corso/website/docs/setup/configuration.md

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

Apart from Environment variables configuration information can also be provided from flags or configuration files. Corso uses the following priority order for configuration:

1. Flags values
2. Environment variables
3. Configuration File information

Environment variables

Three distinct pieces of configuration are required by Corso:

• S3 object storage configuration to store backups. See AWS Credentials 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.

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

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. To create the environment variables file, you can run the following command:

# 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

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.

The config file can also be used to provide other configuration information like Azure and AWS credentials as mentioned below:

# AWS configs
aws_access_key_id = '...'
aws_secret_access_key = '...'
aws_session_token = '...'

# M365 config
account_provider = '...'
azure_tenantid = '...'
azure_client_id = '...' 
azure_secret = '...'

# Corso passphrase
passphrase = '...'

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.

The config file can also be used to provide other configuration information like Azure and AWS credentials as mentioned below:

# AWS configs
aws_access_key_id = '...'
aws_secret_access_key = '...'
aws_session_token = '...'

# M365 config
account_provider = '...'
azure_tenantid = '...'
azure_client_id = '...' 
azure_secret = '...'

# Corso passphrase
passphrase = '...'

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()} \\ <command> <command options> }

The config file can also be used to provide other configuration information like Azure and AWS credentials as mentioned below:

# AWS configs
aws_access_key_id = '...'
aws_secret_access_key = '...'
aws_session_token = '...'

# M365 config
account_provider = '...'
azure_tenantid = '...'
azure_client_id = '...' 
azure_secret = '...'

# Corso passphrase
passphrase = '...'

Log Files

Corso generates a unique log file named with its timestamp for every invocation. The default location of Corso's log file is shown below but the location can be overridden by using the --log-file flag. The log file will be appended to if multiple Corso invocations are pointed to the same file.

You can also use stdout or stderr as the --log-file location to redirect the logs to "stdout" and "stderr" respectively. This setting can cause logs to compete with progress bar displays in the terminal. We suggest using the --hide-progress option if you plan to log to stdout or stderr.

Log entries, by default, include user names and file names. The --mask-sensitive-data option can be used to replace this information with anonymized hashes.

%LocalAppData%\corso\logs\<timestamp>.log

$HOME/.cache/corso/logs/<timestamp>.log

$HOME/Library/Logs/corso/logs/<timestamp>.log