a60d599eaa
Adds the release documentation and reveals all cli commands for groups and teams channelMessages and files support. --- #### Does this PR need a docs update or release note? - [x] ✅ Yes, it's included #### Type of change - [x] 🗺️ Documentation #### Issue(s) * #3988 #### Test Plan - [x] 💪 Manual
344 lines
11 KiB
Markdown
344 lines
11 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
|
|
```
|
|
|
|
## Advanced Restores
|
|
|
|
You can control where your data gets restored, and what happens if restored items would overwrite existing
|
|
ones. Let's restore a folder in OneDrive back to its original location. Since the folder already exists, we can
|
|
tell corso to with duplicate names as copies.
|
|
|
|
<Tabs groupId="os">
|
|
<TabItem value="win" label="Powershell">
|
|
|
|
```powershell
|
|
# Restore a folder to its original location
|
|
.\corso restore onedrive --backup <id of your selected backup> `
|
|
--folder "/presentations/company_culture" `
|
|
--destination "/" `
|
|
--collisions copy
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="unix" label="Linux/macOS">
|
|
|
|
```bash
|
|
# Restore a folder to its original location
|
|
./corso restore onedrive --backup <id of your selected backup> \
|
|
--folder "/presentations/company_culture" \
|
|
--destination "/" \
|
|
--collisions copy
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="docker" label="Docker">
|
|
|
|
<CodeBlock language="bash">{
|
|
`# Restore a folder to its original location
|
|
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> --folder '/presentations/company_culture' \\
|
|
--destination '/' --collisions copy`
|
|
}</CodeBlock>
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
A confirmation of the recovered files will be shown and those files will appear back in their original folder.
|
|
|
|
```text
|
|
ID ItemName ParentPath Size Owner Created Modified
|
|
f43bff59de56 slides 1.ppt /presentations/company_culture 23 kB 2023-07-05T18:37:57Z 2023-07-05T18:37:58Z
|
|
c0de2282e9c7 giftcards.xls /presentations/company_culture 0 B 2023-07-05T18:37:47Z 2023-07-05T18:37:47Z
|
|
```
|
|
|
|
See [here](../setup/restore-options) for more restoration options.
|
|
|
|
## 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 M365 Applications in the [Command Line Reference](../cli/corso)
|
|
* Leverage Corso's [Advanced Restoration Options](../setup/restore-options)
|