Configuration
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:
- Flags values
- Environment variables
- 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 bucketAWS_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 tenantAZURE_TENANT_ID
: ID for the M365 tenant where the Azure AD application is registeredAZURE_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
- Powershell
- Linux/macOS
- Docker
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
- Powershell
- Linux/macOS
- Docker
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:v0.19.0 \
<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.
- Windows
- Linux
- macOS
%LocalAppData%\corso\logs\<timestamp>.log
$HOME/.cache/corso/logs/<timestamp>.log
$HOME/Library/Logs/corso/logs/<timestamp>.log