corso/website/docs/quickstart.md

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:

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.

Connect to Microsoft 365

Obtaining credentials from Microsoft 365 to allow Corso to run is a one-time operation. Follow the instructions here to obtain the necessary credentials and then make them available to Corso.

$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>"

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>

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>

Create a Corso repository

To create a secure backup location for Corso, you will first need to download Corso. Use the container or native executable to initialize the Corso repository using an encryption passphrase 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.

# Initialize the Corso Repository
$Env:CORSO_PASSPHRASE = "CHANGE-ME-THIS-IS-INSECURE"
.\corso repo init s3 --bucket corso-test

# Initialize the Corso Repository
export CORSO_PASSPHRASE="CHANGE-ME-THIS-IS-INSECURE"
./corso repo init s3 --bucket corso-test

{ `# Create an environment variables file mkdir -p $HOME/.corso cat < $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` }

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.

# Backup your inbox
.\corso backup create exchange --mailbox <your exchange email address>

# Backup your inbox
./corso backup create exchange --mailbox <your exchange email address>

{ # 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> }

:::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:

  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:

# List all Exchange backups
.\corso backup list exchange

# List all Exchange backups
./corso backup list exchange

{ # 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 }

  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 for more advanced filtering options.

# List emails in a selected backup
.\corso backup details exchange --backup <id of your selected backup> --email "*" | Select-Object -First 5

# List emails in a selected backup
./corso backup details exchange --backup <id of your selected backup> --email "*" | head

{ # 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 }

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.

  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.

# Restore a selected email
.\corso restore exchange --backup <id of your selected backup> --email <email message ID>

# Restore a selected email
./corso restore exchange --backup <id of your selected backup> --email <email message ID>

{ # 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> }

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.

  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.

# Restore a folder to its original location
.\corso restore onedrive --backup <id of your selected backup> `
  --folder "/presentations/company_culture" `
  --destination "/" `
  --collisions copy

# Restore a folder to its original location
./corso restore onedrive --backup <id of your selected backup> \
  --folder "/presentations/company_culture" \
  --destination "/" \
  --collisions copy

{ # 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 }

A confirmation of the recovered files will be shown and those files will appear back in their original folder.

  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 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
• Explore Corso backup and restore options for M365 Applications in the Command Line Reference
• Leverage Corso's Advanced Restoration Options