Skip to main content

Quick start

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.

$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest `
  -Uri https://github.com/alcionai/corso/releases/download/v0.19.0/corso_v0.19.0_Windows_x86_64.zip `
  -UseBasicParsing -Outfile corso_v0.19.0_Windows_x86_64.zip
Expand-Archive .\corso_v0.19.0_Windows_x86_64.zip

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

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

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

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>

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

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: