eab5510c03
It was easier to confuse `email ID` with `email id` and think it is the email address. This commit makes it clear that it is the id of the email message. --- #### Does this PR need a docs update or release note? - [ ] ✅ Yes, it's included - [ ] 🕐 Yes, but in a later PR - [x] ⛔ No #### Type of change <!--- Please check the type of change your PR introduces: ---> - [ ] 🌻 Feature - [ ] 🐛 Bugfix - [x] 🗺️ Documentation - [ ] 🤖 Supportability/Tests - [ ] 💻 CI/Deployment - [ ] 🧹 Tech Debt/Cleanup #### Issue(s) <!-- Can reference multiple issues. Use one of the following "magic words" - "closes, fixes" to auto-close the Github issue. --> * #<issue> #### Test Plan <!-- How will this be tested prior to merging.--> - [x] 💪 Manual - [ ] ⚡ Unit test - [ ] 💚 E2E
290 lines
8.7 KiB
Markdown
290 lines
8.7 KiB
Markdown
# Quick start
|
|
|
|
import CodeBlock from '@theme/CodeBlock';
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
import TOCInline from '@theme/TOCInline';
|
|
import {Version} from '@site/src/corsoEnv';
|
|
import DownloadBinaries from './setup/_download_binary.md';
|
|
|
|
This quick start guide runs through the steps you can follow to create your first Microsoft 365 backup and restore:
|
|
|
|
<TOCInline toc={toc} maxHeadingLevel={2}/>
|
|
|
|
## Download Corso
|
|
|
|
Download a Corso binary for your platform. If you would like to use a Docker container, the first `docker run` will
|
|
pull the image.
|
|
|
|
<DownloadBinaries />
|
|
|
|
## Connect to Microsoft 365
|
|
|
|
Obtaining credentials from Microsoft 365 to allow Corso to run is a one-time operation. Follow the instructions
|
|
[here](../setup/m365-access) to obtain the necessary credentials and then make them available to Corso.
|
|
|
|
<Tabs groupId="os">
|
|
<TabItem value="win" label="Powershell">
|
|
|
|
```powershell
|
|
$Env:AZURE_CLIENT_ID = "<Application (client) ID for configured app>"
|
|
$Env:AZURE_TENANT_ID = "<Directory (tenant) ID for configured app>"
|
|
$Env:AZURE_CLIENT_SECRET = "<Client secret value>"
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="unix" label="Linux/macOS">
|
|
|
|
```bash
|
|
export AZURE_CLIENT_ID=<Application (client) ID for configured app>
|
|
export AZURE_TENANT_ID=<Directory (tenant) ID for configured app>
|
|
export AZURE_CLIENT_SECRET=<Client secret value>
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="docker" label="Docker">
|
|
|
|
```bash
|
|
export AZURE_CLIENT_ID=<Application (client) ID for configured app>
|
|
export AZURE_TENANT_ID=<Directory (tenant) ID for configured app>
|
|
export AZURE_CLIENT_SECRET=<Client secret value>
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## Create a Corso repository
|
|
|
|
To create a secure backup location for Corso, you will first need to [download Corso](../setup/download).
|
|
Use the container or native executable to initialize the Corso repository using an
|
|
[encryption passphrase](../setup/configuration#environment-variables) and a pre-created S3 bucket (Corso doesn't create
|
|
the bucket if it doesn't exist). The steps below use `corso-test` as the bucket name but, if you are using AWS, you
|
|
will need a different unique name for the bucket.
|
|
|
|
The following commands assume that in addition to the configuration values from the previous step, `AWS_ACCESS_KEY_ID`
|
|
and `AWS_SECRET_ACCESS_KEY` (and `AWS_SESSION_TOKEN` if you are using temporary credentials) are available to the
|
|
Corso binary or container.
|
|
|
|
<Tabs groupId="os">
|
|
<TabItem value="win" label="Powershell">
|
|
|
|
```powershell
|
|
# Initialize the Corso Repository
|
|
$Env:CORSO_PASSPHRASE = "CHANGE-ME-THIS-IS-INSECURE"
|
|
.\corso repo init s3 --bucket corso-test
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="unix" label="Linux/macOS">
|
|
|
|
```bash
|
|
# Initialize the Corso Repository
|
|
export CORSO_PASSPHRASE="CHANGE-ME-THIS-IS-INSECURE"
|
|
./corso repo init s3 --bucket corso-test
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="docker" label="Docker">
|
|
|
|
<!-- vale Vale.Spelling = NO -->
|
|
<!-- markdownlint-disable MD022 MD025 MD033 -->
|
|
|
|
<CodeBlock language="bash">{
|
|
`# Create an environment variables file
|
|
mkdir -p $HOME/.corso
|
|
cat <<EOF > $HOME/.corso/corso.env
|
|
AWS_ACCESS_KEY_ID
|
|
AWS_SECRET_ACCESS_KEY
|
|
AWS_SESSION_TOKEN
|
|
AZURE_CLIENT_ID
|
|
AZURE_TENANT_ID
|
|
AZURE_CLIENT_SECRET
|
|
CORSO_PASSPHRASE
|
|
EOF
|
|
|
|
# Initialize the Corso Repository
|
|
export CORSO_PASSPHRASE="CHANGE-ME-THIS-IS-INSECURE"
|
|
docker run --env-file $HOME/.corso/corso.env \\
|
|
--volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:${Version()} \\
|
|
repo init s3 --bucket corso-test`
|
|
}</CodeBlock>
|
|
|
|
<!-- markdownlint-enable MD022 MD025 MD033 -->
|
|
<!-- vale Vale.Spelling = YES -->
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## Create your first backup
|
|
|
|
Corso can do much more, but you can start by creating a backup of your Exchange mailbox. If it has been a while since
|
|
you initialized the Corso repository, you might need to [connect to it again](../setup/repos#connect-to-a-repository).
|
|
|
|
<Tabs groupId="os">
|
|
<TabItem value="win" label="Powershell">
|
|
|
|
```powershell
|
|
# Backup your inbox
|
|
.\corso backup create exchange --mailbox <your exchange email address>
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="unix" label="Linux/macOS">
|
|
|
|
```bash
|
|
# Backup your inbox
|
|
./corso backup create exchange --mailbox <your exchange email address>
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="docker" label="Docker">
|
|
|
|
<CodeBlock language="bash">{
|
|
`# Backup your inbox
|
|
docker run --env-file $HOME/.corso/corso.env \\
|
|
--volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:${Version()} \\
|
|
backup create exchange --mailbox <your exchange email address>`
|
|
}</CodeBlock>
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
:::note
|
|
Your first backup may take some time if your mailbox is large.
|
|
:::
|
|
|
|
There will be progress indicators as the backup and, on completion, you should see output similar to:
|
|
|
|
```text
|
|
Started At ID Status Resource Owner
|
|
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:
|
|
|
|
<Tabs groupId="os">
|
|
<TabItem value="win" label="Powershell">
|
|
|
|
```powershell
|
|
# List all Exchange backups
|
|
.\corso 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">
|
|
|
|
<CodeBlock language="bash">{
|
|
`# List all Exchange backups
|
|
docker run --env-file $HOME/.corso/corso.env \\
|
|
--volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:${Version()} \\
|
|
backup list exchange`
|
|
}</CodeBlock>
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
```text
|
|
Started At ID Status Resource Owner
|
|
2022-10-20T18:28:53Z d8cd833a-fc63-4872-8981-de5c08e0661b Completed (0 errors) alice@contoso.com
|
|
2022-10-20T18:40:45Z 391ceeb3-b44d-4365-9a8e-8a8e1315b565 Completed (0 errors) alice@contoso.com
|
|
...
|
|
```
|
|
|
|
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.
|
|
|
|
<Tabs groupId="os">
|
|
<TabItem value="win" label="Powershell">
|
|
|
|
```powershell
|
|
# List emails in a selected backup
|
|
.\corso backup details exchange --backup <id of your selected backup> --email "*" | Select-Object -First 5
|
|
```
|
|
|
|
</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">
|
|
|
|
<CodeBlock language="bash">{
|
|
`# List emails in a selected backup
|
|
docker run --env-file $HOME/.corso/corso.env \\
|
|
--volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:${Version()} \\
|
|
backup details exchange --backup <id of your selected backup> --email "*" | head`
|
|
}</CodeBlock>
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
The output from the command above should display a list of any matching emails. Note the ID
|
|
of the email you would like to use for testing restore.
|
|
|
|
```text
|
|
ID 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
|
|
...
|
|
```
|
|
|
|
To restore the selected email, use the following command.
|
|
|
|
<Tabs groupId="os">
|
|
<TabItem value="win" label="Powershell">
|
|
|
|
```powershell
|
|
# Restore a selected email
|
|
.\corso restore exchange --backup <id of your selected backup> --email <email message ID>
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="unix" label="Linux/macOS">
|
|
|
|
```bash
|
|
# Restore a selected email
|
|
./corso restore exchange --backup <id of your selected backup> --email <email message ID>
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="docker" label="Docker">
|
|
|
|
<CodeBlock language="bash">{
|
|
`# Restore a selected email
|
|
docker run --env-file $HOME/.corso/corso.env \\
|
|
--volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:${Version()} \\
|
|
restore exchange --backup <id of your selected backup> --email <email message ID>`
|
|
}</CodeBlock>
|
|
|
|
</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
|
|
ID Sender Subject Received
|
|
360bf6840396 phish@contoso.info Re: Request for Apple/Amazon gift cards 2022-10-18T02:27:47Z
|
|
```
|
|
|
|
## Read more
|
|
|
|
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)
|