49f6f8c337
<!-- PR description--> - Use single inverted comma instead of double inverted comma in Powershell env vars. - Update config file information in docs. #### Does this PR need a docs update or release note? - [ ] ⛔ No #### Type of change <!--- Please check the type of change your PR introduces: ---> - [ ] 🗺️ Documentation #### Issue(s) <!-- Can reference multiple issues. Use one of the following "magic words" - "closes, fixes" to auto-close the Github issue. --> * https://github.com/alcionai/corso/issues/3522 #### Test Plan <!-- How will this be tested prior to merging.--> - [ ] 💪 Manual - [ ] ⚡ Unit test - [ ] 💚 E2E
227 lines
6.5 KiB
Markdown
227 lines
6.5 KiB
Markdown
# 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>
|