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

Add new version to versioned docs

Browse Source
This commit is contained in:
meain 2022-12-06 10:51:33 +00:00 committed by GitHub
parent bbfe879925
commit aa37a1dd2c
30 changed files with 1915 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
website/versioned_docs/version-testing/cli/corso_backup_create_exchange.md Normal file
View File

@ -0,0 +1,43 @@
---
title: corso backup create exchange
hide_title: true
---
## corso backup create exchange
Backup M365 Exchange service data
```bash
corso backup create exchange --user <userId or email> | '*' [flags]
```
### Examples
```bash
# Backup all Exchange data for Alice
corso backup create exchange --user alice@example.com
# Backup only Exchange contacts for Alice and Bob
corso backup create exchange --user alice@example.com,bob@example.com --data contacts
# Backup all Exchange data for all M365 users
corso backup create exchange --user '*'
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--user`||``|Backup Exchange data by user ID; accepts '*' to select all users|
|`--data`||``|Select one or more types of data to backup: email, contacts, or events|
|`--help`|`-h`|`false`|help for exchange|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

42
website/versioned_docs/version-testing/cli/corso_backup_create_onedrive.md Normal file
View File

@ -0,0 +1,42 @@
---
title: corso backup create onedrive
hide_title: true
---
## corso backup create onedrive
Backup M365 OneDrive service data
```bash
corso backup create onedrive --user <userId or email> | '*' [flags]
```
### Examples
```bash
# Backup OneDrive data for Alice
corso backup create onedrive --user alice@example.com
# Backup OneDrive for Alice and Bob
corso backup create onedrive --user alice@example.com,bob@example.com
# Backup all OneDrive data for all M365 users
corso backup create onedrive --user '*'
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--user`||``|Backup OneDrive data by user ID; accepts '*' to select all users. <div class='required'>Required</div>|
|`--help`|`-h`|`false`|help for onedrive|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

36
website/versioned_docs/version-testing/cli/corso_backup_delete_exchange.md Normal file
View File

@ -0,0 +1,36 @@
---
title: corso backup delete exchange
hide_title: true
---
## corso backup delete exchange
Delete backed-up M365 Exchange service data
```bash
corso backup delete exchange --backup <backupId> [flags]
```
### Examples
```bash
# Delete Exchange backup with ID 1234abcd-12ab-cd34-56de-1234abcd
corso backup delete exchange --backup 1234abcd-12ab-cd34-56de-1234abcd
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--backup`|||ID of the backup to delete. <div class='required'>Required</div>|
|`--help`|`-h`|`false`|help for exchange|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

36
website/versioned_docs/version-testing/cli/corso_backup_delete_onedrive.md Normal file
View File

@ -0,0 +1,36 @@
---
title: corso backup delete onedrive
hide_title: true
---
## corso backup delete onedrive
Delete backed-up M365 OneDrive service data
```bash
corso backup delete onedrive --backup <backupId> [flags]
```
### Examples
```bash
# Delete OneDrive backup with ID 1234abcd-12ab-cd34-56de-1234abcd
corso backup delete onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--backup`|||ID of the backup to delete. <div class='required'>Required</div>|
|`--help`|`-h`|`false`|help for onedrive|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

65
website/versioned_docs/version-testing/cli/corso_backup_details_exchange.md Normal file
View File

@ -0,0 +1,65 @@
---
title: corso backup details exchange
hide_title: true
---
## corso backup details exchange
Shows the details of a M365 Exchange service backup
```bash
corso backup details exchange --backup <backupId> [flags]
```
### Examples
```bash
# Explore Alice's items in backup 1234abcd-12ab-cd34-56de-1234abcd
corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --user alice@example.com
# Explore Alice's emails with subject containing "Hello world" in folder "Inbox" from a specific backup
corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user alice@example.com --email-subject "Hello world" --email-folder Inbox
# Explore Bobs's events occurring after start of 2022 from a specific backup
corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user bob@example.com --event-starts-after 2022-01-01T00:00:00
# Explore Alice's contacts with name containing Andy from a specific backup
corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user alice@example.com --contact-name Andy
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--backup`|||ID of the backup to explore. <div class='required'>Required</div>|
|`--user`||``|Select backup details by user ID; accepts '*' to select all users.|
|`--email`||``|Select backup details for emails by email ID; accepts '*' to select all emails.|
|`--email-folder`||``|Select backup details for emails within a folder; accepts '*' to select all email folders.|
|`--email-subject`|||Select backup details for emails with a subject containing this value.|
|`--email-sender`|||Select backup details for emails from a specific sender.|
|`--email-received-after`|||Select backup details for emails received after this datetime.|
|`--email-received-before`|||Select backup details for emails received before this datetime.|
|`--event`||``|Select backup details for events by event ID; accepts '*' to select all events.|
|`--event-calendar`||``|Select backup details for events under a calendar; accepts '*' to select all events.|
|`--event-subject`|||Select backup details for events with a subject containing this value.|
|`--event-organizer`|||Select backup details for events from a specific organizer.|
|`--event-recurs`|||Select backup details for recurring events. Use `--event-recurs false` to select non-recurring events.|
|`--event-starts-after`|||Select backup details for events starting after this datetime.|
|`--event-starts-before`|||Select backup details for events starting before this datetime.|
|`--contact`||``|Select backup details for contacts by contact ID; accepts '*' to select all contacts.|
|`--contact-folder`||``|Select backup details for contacts within a folder; accepts '*' to select all contact folders.|
|`--contact-name`|||Select backup details for contacts whose contact name contains this value.|
|`--help`|`-h`|`false`|help for exchange|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

50
website/versioned_docs/version-testing/cli/corso_backup_details_onedrive.md Normal file
View File

@ -0,0 +1,50 @@
---
title: corso backup details onedrive
hide_title: true
---
## corso backup details onedrive
Shows the details of a M365 OneDrive service backup
```bash
corso backup details onedrive --backup <backupId> [flags]
```
### Examples
```bash
# Explore Alice's files from backup 1234abcd-12ab-cd34-56de-1234abcd
corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd --user alice@example.com
# Explore Alice or Bob's files with name containing "Fiscal 22" in folder "Reports"
corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user alice@example.com,bob@example.com --file-name "Fiscal 22" --folder "Reports"
# Explore Alice's files created before end of 2015 from a specific backup
corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user alice@example.com --file-created-before 2015-01-01T00:00:00
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--backup`|||ID of the backup to explore. <div class='required'>Required</div>|
|`--folder`||``|Select backup details by OneDrive folder; defaults to root.|
|`--file`||``|Select backup details by file name or ID.|
|`--file-created-after`|||Select backup details for files created after this datetime.|
|`--file-created-before`|||Select backup details for files created before this datetime.|
|`--file-modified-after`|||Select backup details for files modified after this datetime.|
|`--file-modified-before`|||Select backup details for files modified before this datetime.|
|`--help`|`-h`|`false`|help for onedrive|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

39
website/versioned_docs/version-testing/cli/corso_backup_details_sharepoint.md Normal file
View File

@ -0,0 +1,39 @@
---
title: corso backup details sharepoint
hide_title: true
---
## corso backup details sharepoint
Shows the details of a M365 SharePoint service backup
```bash
corso backup details sharepoint --backup <backupId> [flags]
```
### Examples
```bash
# Explore <site>'s files from backup 1234abcd-12ab-cd34-56de-1234abcd
corso backup details sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd --site <site_id>
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--backup`|||ID of the backup to retrieve.|
|`--library`||``|Select backup details by Library name.|
|`--library-item`||``|Select backup details by library item name or ID.|
|`--help`|`-h`|`false`|help for sharepoint|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

29
website/versioned_docs/version-testing/cli/corso_backup_list_exchange.md Normal file
View File

@ -0,0 +1,29 @@
---
title: corso backup list exchange
hide_title: true
---
## corso backup list exchange
List the history of M365 Exchange service backups
```bash
corso backup list exchange [flags]
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--backup`|||ID of the backup to retrieve.|
|`--help`|`-h`|`false`|help for exchange|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

29
website/versioned_docs/version-testing/cli/corso_backup_list_onedrive.md Normal file
View File

@ -0,0 +1,29 @@
---
title: corso backup list onedrive
hide_title: true
---
## corso backup list onedrive
List the history of M365 OneDrive service backups
```bash
corso backup list onedrive [flags]
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--backup`|||ID of the backup to retrieve.|
|`--help`|`-h`|`false`|help for onedrive|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

28
website/versioned_docs/version-testing/cli/corso_env.md Normal file
View File

@ -0,0 +1,28 @@
---
title: corso env
hide_title: true
---
## corso env
A guide to using environment variables in Corso.
```bash
corso env [flags]
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--help`|`-h`|`false`|help for env|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

46
website/versioned_docs/version-testing/cli/corso_repo_connect_s3.md Normal file
View File

@ -0,0 +1,46 @@
---
title: corso repo connect s3
hide_title: true
---
## corso repo connect s3
Ensures a connection to an existing S3 repository.
```bash
corso repo connect s3 --bucket <bucket> [flags]
```
### Examples
```bash
# Connect to a Corso repo in AWS S3 bucket named "my-bucket"
corso repo connect s3 --bucket my-bucket
# Connect to a Corso repo in AWS S3 bucket named "my-bucket" using a prefix
corso repo connect s3 --bucket my-bucket --prefix my-prefix
# Connect to a Corso repo in an S3 compliant storage provider
corso repo connect s3 --bucket my-bucket --endpoint https://my-s3-server-endpoint
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--bucket`|||Name of S3 bucket for repo. <div class='required'>Required</div>|
|`--prefix`|||Repo prefix within bucket.|
|`--endpoint`||`s3.amazonaws.com`|S3 service endpoint.|
|`--disable-tls`||`false`|Disable TLS (HTTPS)|
|`--disable-tls-verification`||`false`|Disable TLS (HTTPS) certificate verification.|
|`--help`|`-h`|`false`|help for s3|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

46
website/versioned_docs/version-testing/cli/corso_repo_init_s3.md Normal file
View File

@ -0,0 +1,46 @@
---
title: corso repo init s3
hide_title: true
---
## corso repo init s3
Bootstraps a new S3 repository and connects it to your m365 account.
```bash
corso repo init s3 --bucket <bucket> [flags]
```
### Examples
```bash
# Create a new Corso repo in AWS S3 bucket named "my-bucket"
corso repo init s3 --bucket my-bucket
# Create a new Corso repo in AWS S3 bucket named "my-bucket" using a prefix
corso repo init s3 --bucket my-bucket --prefix my-prefix
# Create a new Corso repo in an S3 compliant storage provider
corso repo init s3 --bucket my-bucket --endpoint https://my-s3-server-endpoint
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--bucket`|||Name of S3 bucket for repo. <div class='required'>Required</div>|
|`--prefix`|||Repo prefix within bucket.|
|`--endpoint`||`s3.amazonaws.com`|S3 service endpoint.|
|`--disable-tls`||`false`|Disable TLS (HTTPS)|
|`--disable-tls-verification`||`false`|Disable TLS (HTTPS) certificate verification.|
|`--help`|`-h`|`false`|help for s3|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

64
website/versioned_docs/version-testing/cli/corso_restore_exchange.md Normal file
View File

@ -0,0 +1,64 @@
---
title: corso restore exchange
hide_title: true
---
## corso restore exchange
Restore M365 Exchange service data
```bash
corso restore exchange --backup <backupId> [flags]
```
### Examples
```bash
# Restore emails with ID 98765abcdef and 12345abcdef from a specific backup
corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --email 98765abcdef,12345abcdef
# Restore Alice's emails with subject containing "Hello world" in "Inbox" from a specific backup
corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user alice@example.com --email-subject "Hello world" --email-folder Inbox
# Restore Bobs's entire calendar from a specific backup
corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user bob@example.com --event-calendar Calendar
# Restore contact with ID abdef0101 from a specific backup
corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --contact abdef0101
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--backup`|||ID of the backup to restore. <div class='required'>Required</div>|
|`--user`||``|Restore data by user ID; accepts '*' to select all users.|
|`--email`||``|Restore emails by ID; accepts '*' to select all emails.|
|`--email-folder`||``|Restore emails within a folder; accepts '*' to select all email folders.|
|`--email-subject`|||Restore emails with a subject containing this value.|
|`--email-sender`|||Restore emails from a specific sender.|
|`--email-received-after`|||Restore emails received after this datetime.|
|`--email-received-before`|||Restore emails received before this datetime.|
|`--event`||``|Restore events by event ID; accepts '*' to select all events.|
|`--event-calendar`||``|Restore events under a calendar; accepts '*' to select all event calendars.|
|`--event-subject`|||Restore events with a subject containing this value.|
|`--event-organizer`|||Restore events from a specific organizer.|
|`--event-recurs`|||Restore recurring events. Use `--event-recurs false` to restore non-recurring events.|
|`--event-starts-after`|||Restore events starting after this datetime.|
|`--event-starts-before`|||Restore events starting before this datetime.|
|`--contact`||``|Restore contacts by contact ID; accepts '*' to select all contacts.|
|`--contact-folder`||``|Restore contacts within a folder; accepts '*' to select all contact folders.|
|`--contact-name`|||Restore contacts whose contact name contains this value.|
|`--help`|`-h`|`false`|help for exchange|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

51
website/versioned_docs/version-testing/cli/corso_restore_onedrive.md Normal file
View File

@ -0,0 +1,51 @@
---
title: corso restore onedrive
hide_title: true
---
## corso restore onedrive
Restore M365 OneDrive service data
```bash
corso restore onedrive --backup <backupId> [flags]
```
### Examples
```bash
# Restore file with ID 98765abcdef
corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd --file 98765abcdef
# Restore Alice's file named "FY2021 Planning.xlsx in "Documents/Finance Reports" from a specific backup
corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user alice@example.com --file "FY2021 Planning.xlsx" --folder "Documents/Finance Reports"
# Restore all files from Bob's folder that were created before 2020 when captured in a specific backup
corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd
--user bob@example.com --folder "Documents/Finance Reports" --file-created-before 2020-01-01T00:00:00
```
### Flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--backup`|||ID of the backup to restore. <div class='required'>Required</div>|
|`--user`||``|Restore data by user ID; accepts '*' to select all users.|
|`--folder`||``|Restore items by OneDrive folder; defaults to root|
|`--file`||``|Restore items by file name or ID|
|`--file-created-after`|||Restore files created after this datetime|
|`--file-created-before`|||Restore files created before this datetime|
|`--file-modified-after`|||Restore files modified after this datetime|
|`--file-modified-before`|||Restore files modified before this datetime|
|`--help`|`-h`|`false`|help for onedrive|
### Global and inherited flags
|Flag|Short|Default|Help|
|:----|:-----|:-------|:----|
|`--config-file`||`$HOME/.corso.toml`|config file location (default is $HOME/.corso.toml)|
|`--hide-progress`||`false`|turn off the progress bar displays|
|`--json`||`false`|output data in JSON format|
|`--log-level`||`info`|set the log level to debug|info|warn|error|
|`--no-stats`||`false`|disable anonymous usage statistics gathering|
|`--retain-progress`||`false`|retain the progress bar displays after completion|

75
website/versioned_docs/version-testing/developers/build.md Normal file
View File

@ -0,0 +1,75 @@
# Building Corso
## Binary
### Building locally
Corso is a Go project, and you can build it with `go build` from `<repo root>/src`
if you have Go installed on your system.
```bash
# run from within `./src`
go build -o corso
```
:::info
If you don't have Go available, you can find installation instructions [here](https://go.dev/doc/install)
:::
This will generate a binary named `corso` in the directory where you run the build.
### Building via Docker
For convenience, the Corso build tooling is containerized. To take advantage, you need
[Docker](https://www.docker.com/) installed on your machine.
To build Corso via docker, use the following command from the root of your repo:
```bash
./build/build.sh binary
```
By default, we will build for your current platform. You can pass in
all the architectures/platforms you would like to build it for using
the `--platforms` flag as a comma separated list. For example, if you
would like to build `amd64` and `arm64` versions for Linux, you can
run the following command:
```bash
./build/build.sh binary --platforms linux/amd64,linux/arm64
```
Once built, the resulting binaries will be available in `<repo root>/bin` for all the different platforms you specified.
## Container Image
If you prefer to build Corso as a container image, use the following command instead:
```bash
# Use --help to see all available options
./build/build.sh image
```
:::note
`Dockerfile` used to build the image is available at [`build/Dockerfile`](https://github.com/alcionai/corso/blob/main/build/Dockerfile)
:::
Similar to binaries, we build your a container image for your current
platform by default, but you can change it by explicitly passing in
the platforms that you would like to build for.
In addition, you can optionally pass the tag that you would like to
apply for the image using `--tag` option.
For example, you can use the following command to create a `arm64`
image with the tag `ghcr.io/alcionai/corso:latest`, you can run:
```bash
./build/build.sh image --platforms linux/arm64 --tag ghcr.io/alcionai/corso:latest
```
:::info
If you run into any issues with building cross platform images, make
sure to follow the instructions on [Docker
docs](https://docs.docker.com/build/building/multi-platform/) to setup
the build environment for Multi-platform images.
:::

209
website/versioned_docs/version-testing/developers/linters.md Normal file
View File

@ -0,0 +1,209 @@
# Corso linters
Corso uses the golangci-lint GitHub action to run linters on every PR to `main`.
This helps reduce the cognitive load on reviewers and can lead to better
reviewer comments as they don’t get caught up with formatting issues.
## Installing golangci-lint locally
You can install a local version of the linter Corso uses on any platform and
there's also a docker container available. Instructions for installation are
available on the golangci-lint
[website](https://golangci-lint.run/usage/install/#local-installation). The
version that you install should match the version the GitHub workflow uses to
avoid failures even after running locally. The current version in use can be
[found](https://github.com/alcionai/corso/blob/main/.github/workflows/lint.yml#L55)
in `.github/worflows/lint.yaml`.
## Running the linter
You can run the linter manually or with the `Makefile` in the repository. Running with
the `Makefile` will also ensure you have the proper version of golangci-lint
installed.
### Running with the `Makefile`
There’s a `Makefile` in the corso/src that will automatically check if the proper
golangci-lint version is installed and run it. This make rule can be run
with `make lint`. If golangci-lint isn't installed locally or the wrong version
is present it will tell you what version it expects along with a link to the
installation page.
### Running manually
You can run golangci-lint manually by executing `golangci-lint run` in the corso/src
directory. This will automatically use corso's `.golangci.yml` configuration.
## Adding exceptions for lint errors
Sometimes the linter will report an issue but it's not something that you can or
should fix. In those cases there are two ways to add a linter exception:
### Single exception via comment
Adding a comment on the line before (or sometimes the offending line) with the
form `//nolint:<linter-name>` will ignore a single error. `<linter-name>` must
be replaced with the name of the linter that produced the report. Note there’s
no space between the `//` and `nolint`. Having a space between the two may
result in the linter still reporting that line.
### Global exception
The `golangci.yml` file has a list of issues that are ignored in the whole
project. These should be as targeted as possible to avoid silencing other lint
errors that aren't related to the one in question. The golangci-lint
[issues configuration page](https://golangci-lint.run/usage/configuration/#issues-configuration)
has some information on this, but it's also useful to look at
[existing exceptions](https://github.com/alcionai/corso/blob/main/src/.golangci.yml)
in the repository under the `issues` section.
The configuration file allows for regex in the text property, so it’s useful to include
the linter/rule that triggered the message. This ensures the lint error is only
ignored for that linter. Combining the linter/rule with the error message text
specific to that error also helps minimize collisions with other lint errors.
## Working with the linters
Some of the enabled linters, like `wsl`, are picky about how code is arranged.
This section provides some tips on how to organize code to reduce lint errors.
### `wsl`
`wsl` is a linter that requires blank lines in parts of the code. It helps make
the codebase uniform and ensures the code doesn't feel too compact.
#### Short-assignments versus var declarations
Go allows declaring and assigning to a variable with either short-assignments
(`x := 42`) or var assignments (`var x = 42`). `wsl` doesn't allow
grouping these two types of variable declarations together. To work around this,
you can convert all your declarations to one type or the other. Converting to
short-assignments only works if the types in question have accessible and
suitable default values.
For example, the mixed set of declarations and assignments:
```go
var err error
x := 42
```
should be changed to the following because using a short-assignment for type
`error` is cumbersome.
```go
var (
err error
x = 42
)
```
#### Post-increment and assignments
`wsl` doesn't allow statements before an assignment without a blank line
separating the two. Post-increment operators (e.x. `x++`) count as statements
instead of assignments and may cause `wsl` to report an error. You can avoid
this by moving the post-increment operator to be after the assignment instead of
before it if the assignment doesn't depend on the increment operation.
For example, the snippet:
```go
x++
found = true
```
should be converted to:
```go
found = true
x++
```
#### Functions using recently assigned values
`wsl` allows functions immediately after assignments, but only if the function
uses the assigned value. This requires an ordering for assignments and
function calls.
For example, the following code
```go
a := 7
b := 42
foo(a)
```
should be changed to
```go
b := 42
a := 7
foo(a)
```
If both the second assignment and function call depend on the value of the first
assignment then the assignments and function call must be separated by a blank
line.
```go
a := 7
b := a + 35
foo(a, b)
```
#### Function calls and checking returned error values
One of the other linters expects error checks to follow assignments to the error
variable without blank lines separating the two. One the other hand, `wsl` has
requirements about what statements can be mixed with assignments. To work
around this, you should separate assignments that involve an error from other
assignments. For example
```go
a := 7
b := 42
c, err := foo()
if err != nil {
...
}
```
should be changed to
```go
a := 7
b := 42
c, err := foo()
if err != nil {
...
}
```
## Common problem linters
Some linter messages aren't clear about what the issue is. Here's common
cryptic messages how you can fix the problems the linters flag.
Each subsection also includes the version of golangci-lint it applies to and the
linter in question.
### `gci` `Expected 's', Found 'a' at file.go`
This applies to golangci-lint v1.45.2 for the `gci` linter and is due to an import
ordering issue. It occurs because imports in the file aren't grouped according
to the import rules for Corso. Corso code should have three distinct import
groups: system imports, third party imports, and imports of other Corso packaged
(see the example below). Typically the cause of a `gci` lint error is a Corso import in the
block for third party libraries.
```go
import (
"time"
"github.com/kopia/kopia"
"github.com/alcionai/corso/pkg/selector"
)
```

58
website/versioned_docs/version-testing/developers/testing.md Normal file
View File

@ -0,0 +1,58 @@
# Running tests locally
## Prerequisites
- Set `CORSO_PASSPHRASE` environment variable
```bash
export CORSO_PASSPHRASE=<some password>
```
- Set AWS credential (needed for tests that use S3) environment variables
```bash
export AWS_ACCESS_KEY_ID="...."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="..."
```
- Create a config file with the S3 bucket used for testing
```toml
bucket = '<bucket name>'
```
- Set `CORSO_TEST_CONFIG_FILE` to use the test config file
```bash
export CORSO_TEST_CONFIG_FILE=~/.corso_test.toml
```
- Set M365 Credentials environment variables
> You can find more information on how to get these values in our [M365 docs](../../setup/m365_access/).
```bash
export AZURE_CLIENT_ID=<id>
export AZURE_CLIENT_SECRET=<secret>
export AZURE_TENANT_ID=<tenant>
```
## Running tests
Standard `go test ./...` will run unit tests
Integration style tests run when enabled by setting the appropriate environment variable.
For example, `CORSO_CI_TESTS=true go test ./...`
The complete list of environment constants is available at
`.../src/internal/tester/integration_runners.go`.
## Advanced options
- To override the M365 user for tests, use `CORSO_M365_TEST_USER_ID`
```bash
export CORSO_M365_TEST_USER_ID="..."
```

17
website/versioned_docs/version-testing/intro.md Normal file
View File

@ -0,0 +1,17 @@
# Introduction
## Overview
Corso is the first open-source tool that aims to assist IT admins with the critical task of protecting their
Microsoft 365 data. It provides a reliable, secure, and efficient data protection engine. Admins decide where to store
the backup data and have the flexibility to perform backups of their desired service through an intuitive interface.
As Corso evolves, it can become a great building block for more complex data protection workflows.
Corso supports M365 Exchange, OneDrive, SharePoint, and Teams. Coverage for more services, possibly
beyond M365, will expand based on the interest and needs of the community.
## Getting started
You can follow the [Quick Start](../quickstart) guide for an end-to-end Corso walk through. Alternatively, follow
the instructions in the [Corso Setup](../setup/concepts) section to dive into the details on how to configure and
run Corso.

289
website/versioned_docs/version-testing/quickstart.md Normal file
View File

@ -0,0 +1,289 @@
# 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 --user <your exchange email address>
```
</TabItem>
<TabItem value="unix" label="Linux/macOS">
```bash
# Backup your inbox
./corso backup create exchange --user <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 --user <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 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:
<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 Selectors
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 ID>
```
</TabItem>
<TabItem value="unix" label="Linux/macOS">
```bash
# Restore a selected email
./corso restore exchange --backup <id of your selected backup> --email <email 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 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)

55
website/versioned_docs/version-testing/setup/_download_binary.md Normal file
View File

@ -0,0 +1,55 @@
<!-- markdownlint-disable MD034 MD041 -->
<!-- vale Vale.Spelling = NO -->
import CodeBlock from '@theme/CodeBlock';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import {Version} from '@site/src/corsoEnv';
<Tabs groupId="download">
<TabItem value="win" label="Windows (Powershell)">
<CodeBlock language="powershell">{
`Invoke-WebRequest \`
-Uri https://github.com/alcionai/corso/releases/download/${Version()}/corso_${Version()}_Windows_x86_64.zip \`
-UseBasicParsing -Outfile corso_${Version()}_Windows_x86_64.zip
Expand-Archive .\\corso_${Version()}_Windows_x86_64.zip`
}</CodeBlock>
</TabItem>
<TabItem value="linux-arm" label="Linux - arm64">
<CodeBlock language="bash">{
`curl -L -O https://github.com/alcionai/corso/releases/download/${Version()}/corso_${Version()}_Linux_arm64.tar.gz && \\
tar zxvf corso_${Version()}_Linux_arm64.tar.gz`
}</CodeBlock>
</TabItem>
<TabItem value="linux-x86-64" label="Linux - x86_64">
<CodeBlock language="bash">{
`curl -L -O https://github.com/alcionai/corso/releases/download/${Version()}/corso_${Version()}_Linux_x86_64.tar.gz && \\
tar zxvf corso_${Version()}_Linux_x86_64.tar.gz`
}</CodeBlock>
</TabItem>
<TabItem value="macos-arm" label="macOS - arm64">
<CodeBlock language="bash">{
`curl -L -O https://github.com/alcionai/corso/releases/download/${Version()}/corso_${Version()}_Darwin_arm64.tar.gz && \\
tar zxvf corso_${Version()}_Darwin_arm64.tar.gz`
}</CodeBlock>
</TabItem>
<TabItem value="macos-x86-64" label="macOS - x86_64">
<CodeBlock language="bash">{
`curl -L -O https://github.com/alcionai/corso/releases/download/${Version()}/corso_${Version()}_Darwin_x86_64.tar.gz && \\
tar zxvf corso_${Version()}_Darwin_x86_64.tar.gz`
}</CodeBlock>
</TabItem>
</Tabs>
<!-- vale Vale.Spelling = YES -->
<!-- markdownlint-enable MD034 MD041 -->

27
website/versioned_docs/version-testing/setup/concepts.md Normal file
View File

@ -0,0 +1,27 @@
---
description: "Core Corso concepts."
---
# Concepts
Before using Corso, it's important to familiarize yourself with some key concepts.
## Microsoft 365 concepts {#m365-concepts}
* **M365 Tenant** is typically associated with a unique domain (for example, `contoso.com`) and represents a dedicated
and logically segregated instance of the Microsoft 365 services plus associated data available to your organization.
* **M365 Service** refer to a cloud-applications available through the Microsoft 365 platform. Corso supports
backup and recovery for Exchange Online, OneDrive, SharePoint, and Teams.
* **Azure AD Application** represents an Azure AD digital identity/service principal and associated configuration which
define the accessible resources and permitted actions on these resources through the application. Corso uses an Azure AD
application to connect to your *M365 tenant* and transfer data during backup and restore operations.
## Corso concepts {#corso-concepts}
* **Repository** refers to the storage location where Corso securely and efficiently stores encrypted *backups* of your
*M365 Services* data. See [Repositories](../repos) for more information.
* **Backup** is a copy of your *M365 Services* data to be used for restores in case of deletion, loss, or corruption of the
original data. Corso performs backups incrementally, and each backup only captures data that has changed between backup iterations.

128
website/versioned_docs/version-testing/setup/configuration.md Normal file
View File

@ -0,0 +1,128 @@
# Configuration
import CodeBlock from '@theme/CodeBlock';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import {Version} from '@site/src/corsoEnv';
Two things are needed to configure Corso:
* Environment variables containing configuration information
* A directory for Corso to store its configuration file
## Environment variables
Three distinct pieces of configuration are required by Corso:
* S3 object storage configuration to store backups. See [AWS Credentials Setup](../repos#s3-creds-setup) for
alternate ways to pass AWS credentials.
* `AWS_ACCESS_KEY_ID`: Access key for an IAM user or role for accessing an S3 bucket
* `AWS_SECRET_ACCESS_KEY`: Secret key associated with the access key
* (Optional) `AWS_SESSION_TOKEN`: Session token required when using temporary credentials
* Microsoft 365 Configuration
* `AZURE_CLIENT_ID`: Client ID for your Azure AD application used to access your M365 tenant
* `AZURE_TENANT_ID`: ID for the M365 tenant where the Azure AD application is registered
* `AZURE_CLIENT_SECRET`: Azure secret for your Azure AD application used to access your M365 tenant
* Corso Security Passphrase
* `CORSO_PASSPHRASE`: Passphrase to protect encrypted repository contents
<Tabs groupId="os">
<TabItem value="win" label="Powershell">
Ensure that all of the above environment variables are defined in your Powershell environment.
```powershell
$Env:AWS_ACCESS_KEY_ID = "..."
$Env:AWS_SECRET_ACCESS_KEY = "..."
$Env:AWS_SESSION_TOKEN = ""
$Env:AZURE_CLIENT_ID = "..."
$Env:AZURE_TENANT_ID = "..."
$Env:AZURE_CLIENT_SECRET = "..."
$Env:CORSO_PASSPHRASE = "CHANGE-ME-THIS-IS-INSECURE"
```
</TabItem>
<TabItem value="unix" label="Linux/macOS">
Ensure that all of the above environment variables are defined in your shell environment.
```bash
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=...
export AZURE_CLIENT_ID=...
export AZURE_TENANT_ID=...
export AZURE_CLIENT_SECRET=...
export CORSO_PASSPHRASE=CHANGE-ME-THIS-IS-INSECURE
```
</TabItem>
<TabItem value="docker" label="Docker">
For ease of use with Docker, we recommend adding the names of the required environment variables (but not their
values!) to a [Docker environment variables file](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file).
To create the environment variables file, you can run the following command:
```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
# Export required variables
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=...
export AZURE_CLIENT_ID=...
export AZURE_TENANT_ID=...
export AZURE_CLIENT_SECRET=...
export CORSO_PASSPHRASE=CHANGE-ME-THIS-IS-INSECURE
```
</TabItem>
</Tabs>
## Configuration File
<Tabs groupId="os">
<TabItem value="win" label="Powershell">
By default, Corso stores its configuration file (`.corso.toml`) in the user's home directory.
The location of the configuration file can be specified using the `--config-file` option.
</TabItem>
<TabItem value="unix" label="Linux/macOS">
By default, Corso stores its configuration file (`.corso.toml`) in the user's home directory.
The location of the configuration file can be specified using the `--config-file` option.
</TabItem>
<TabItem value="docker" label="Docker">
To preserve configuration across container runs, Corso requires access to a directory outside of its Docker container
to read or create its configuration file (`.corso.toml`). This directory must be mapped, by Docker, to the `/app/corso`
directory within the container.
<CodeBlock language="bash">{
`docker run --env-file $HOME/.corso/corso.env \\
--volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:${Version()} \\
<command> <command options>`
}</CodeBlock>
</TabItem>
</Tabs>

51
website/versioned_docs/version-testing/setup/download.md Normal file
View File

@ -0,0 +1,51 @@
# Downloads
import CodeBlock from '@theme/CodeBlock';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import {Version} from '@site/src/corsoEnv';
import DownloadBinaries from './_download_binary.md';
Corso is available as a Docker container image or as native binaries.
## Native binaries
Corso is available as an `x86_64` and `arm64` executable for Windows, Linux and macOS. These can be downloaded from
the [GitHub releases page](https://github.com/alcionai/corso/releases).
<DownloadBinaries />
## Docker container images
Corso is also available as a Docker container image for Linux (`x86_64` and `arm64`). The image can also be used on
Linux, with Docker Desktop on macOS, and on Windows in
[Linux Mode](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/quick-start-windows-10-linux).
These Docker containers can be pulled from [GitHub's container registry](https://github.com/alcionai/corso/pkgs/container/corso).
We strongly recommend using a container image with the release version tag (for example,
`ghcr.io/alcionai/corso:v0.1.0`) but container images with the `latest` tag are also available. Unreleased builds
with the `nightly` tag are also provided for testing but these are likely to be unstable.
<Tabs groupId="docker">
<TabItem value="release" label="Official Release">
<CodeBlock language="bash">{
`docker pull ghcr.io/alcionai/corso:${Version()}`
}</CodeBlock>
</TabItem>
<TabItem value="latest" label="Latest">
```bash
docker pull ghcr.io/alcionai/corso:latest
```
</TabItem>
<TabItem value="nightly" label="Nightly (Unstable)">
```bash
docker pull ghcr.io/alcionai/corso:nightly
```
</TabItem>
</Tabs>

142
website/versioned_docs/version-testing/setup/m365_access.md Normal file
View File

@ -0,0 +1,142 @@
---
description: "Connect to a Microsoft 365 tenant"
---
# Microsoft 365 access
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
To perform backup and restore operations, Corso requires access to your [M365 tenant](../concepts#m365-concepts)
by creating an [Azure AD application](../concepts#m365-concepts) with appropriate permissions.
The following steps outline a simplified procedure for creating an Azure Ad application suitable for use with Corso.
For more details, please refer to the
[official documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal)
for adding an Azure AD Application and Service Principal using the Azure Portal.
## Create an Azure AD application
Sign in into the [Azure Portal](https://portal.azure.com/) with a user that has sufficient permissions to create an
AD application.
### Register a new application
From the list of [Azure services](https://portal.azure.com/#allservices), select
**Azure Active Directory &#8594; App Registrations &#8594; New Registration**
![Registering a new application](/img/m365app_create_new.png)
### Configure basic settings
Next, configure the following:
* Give the application a name
* Select **Accounts in this organizational directory only**
* Skip the **Redirect URI** option
* Click **Register** at the bottom of the screen
![Configuring the application](/img/m365app_configure.png)
### Configure required permissions
Within the new application (`CorsoApp` in the below diagram), select **API Permissions &#8594; Add a permission** from
the management panel.
![Adding application permissions](/img/m365app_permissions.png)
Select the following permissions from **Microsoft API &#8594; Microsoft Graph &#8594; Application Permissions** and
then click **Add permissions**.
<!-- vale Microsoft.Spacing = NO -->
| API / Permissions Name | Type | Description
|:--|:--|:--|
| Calendars.ReadWrite | Application | Read and write calendars in all mailboxes |
| Contacts.ReadWrite | Application | Read and write contacts in all mailboxes |
| Files.ReadWrite.All | Application | Read and write files in all site collections |
| Mail.ReadWrite | Application | Read and write mail in all mailboxes |
| User.Read.All | Application | Read all users' full profiles |
<!-- vale Microsoft.Spacing = YES -->
### Grant admin consent
Finally, grant admin consent to this application. This step is required even if the user that created the application
is an Microsoft 365 admin.
![Granting administrator consent](/img/m365app_consent.png)
## Export application credentials
After configuring the Corso Azure AD application, store the information needed by Corso to connect to the application
as environment variables.
### Tenant ID and client ID
To view the tenant and client ID, select Overview from the app management panel.
![Obtaining Tenant and Client IDs](/img/m365app_ids.png)
Copy the client and tenant IDs and export them into the following environment variables.
<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>"
```
</TabItem>
<TabItem value="unix" label="Linux/macOS">
```bash
export AZURE_TENANT_ID=<Directory (tenant) ID for configured app>
export AZURE_CLIENT_ID=<Application (client) ID for configured app>
```
</TabItem>
<TabItem value="docker" label="Docker">
```bash
export AZURE_TENANT_ID=<Directory (tenant) ID for configured app>
export AZURE_CLIENT_ID=<Application (client) ID for configured app>
```
</TabItem>
</Tabs>
### Azure client secret
Finally, you need to obtain a client secret associated with the app using **Certificates & Secrets** from the app
management panel.
Click **New Client Secret** under **Client secrets** and follow the instructions to create a secret.
![Obtaining the Azure client secrete](/img/m365app_secret.png)
After creating the secret, immediately copy the secret **Value** because it won't be available later. Export it as an
environment variable.
<Tabs groupId="os">
<TabItem value="win" label="Powershell">
```powershell
$Env:AZURE_CLIENT_SECRET = "<Client secret value>"
```
</TabItem>
<TabItem value="unix" label="Linux/macOS">
```bash
export AZURE_CLIENT_SECRET=<Client secret value>
```
</TabItem>
<TabItem value="docker" label="Docker">
```bash
export AZURE_CLIENT_SECRET=<Client secret value>
```
</TabItem>
</Tabs>

152
website/versioned_docs/version-testing/setup/repos.md Normal file
View File

@ -0,0 +1,152 @@
---
description: "Configure backup repository"
---
# Repositories
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';
A Corso [repository](../concepts#corso-concepts) stores encrypted copies of your backup data. Repositories are
supported on the following object storage systems:
<TOCInline toc={toc} maxHeadingLevel={2}/><br/>
:::note
Depending on community interest, Corso will add support for other object storage backends in the future.
:::
## Amazon S3
### Prerequisites
Before setting up your Corso S3 repository, the following prerequisites must be met:
* The 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 has the following permissions:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:ListBucket",
"s3:DeleteObject",
"s3:GetBucketLocation",
],
"Resource": [
"arn:aws:s3:::<YOUR_BUCKET_NAME>",
"arn:aws:s3:::<YOUR_BUCKET_NAME>/*"
]
}
]
}
```
### Credential setup {#s3-creds-setup}
Corso supports the credential options offered by the AWS Go SDK. For Full details, see the *Specifying Credentials*
section of the [official documentation](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html).
The two most commonly-used options are:
* **Environment variables** - set and export `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. If using temporary
credentials derived by assuming an IAM Role, you will also need `AWS_SESSION_TOKEN`.
* **Credentials file** - ensure that the credentials file is available to Corso (for example, may need to map it if
using Corso as a container). You may also want to set and export `AWS_PROFILE`, if not using the default profile, and
`AWS_SHARED_CREDENTIALS_FILE`, if not using the default file location. You can learn more about the AWS CLI
environment variables [here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html).
### Initialize repository
Before first use, you need to initialize a Corso repository with `corso repo init s3`. See the command details
[here](../../cli/corso_repo_init_s3).
<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">
<CodeBlock language="bash">{
`# 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>
</TabItem>
</Tabs>
### Connect to a repository
If a repository already exists, you can connect to it with `corso repo connect s3`. See the command details
[here](../../cli/corso_repo_connect_s3).
<Tabs groupId="os">
<TabItem value="win" label="Powershell">
```powershell
# Connect to the Corso Repository
.\corso repo connect s3 --bucket corso-test
```
</TabItem>
<TabItem value="unix" label="Linux/macOS">
```bash
# Connect to the Corso Repository
./corso repo connect s3 --bucket corso-test
```
</TabItem>
<TabItem value="docker" label="Docker">
<CodeBlock language="bash">{
`# Connect to the Corso Repository
docker run --env-file $HOME/.corso/corso.env \\
--volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:${Version()} \\
repo connect s3 --bucket corso-test`
}</CodeBlock>
</TabItem>
</Tabs>
## S3-compatible object storage
Configuring Corso to use object storage systems compatible with the AWS S3 API (for example, Google Cloud Storage,
Backblaze B2, MinIO, etc.) is almost identical to the Amazon S3 instructions above with the exception that you will
need to use the following flag with the initial Corso `repo init` command:
```bash
--endpoint <domain.example.com>
```
### Testing with insecure TLS configurations
Corso also supports the use of object storage systems with no TLS certificate or with self-signed
TLS certificates with the `--disable-tls` or `--disable-tls-verification` flags.
[These flags](../../cli/corso_repo_init_s3) should only be used for testing.

6
website/versioned_docs/version-testing/support/bugs_and_features.md Normal file
View File

@ -0,0 +1,6 @@
# Bugs and new features
You can learn more about the Corso roadmap and how to interpret it [here](https://github.com/alcionai/corso-roadmap).
If you run into a bug or have feature requests, please file a [GitHub issue](https://github.com/alcionai/corso/issues/)
and attach the `bug` or `enhancement` label to the issue.

30
website/versioned_docs/version-testing/support/faq.md Normal file
View File

@ -0,0 +1,30 @@
# FAQ
<details>
<summary>Where does Corso store local configuration?</summary>
Corso's local configuration is stored in a file named `.corso.toml` in your home directory. Corso can be pointed at
separate configuration files using the `--config-file` option.
</details>
<details>
<summary>Does Corso report usage telemetry?</summary>
In order to better understand how people use Corso and to guide feature development, Corso supports reporting telemetry
metadata for basic information about installed versions and usage in a privacy-preserving manner. This includes a
generic description of most-commonly used backup operations and statistics on the duration and size of backups. No user
data is stored or transmitted during this process.
Telemetry reporting can be turned off by using the `--no-stats` flag. See the [Command Line Reference](../../cli/corso)
section for more information.
</details>
<details>
<summary>Does Corso work with Microsoft 365 Personal or Family subscriptions?</summary>
Unfortunately, Corso leverages the Microsoft Graph API and that's only accessible to organizations with paid
subscriptions to Microsoft 365 (for example, Business, Enterprise, or Education plans).
</details>

14
website/versioned_docs/version-testing/support/known_issues.md Normal file
View File

@ -0,0 +1,14 @@
# Known issues
Below is a list of known Corso issues and limitations:
* Only supports Exchange (email, calendars, contact) and OneDrive (files) M365 data. Additional
data types and services will be added in subsequent releases.
* Restores are non-destructive to a dedicated restore folder in the original Exchange mailbox or OneDrive account.
Advanced restore options such as in-place restore, or restore to a specific folder or to a different account aren't
yet supported.
* Provides no guarantees about whether data moved, added, or deleted in M365
while a backup is being created will be included in the running backup.
Future backups run when the data isn't modified will include the data.

57
website/versioned_sidebars/version-testing-sidebars.json Normal file
View File

@ -0,0 +1,57 @@
{
"docsSidebar": [
"intro",
"quickstart",
{
"type": "category",
"label": "Corso setup",
"items": [
"setup/concepts",
"setup/download",
"setup/m365_access",
"setup/configuration",
"setup/repos"
]
},
{
"type": "category",
"label": "Command line reference",
"link": {
"slug": "cli/corso",
"description": "Explore the commonly used Corso CLI commands",
"type": "generated-index"
},
"items": [
"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_onedrive",
"cli/corso_backup_list_onedrive",
"cli/corso_backup_details_onedrive",
"cli/corso_restore_exchange",
"cli/corso_restore_onedrive",
"cli/corso_env"
]
},
{
"type": "category",
"label": "Support",
"items": [
"support/bugs_and_features",
"support/known_issues",
"support/faq"
]
},
{
"type": "category",
"label": "Developer guide",
"items": [
"developers/build",
"developers/testing",
"developers/linters"
]
}
]
}

1
website/versions.json
View File

@ -1,3 +1,4 @@
[
"testing",
"0.0.3"
]