From aa37a1dd2ca54df65e3adbf2e042b4d6ea079833 Mon Sep 17 00:00:00 2001 From: meain Date: Tue, 6 Dec 2022 10:51:33 +0000 Subject: [PATCH] Add new version to versioned docs --- .../cli/corso_backup_create_exchange.md | 43 +++ .../cli/corso_backup_create_onedrive.md | 42 +++ .../cli/corso_backup_delete_exchange.md | 36 +++ .../cli/corso_backup_delete_onedrive.md | 36 +++ .../cli/corso_backup_details_exchange.md | 65 ++++ .../cli/corso_backup_details_onedrive.md | 50 +++ .../cli/corso_backup_details_sharepoint.md | 39 +++ .../cli/corso_backup_list_exchange.md | 29 ++ .../cli/corso_backup_list_onedrive.md | 29 ++ .../version-testing/cli/corso_env.md | 28 ++ .../cli/corso_repo_connect_s3.md | 46 +++ .../version-testing/cli/corso_repo_init_s3.md | 46 +++ .../cli/corso_restore_exchange.md | 64 ++++ .../cli/corso_restore_onedrive.md | 51 ++++ .../version-testing/developers/build.md | 75 +++++ .../version-testing/developers/linters.md | 209 +++++++++++++ .../version-testing/developers/testing.md | 58 ++++ .../versioned_docs/version-testing/intro.md | 17 ++ .../version-testing/quickstart.md | 289 ++++++++++++++++++ .../version-testing/setup/_download_binary.md | 55 ++++ .../version-testing/setup/concepts.md | 27 ++ .../version-testing/setup/configuration.md | 128 ++++++++ .../version-testing/setup/download.md | 51 ++++ .../version-testing/setup/m365_access.md | 142 +++++++++ .../version-testing/setup/repos.md | 152 +++++++++ .../support/bugs_and_features.md | 6 + .../version-testing/support/faq.md | 30 ++ .../version-testing/support/known_issues.md | 14 + .../version-testing-sidebars.json | 57 ++++ website/versions.json | 1 + 30 files changed, 1915 insertions(+) create mode 100644 website/versioned_docs/version-testing/cli/corso_backup_create_exchange.md create mode 100644 website/versioned_docs/version-testing/cli/corso_backup_create_onedrive.md create mode 100644 website/versioned_docs/version-testing/cli/corso_backup_delete_exchange.md create mode 100644 website/versioned_docs/version-testing/cli/corso_backup_delete_onedrive.md create mode 100644 website/versioned_docs/version-testing/cli/corso_backup_details_exchange.md create mode 100644 website/versioned_docs/version-testing/cli/corso_backup_details_onedrive.md create mode 100644 website/versioned_docs/version-testing/cli/corso_backup_details_sharepoint.md create mode 100644 website/versioned_docs/version-testing/cli/corso_backup_list_exchange.md create mode 100644 website/versioned_docs/version-testing/cli/corso_backup_list_onedrive.md create mode 100644 website/versioned_docs/version-testing/cli/corso_env.md create mode 100644 website/versioned_docs/version-testing/cli/corso_repo_connect_s3.md create mode 100644 website/versioned_docs/version-testing/cli/corso_repo_init_s3.md create mode 100644 website/versioned_docs/version-testing/cli/corso_restore_exchange.md create mode 100644 website/versioned_docs/version-testing/cli/corso_restore_onedrive.md create mode 100644 website/versioned_docs/version-testing/developers/build.md create mode 100644 website/versioned_docs/version-testing/developers/linters.md create mode 100644 website/versioned_docs/version-testing/developers/testing.md create mode 100644 website/versioned_docs/version-testing/intro.md create mode 100644 website/versioned_docs/version-testing/quickstart.md create mode 100644 website/versioned_docs/version-testing/setup/_download_binary.md create mode 100644 website/versioned_docs/version-testing/setup/concepts.md create mode 100644 website/versioned_docs/version-testing/setup/configuration.md create mode 100644 website/versioned_docs/version-testing/setup/download.md create mode 100644 website/versioned_docs/version-testing/setup/m365_access.md create mode 100644 website/versioned_docs/version-testing/setup/repos.md create mode 100644 website/versioned_docs/version-testing/support/bugs_and_features.md create mode 100644 website/versioned_docs/version-testing/support/faq.md create mode 100644 website/versioned_docs/version-testing/support/known_issues.md create mode 100644 website/versioned_sidebars/version-testing-sidebars.json diff --git a/website/versioned_docs/version-testing/cli/corso_backup_create_exchange.md b/website/versioned_docs/version-testing/cli/corso_backup_create_exchange.md new file mode 100644 index 000000000..98f390a89 --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_backup_create_exchange.md @@ -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 | '*' [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| diff --git a/website/versioned_docs/version-testing/cli/corso_backup_create_onedrive.md b/website/versioned_docs/version-testing/cli/corso_backup_create_onedrive.md new file mode 100644 index 000000000..583cc9159 --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_backup_create_onedrive.md @@ -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 | '*' [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.
Required
| +|`--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| diff --git a/website/versioned_docs/version-testing/cli/corso_backup_delete_exchange.md b/website/versioned_docs/version-testing/cli/corso_backup_delete_exchange.md new file mode 100644 index 000000000..1b5ef2ace --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_backup_delete_exchange.md @@ -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 [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.
Required
| +|`--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| diff --git a/website/versioned_docs/version-testing/cli/corso_backup_delete_onedrive.md b/website/versioned_docs/version-testing/cli/corso_backup_delete_onedrive.md new file mode 100644 index 000000000..8fa7509de --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_backup_delete_onedrive.md @@ -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 [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.
Required
| +|`--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| diff --git a/website/versioned_docs/version-testing/cli/corso_backup_details_exchange.md b/website/versioned_docs/version-testing/cli/corso_backup_details_exchange.md new file mode 100644 index 000000000..c6cdeef7f --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_backup_details_exchange.md @@ -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 [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.
Required
| +|`--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| diff --git a/website/versioned_docs/version-testing/cli/corso_backup_details_onedrive.md b/website/versioned_docs/version-testing/cli/corso_backup_details_onedrive.md new file mode 100644 index 000000000..3f7d0d64f --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_backup_details_onedrive.md @@ -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 [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.
Required
| +|`--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| diff --git a/website/versioned_docs/version-testing/cli/corso_backup_details_sharepoint.md b/website/versioned_docs/version-testing/cli/corso_backup_details_sharepoint.md new file mode 100644 index 000000000..75f41b299 --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_backup_details_sharepoint.md @@ -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 [flags] +``` + +### Examples + +```bash +# Explore 's files from backup 1234abcd-12ab-cd34-56de-1234abcd + +corso backup details sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd --site +``` + +### 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| diff --git a/website/versioned_docs/version-testing/cli/corso_backup_list_exchange.md b/website/versioned_docs/version-testing/cli/corso_backup_list_exchange.md new file mode 100644 index 000000000..ad52241a8 --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_backup_list_exchange.md @@ -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| diff --git a/website/versioned_docs/version-testing/cli/corso_backup_list_onedrive.md b/website/versioned_docs/version-testing/cli/corso_backup_list_onedrive.md new file mode 100644 index 000000000..a1cf7422d --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_backup_list_onedrive.md @@ -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| diff --git a/website/versioned_docs/version-testing/cli/corso_env.md b/website/versioned_docs/version-testing/cli/corso_env.md new file mode 100644 index 000000000..1d55c1474 --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_env.md @@ -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| diff --git a/website/versioned_docs/version-testing/cli/corso_repo_connect_s3.md b/website/versioned_docs/version-testing/cli/corso_repo_connect_s3.md new file mode 100644 index 000000000..0809f09cf --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_repo_connect_s3.md @@ -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 [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.
Required
| +|`--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| diff --git a/website/versioned_docs/version-testing/cli/corso_repo_init_s3.md b/website/versioned_docs/version-testing/cli/corso_repo_init_s3.md new file mode 100644 index 000000000..56ca2526b --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_repo_init_s3.md @@ -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 [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.
Required
| +|`--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| diff --git a/website/versioned_docs/version-testing/cli/corso_restore_exchange.md b/website/versioned_docs/version-testing/cli/corso_restore_exchange.md new file mode 100644 index 000000000..1a2604960 --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_restore_exchange.md @@ -0,0 +1,64 @@ +--- +title: corso restore exchange +hide_title: true +--- +## corso restore exchange + +Restore M365 Exchange service data + +```bash +corso restore exchange --backup [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.
Required
| +|`--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| diff --git a/website/versioned_docs/version-testing/cli/corso_restore_onedrive.md b/website/versioned_docs/version-testing/cli/corso_restore_onedrive.md new file mode 100644 index 000000000..3658ae7b5 --- /dev/null +++ b/website/versioned_docs/version-testing/cli/corso_restore_onedrive.md @@ -0,0 +1,51 @@ +--- +title: corso restore onedrive +hide_title: true +--- +## corso restore onedrive + +Restore M365 OneDrive service data + +```bash +corso restore onedrive --backup [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.
Required
| +|`--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| diff --git a/website/versioned_docs/version-testing/developers/build.md b/website/versioned_docs/version-testing/developers/build.md new file mode 100644 index 000000000..ce2cbef4b --- /dev/null +++ b/website/versioned_docs/version-testing/developers/build.md @@ -0,0 +1,75 @@ +# Building Corso + +## Binary + +### Building locally + +Corso is a Go project, and you can build it with `go build` from `/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 `/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. +::: diff --git a/website/versioned_docs/version-testing/developers/linters.md b/website/versioned_docs/version-testing/developers/linters.md new file mode 100644 index 000000000..9cf192ff1 --- /dev/null +++ b/website/versioned_docs/version-testing/developers/linters.md @@ -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:` will ignore a single error. `` 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" +) +``` diff --git a/website/versioned_docs/version-testing/developers/testing.md b/website/versioned_docs/version-testing/developers/testing.md new file mode 100644 index 000000000..83593daa8 --- /dev/null +++ b/website/versioned_docs/version-testing/developers/testing.md @@ -0,0 +1,58 @@ +# Running tests locally + +## Prerequisites + +- Set `CORSO_PASSPHRASE` environment variable + + ```bash + export CORSO_PASSPHRASE= + ``` + +- 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 = '' + ``` + +- 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= + export AZURE_CLIENT_SECRET= + export AZURE_TENANT_ID= + ``` + +## 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="..." + ``` diff --git a/website/versioned_docs/version-testing/intro.md b/website/versioned_docs/version-testing/intro.md new file mode 100644 index 000000000..55466f4ea --- /dev/null +++ b/website/versioned_docs/version-testing/intro.md @@ -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. diff --git a/website/versioned_docs/version-testing/quickstart.md b/website/versioned_docs/version-testing/quickstart.md new file mode 100644 index 000000000..d3722a967 --- /dev/null +++ b/website/versioned_docs/version-testing/quickstart.md @@ -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: + + + +## 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](../setup/m365_access) to obtain the necessary credentials and then make them available to Corso. + + + + + ```powershell + $Env:AZURE_CLIENT_ID = "" + $Env:AZURE_TENANT_ID = "" + $Env:AZURE_CLIENT_SECRET = "" + ``` + + + + + ```bash + export AZURE_CLIENT_ID= + export AZURE_TENANT_ID= + export AZURE_CLIENT_SECRET= + ``` + + + + + ```bash + export AZURE_CLIENT_ID= + export AZURE_TENANT_ID= + export AZURE_CLIENT_SECRET= + ``` + + + + +## 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. + + + + + ```powershell + # Initialize the Corso Repository + $Env:CORSO_PASSPHRASE = "CHANGE-ME-THIS-IS-INSECURE" + .\corso repo init s3 --bucket corso-test + ``` + + + + + ```bash + # 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](../setup/repos#connect-to-a-repository). + + + + + ```powershell + # Backup your inbox + .\corso backup create exchange --user + ``` + + + + + ```bash + # Backup your inbox + ./corso backup create exchange --user + ``` + + + + +{ +`# 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 ` +} + + + + +:::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: + + + + + ```powershell + # List all Exchange backups + .\corso backup list exchange + ``` + + + + + ```bash + # 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` +} + + + + +```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. + + + + + ```powershell + # List emails in a selected backup + .\corso backup details exchange --backup --email "*" | Select-Object -First 5 + ``` + + + + + ```bash + # List emails in a selected backup + ./corso backup details exchange --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 --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. + +```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. + + + + + ```powershell + # Restore a selected email + .\corso restore exchange --backup --email + ``` + + + + + ```bash + # Restore a selected email + ./corso restore exchange --backup --email + ``` + + + + +{ +`# 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 --email ` +} + + + + +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) diff --git a/website/versioned_docs/version-testing/setup/_download_binary.md b/website/versioned_docs/version-testing/setup/_download_binary.md new file mode 100644 index 000000000..5997ed753 --- /dev/null +++ b/website/versioned_docs/version-testing/setup/_download_binary.md @@ -0,0 +1,55 @@ + + + +import CodeBlock from '@theme/CodeBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import {Version} from '@site/src/corsoEnv'; + + + + +{ +`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` +} + + + + +{ +`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` +} + + + + +{ +`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` +} + + + + +{ +`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` +} + + + + +{ +`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` +} + + + + + + diff --git a/website/versioned_docs/version-testing/setup/concepts.md b/website/versioned_docs/version-testing/setup/concepts.md new file mode 100644 index 000000000..b9e8efae4 --- /dev/null +++ b/website/versioned_docs/version-testing/setup/concepts.md @@ -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. diff --git a/website/versioned_docs/version-testing/setup/configuration.md b/website/versioned_docs/version-testing/setup/configuration.md new file mode 100644 index 000000000..4a07d8f21 --- /dev/null +++ b/website/versioned_docs/version-testing/setup/configuration.md @@ -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 + + + + +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" + ``` + + + + +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 + ``` + + + + +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 < $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 + ``` + + + + +## Configuration File + + + + +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. + + + + +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. + + + + +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. + +{ +`docker run --env-file $HOME/.corso/corso.env \\ + --volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:${Version()} \\ + ` +} + + + diff --git a/website/versioned_docs/version-testing/setup/download.md b/website/versioned_docs/version-testing/setup/download.md new file mode 100644 index 000000000..7e945f0c0 --- /dev/null +++ b/website/versioned_docs/version-testing/setup/download.md @@ -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). + + + +## 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. + + + + +{ +`docker pull ghcr.io/alcionai/corso:${Version()}` +} + + + + + ```bash + docker pull ghcr.io/alcionai/corso:latest + ``` + + + + + ```bash + docker pull ghcr.io/alcionai/corso:nightly + ``` + + + diff --git a/website/versioned_docs/version-testing/setup/m365_access.md b/website/versioned_docs/version-testing/setup/m365_access.md new file mode 100644 index 000000000..fa83b4003 --- /dev/null +++ b/website/versioned_docs/version-testing/setup/m365_access.md @@ -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 → App Registrations → 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 → Add a permission** from +the management panel. + +![Adding application permissions](/img/m365app_permissions.png) + +Select the following permissions from **Microsoft API → Microsoft Graph → Application Permissions** and +then click **Add permissions**. + + +| 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 | + + +### 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. + + + + + ```powershell + $Env:AZURE_CLIENT_ID = "" + $Env:AZURE_TENANT_ID = "" + ``` + + + + + ```bash + export AZURE_TENANT_ID= + export AZURE_CLIENT_ID= + ``` + + + + + ```bash + export AZURE_TENANT_ID= + export AZURE_CLIENT_ID= + ``` + + + + +### 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. + + + + + ```powershell + $Env:AZURE_CLIENT_SECRET = "" + ``` + + + + + ```bash + export AZURE_CLIENT_SECRET= + ``` + + + + + ```bash + export AZURE_CLIENT_SECRET= + ``` + + + diff --git a/website/versioned_docs/version-testing/setup/repos.md b/website/versioned_docs/version-testing/setup/repos.md new file mode 100644 index 000000000..c95e47229 --- /dev/null +++ b/website/versioned_docs/version-testing/setup/repos.md @@ -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: + +
+ +:::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:::", + "arn:aws:s3:::/*" + ] + } + ] +} +``` + +### 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). + + + + + ```powershell + # Initialize the Corso Repository + $Env:CORSO_PASSPHRASE = "CHANGE-ME-THIS-IS-INSECURE" + .\corso repo init s3 --bucket corso-test + ``` + + + + + ```bash + # Initialize the Corso Repository + export 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" +docker run --env-file $HOME/.corso/corso.env \\ + --volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:${Version()} \\ + repo init s3 --bucket corso-test` +} + + + + +### 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). + + + + + ```powershell + # Connect to the Corso Repository + .\corso repo connect s3 --bucket corso-test + ``` + + + + + ```bash + # Connect to the Corso Repository + ./corso repo connect s3 --bucket corso-test + ``` + + + + +{ +`# 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` +} + + + + +## 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 +``` + +### 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. diff --git a/website/versioned_docs/version-testing/support/bugs_and_features.md b/website/versioned_docs/version-testing/support/bugs_and_features.md new file mode 100644 index 000000000..20eef8888 --- /dev/null +++ b/website/versioned_docs/version-testing/support/bugs_and_features.md @@ -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. diff --git a/website/versioned_docs/version-testing/support/faq.md b/website/versioned_docs/version-testing/support/faq.md new file mode 100644 index 000000000..4f5233a3a --- /dev/null +++ b/website/versioned_docs/version-testing/support/faq.md @@ -0,0 +1,30 @@ +# FAQ + +
+ Where does Corso store local configuration? + +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. + +
+ +
+ Does Corso report usage telemetry? + +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. + +
+ +
+ Does Corso work with Microsoft 365 Personal or Family subscriptions? + +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). + +
diff --git a/website/versioned_docs/version-testing/support/known_issues.md b/website/versioned_docs/version-testing/support/known_issues.md new file mode 100644 index 000000000..e809fc565 --- /dev/null +++ b/website/versioned_docs/version-testing/support/known_issues.md @@ -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. diff --git a/website/versioned_sidebars/version-testing-sidebars.json b/website/versioned_sidebars/version-testing-sidebars.json new file mode 100644 index 000000000..66233a417 --- /dev/null +++ b/website/versioned_sidebars/version-testing-sidebars.json @@ -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" + ] + } + ] +} diff --git a/website/versions.json b/website/versions.json index 44889fadb..9fc0e8308 100644 --- a/website/versions.json +++ b/website/versions.json @@ -1,3 +1,4 @@ [ + "testing", "0.0.3" ]