larryh/corso
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Edit Quickstart backup and restore sections (#1263)

Browse Source 
## Description

- Adds command tabs for back and restore
- Reorder Exchange CLI restore page
- Minor consistency tweaks
- Fix subsection headers
- Fix restore command
- Address TODO in repos page

## Type of change

- [x] 🗺️ Documentation
This commit is contained in:
Niraj Tolia 2022-10-20 15:59:01 -07:00 committed by GitHub
parent 1cad17bfc7
commit 268e12d14f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 124 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
docs/docs/quickstart.md
View File

@ -10,9 +10,8 @@ This quick start guide runs through the steps you can follow to create your firs
## Connecting to Microsoft 365 ## Connecting to Microsoft 365
Obtaining credentials from Microsoft 365 to allow Corso to run is a moderately involved one-time operation. Obtaining credentials from Microsoft 365 to allow Corso to run is a one-time operation. Follow the instructions
Follow the instructions [here](setup/m365_access) to obtain the necessary credentials and then make them available to [here](setup/m365_access) to obtain the necessary credentials and then make them available to Corso.
Corso.
<Tabs groupId="os"> <Tabs groupId="os">
<TabItem value="win" label="Powershell"> <TabItem value="win" label="Powershell">
@ -88,8 +87,8 @@ The following commands assume that all the configuration values from the previou
mkdir -p $HOME/.corso mkdir -p $HOME/.corso
cat <<EOF > $HOME/.corso/corso.env cat <<EOF > $HOME/.corso/corso.env
CORSO_PASSPHRASE CORSO_PASSPHRASE
AZURE_TENANT_ID
AZURE_CLIENT_ID AZURE_CLIENT_ID
AZURE_TENANT_ID
AZURE_CLIENT_SECRET AZURE_CLIENT_SECRET
AWS_ACCESS_KEY_ID AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY AWS_SECRET_ACCESS_KEY
@ -106,7 +105,7 @@ The following commands assume that all the configuration values from the previou
</TabItem> </TabItem>
</Tabs> </Tabs>
## Creating your first backup ## Create your first backup
Corso can do much more, but you can start by creating a backup of your Exchange mailbox. To do this, first ensure that Corso can do much more, but you can start by creating a backup of your Exchange mailbox. To do this, first ensure that
you are connected with the repository and then backup your own Exchange mailbox. you are connected with the repository and then backup your own Exchange mailbox.
@ -155,50 +154,137 @@ you are connected with the repository and then backup your own Exchange mailbox.
Your first backup may take some time if your mailbox is large. Your first backup may take some time if your mailbox is large.
::: :::
## Restoring an email There will be progress indicators as the backup and, on completion, you should see output similar to:
Now lets explore how you can restore data from one of your backups. ```text
Started At ID Status Selectors
2022-10-20T18:28:53Z d8cd833a-fc63-4872-8981-de5c08e0661b Completed (0 errors) alice@contoso.com
```
## Restore an email
Now, lets explore how you can restore data from one of your backups.
You can see all Exchange backups available with the following command: You can see all Exchange backups available with the following command:
```bash <Tabs groupId="os">
$ docker run -e CORSO_PASSPHRASE \ <TabItem value="win" label="Powershell">
--env-file ~/.corso/corso.env \
-v ~/.corso:/app/corso corso/corso:<release tag> \
backup list exchange
```powershell
# List all Exchange backups
.\corso.exe backup list exchange
```
</TabItem>
<TabItem value="unix" label="Linux/macOS">
```bash
# List all Exchange backups
corso backup list exchange
```
</TabItem>
<TabItem value="docker" label="Docker">
```bash
# List all Exchange backups
docker run --env-file $HOME/.corso/corso.env \
--volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:latest \
backup list exchange
```
</TabItem>
</Tabs>
```text
Started At ID Status Selectors Started At ID Status Selectors
2022-09-09T42:27:16Z 72d12ef6-420a-15bd-c862-fd7c9023a014 Completed (0 errors) alice@example.com 2022-10-20T18:28:53Z d8cd833a-fc63-4872-8981-de5c08e0661b Completed (0 errors) alice@contoso.com
2022-10-10T19:46:43Z 41e93db7-650d-44ce-b721-ae2e8071c728 Completed (0 errors) alice@example.com 2022-10-20T18:40:45Z 391ceeb3-b44d-4365-9a8e-8a8e1315b565 Completed (0 errors) alice@contoso.com
``` ```
Select one of the available backups and search through its contents. Next, select one of the available backups and list all backed up emails. See
[here](cli/corso_backup_details_exchange) for more advanced filtering options.
```bash <Tabs groupId="os">
$ docker run -e CORSO_PASSPHRASE \ <TabItem value="win" label="Powershell">
--env-file ~/.corso/corso.env \
-v ~/.corso:/app/corso corso/corso:<release tag> \ ```powershell
backup details exchange \ # List emails in a selected backup
--backup <id of your selected backup> \ .\corso.exe backup details exchange --backup <id of your selected backup> --email "*" | Select-Object -First 5
--user <your exchange email address> \ ```
--email-subject <portion of subject of email you want to recover>
</TabItem>
<TabItem value="unix" label="Linux/macOS">
```bash
# List emails in a selected backup
corso backup details exchange --backup <id of your selected backup> --email "*" | head
```
</TabItem>
<TabItem value="docker" label="Docker">
```bash
# List emails in a selected backup
docker run --env-file $HOME/.corso/corso.env \
--volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:latest \
backup details exchange --backup <id of your selected backup> --email "*" | head
```
</TabItem>
</Tabs>
The output from the command above should display a list of any matching emails. Note the reference
of the email you would like to use for testing restore.
```text
Reference Sender Subject Received
360bf6840396 phish@contoso.info Re: Request for Apple/Amazon gift cards 2022-10-18T02:27:47Z
84dbad89b9f5 ravi@cohovineyard.com Come join us! 2022-10-19T06:12:08Z
...
``` ```
The output from the command above should display a list of any matching emails. Note the ID When you are ready to restore the selected email, use the following command.
of the one to use for testing restore.
When you are ready to restore, use the following command: <Tabs groupId="os">
<TabItem value="win" label="Powershell">
```bash ```powershell
$ docker run -e CORSO_PASSPHRASE \ # Restore a selected email
--env-file ~/.corso/corso.env \ .\corso.exe restore exchange --backup <id of your selected backup> --email <email reference>
-v ~/.corso:/app/corso corso/corso:<release tag> \ ```
backup details exchange \
--backup <id of your selected backup> \ </TabItem>
--user <your exchange email address> \ <TabItem value="unix" label="Linux/macOS">
--email <id of your selected email>
```bash
# Restore a selected email
corso restore exchange --backup <id of your selected backup> --email <email reference>
```
</TabItem>
<TabItem value="docker" label="Docker">
```bash
# Restore a selected email
docker run --env-file $HOME/.corso/corso.env \
--volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:latest \
restore exchange --backup <id of your selected backup> --email <email reference>
```
</TabItem>
</Tabs>
A confirmation of the recovered email will be shown and the email will appear in a new mailbox folder named `Corso_Restore_DD-MMM-YYYY_HH:MM:SS`.
```text
Reference Sender Subject Received
360bf6840396 phish@contoso.info Re: Request for Apple/Amazon gift cards 2022-10-18T02:27:47Z
``` ```
You can now find the recovered email in a mailbox folder named `Corso_Restore_DD-MMM-YYYY_HH:MM:SS`. ## Next Steps
You are now ready to explore the [Command Line Reference](cli/corso) and try everything that Corso can do. The above tutorial only scratches the surface for Corso's capabilities. We encourage you to dig deeper by:
* Learning about [Corso concepts and setup](setup/concepts)
* Explore Corso backup and restore options for Exchange and Onedrive in the [Command Line Reference](cli/corso)

6
docs/docs/setup/repos.md
View File

@ -22,11 +22,7 @@ Depending on community interest, Corso may support other object storage backends
Before setting you your Corso S3 repository, the following prerequisites must be met: Before setting you your Corso S3 repository, the following prerequisites must be met:
* S3 bucket for the repository already exists. Corso won't create it for you. * S3 bucket for the repository already exists. Corso won't create it for you.
* You have access to credentials for a user or an IAM role that represent the following permissions * You have access to credentials for a user or an IAM role that has the following permissions:
<!-- vale proselint.Annotations = NO -->
**TODO: Verify if these permissions are correct?
<!-- vale proselint.Annotations = YES -->
```json ```json
{ {

3
docs/sidebars.js
View File

@ -33,9 +33,8 @@ const sidebars = {
items: [ items: [
'cli/corso_repo_init_s3', 'cli/corso_repo_connect_s3', 'cli/corso_repo_init_s3', 'cli/corso_repo_connect_s3',
'cli/corso_backup_create_exchange', 'cli/corso_backup_list_exchange', 'cli/corso_backup_details_exchange', 'cli/corso_backup_create_exchange', 'cli/corso_backup_list_exchange', 'cli/corso_backup_details_exchange',
'cli/corso_restore_exchange',
'cli/corso_backup_create_onedrive', 'cli/corso_backup_list_onedrive', 'cli/corso_backup_details_onedrive', 'cli/corso_backup_create_onedrive', 'cli/corso_backup_list_onedrive', 'cli/corso_backup_details_onedrive',
'cli/corso_restore_onedrive', 'cli/corso_restore_exchange', 'cli/corso_restore_onedrive',
'cli/corso_env' 'cli/corso_env'
] ]
}, },