# 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](../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.

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

  ```bash
 # 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 = '...'
```

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

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

  ```bash
 # 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 = '...'
```

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

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

  ```bash
 # 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 = '...'
```

</TabItem>
</Tabs>

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

<Tabs groupId="os">
<TabItem value="win" label="Windows">

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

</TabItem>
<TabItem value="unix" label="Linux">

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

</TabItem>
<TabItem value="macos" label="macOS">

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

</TabItem>
</Tabs>