<p align="center">
<img src="https://raw.githubusercontent.com/rustic-rs/assets/main/logos/readme_header_config.png" height="400" />
</p>
# rustic Configuration Specification
`rustic` is a backup tool that allows users to define their backup options in
profiles using TOML files. A configuration profile consists of various sections
and attributes that control the behavior of `rustic` for different commands and
sources.
This specification covers all the available sections and attributes in the
`rustic` configuration profile file and includes their corresponding environment
variable names. Users can customize their backup behavior by modifying these
attributes according to their needs.
## Table of Contents
- [Merge Precedence](#merge-precedence)
- [Profiles](#profiles)
- [Sections and Attributes](#sections-and-attributes)
- [Global Options `[global]`](#global-options-global)
- [Global Hooks `[global.hooks]`](#global-hooks-globalhooks)
- [Global Options - env variables `[global.env]`](#global-options---env-variables-globalenv)
- [Repository Options `[repository]`](#repository-options-repository)
- [Repository Options (Additional) `[repository.options]`](#repository-options-additional-repositoryoptions)
- [Repository Options for cold repo (Additional) `[repository.options-cold]`](#repository-options-for-cold-repo-additional-repositoryoptions-cold)
- [Repository Options for hot repo (Additional) `[repository.options-hot]`](#repository-options-for-hot-repo-additional-repositoryoptions-hot)
- [Repository Hooks `[repository.hooks]`](#repository-hooks-repositoryhooks)
- [Snapshot-Filter Options `[snapshot-filter]`](#snapshot-filter-options-snapshot-filter)
- [Backup Options `[backup]`](#backup-options-backup)
- [Backup Hooks `[backup.hooks]`](#backup-hooks-backuphooks)
- [Backup Snapshots `[[backup.snapshots]]`](#backup-snapshots-backupsnapshots)
- [Forget Options `[forget]`](#forget-options-forget)
- [Copy Targets `[copy]`](#copy-targets-copy)
- [WebDAV Options `[webdav]`](#webdav-options-webdav)
## Merge Precedence
The merge precedence for values is:
Commandline Arguments >> Environment Variables >> Configuration Profile
Values parsed from the `configuration profile` can be overwritten by
`environment variables`, which can be overwritten by `commandline arguments`
options. Therefore `commandline arguments` have the highest precedence.
**NOTE**: There are the following restrictions:
- Not all options are available as environment variables or command line
arguments. There are also command line options which cannot be set in the
profile TOML files.
- You can overwrite values, but for most values, you cannot "unset" them on a
higher priority level.
## Profiles
Configuration files can be placed in the user's local config directory, e.g.
`~/.config/rustic/` or in the global config dir, e.g. `/etc/rustic/`. You can
use different config files, e.g. `myconfig.toml` and use the `-P` option to
specify the profile name, e.g. `rustic -P myconfig`. env variables can be
substituted in config files using the `profile-substitute-env` option. This
allows extra customization possibilities.
Examples for different configuration files can be found here in the
[/config/](/config) directory.
## Services
We have collected some examples how to configure `rustic` for various services
in the [services/](/config/services/) subdirectory. Please note that these
examples are not complete and may not work out of the box. They are intended to
give you a starting point for your own configuration.
If you want to contribute your own configuration, please
[open a pull request](https://rustic.cli.rs/dev-docs/contributing-to-rustic.html#submitting-pull-requests).
## Sections and Attributes
### Global Options `[global]`
| use-profiles | Array of profiles to use. Allows to recursively use other profiles. | Empty array | ["2nd", "3rd"] | RUSTIC_USE_PROFILE | --use-profile, -P |
| profile-substitute-env | Substitute env variables in profiles. | false | true | RUSTIC_PROFILE_SUBSTITUTE_ENV | --profile-substitute-env |
| dry-run | If true, performs a dry run without making any changes. | false | | RUSTIC_DRY_RUN | --dry-run, -n |
| log-level | Logging level. Possible values: "off", "error", "warn", "info", "debug", "trace". | "info" | | RUSTIC_LOG_LEVEL | --log-level |
| log-level-logfile | Logging level for log file. Possible values: "off", "error", "warn", "info", "debug", "trace". | "info" | | RUSTIC_LOG_LEVEL_LOGFILE | --log-level-logfile |
| log-level-dryrun | Logging level in dry-run mode. Possible values: "off", "error", "warn", "info", "debug", "trace". | "info" | | RUSTIC_LOG_LEVEL_DRYRUN | --log-level-dryrun |
| log-level-dependencies | Logging level for dependencies. Possible values: "off", "error", "warn", "info", "debug", "trace". | "warn" | | RUSTIC_LOG_LEVEL_DEPENDENCIES | --log-level-dependencies |
| log-file | Path to the log file. | No log file | "/log/rustic.log" | RUSTIC_LOG_FILE | --log-file |
| no-progress | If true, disables progress indicators. | false | | RUSTIC_NO_PROGRESS | --no-progress |
| progress-interval | The interval at which progress indicators are shown. | "100ms" | "1m" | RUSTIC_PROGRESS_INTERVAL | --progress-interval |
| group-by | Group snapshots by any combination of host,label,paths,tags e.g. for "latest" | "host,label,paths" | | RUSTIC_GROUP_BY | --group-by, -g |
| check-index | If true, check the index and read pack headers if index information is missing. | false | | RUSTIC_CHECK_INDEX | --check-index |
| show-time-offset | If true, show stored time with offset instead of converting to local time | false | true | RUSTIC_SHOW_TIME_OFFSET | --show-time-offset |
| prometheus | URL of a Prometheus Push Gateway to push metrics to. | Not set | "http://gateway/" | RUSTIC_PROMETHEUS | --prometheus |
| prometheus-user | Username to authenticate to the Prometheus Push Gateway | Not set | "myuser" | RUSTIC_PROMETHEUS_USER | --prometheus-user |
| prometheus-pass | Password to authenticate to the Prometheus Push Gateway | Not set | "secret" | RUSTIC_PROMETHEUS_PASS | --prometheus-pass |
| opentelemetry | OpenTelemetry metrics endpoint (HTTP Protobuf) | Not set | "http://otel/v1/metrics" | RUSTIC_OTEL, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | --opentelemetry |
### Global Hooks `[global.hooks]`
These external commands are run before and after each commands, respectively.
**Note**: There are also repository hooks, which should be used for commands
needed to set up the repository (like mounting the repo dir), see below.
| run-before | Run the given commands before execution | not set | ["echo test"] | |
| run-after | Run the given commands after successful execution | not set | ["echo test"] | |
| run-failed | Run the given commands after failed execution | not set | ["echo test"] | |
| run-finally | Run the given commands after every execution | not set | ["echo test"] | |
### Global Options - env variables `[global.env]`
All given environment variables are set before processing. This is handy to
configure e.g. the `rclone`-backend or some commands which will be called by
rustic.
**Important**: Please do not forget to include environment variables set in the
config profile as a possible source of errors if you encounter problems. They
could possibly shadow other values that you have already set.
### Global Metrics labels `[global.metrics-labels]`
All given labels are included with the metrics, if it is configured.
### Repository Options `[repository]`
| repository | The path to the repository. Required. | Not set | "/tmp/rustic" | RUSTIC_REPOSITORY | --repositoy, -r |
| repo-hot | The path to the hot repository. | Not set | | RUSTIC_REPO_HOT | --repo-hot |
| cache-dir | Path to the cache directory. | ~/.cache/rustic/$REPO_ID | ~/.cache/my_own_cache/ | RUSTIC_CACHE_DIR | --cache-dir |
| no-cache | If true, disables caching. | false | | RUSTIC_NO_CACHE | --no-cache |
| warm-up | If true, warms up the repository by file access. | false | | | ---warm-up |
| warm-up-command | Command to warm up the repository. | Not set | | | --warm-up-command |
| warm-up-wait | The wait time for warming up the repository. | Not set | | | --warm-up-wait |
| warm-up-wait-command | Command to run to wait for packs to be warmed-up. | Not set | | | --warm-up-wait-command |
| warm-up-batch | The batch size for warm-up. | 1 | | | --warm-up-batch |
| key | The masterkey for the repository. | Not set | (create one using `rustic key create`) | RUSTIC_KEY | --key |
| key-file | Path to a file containing the masterkey for the repository. | Not set | | RUSTIC_KEY_FILE | --key-file |
| key-command | Command to retrieve the masterkey for the repository. | Not set | | RUSTIC_KEY_COMMAND | --key-command |
| password | The password for the repository. | Not set | "mySecretPassword" | RUSTIC_PASSWORD | --password |
| password-file | Path to a file containing the password for the repository. | Not set | | RUSTIC_PASSWORD_FILE | --password-file, -p |
| password-command | Command to retrieve the password for the repository. | Not set | | RUSTIC_PASSWORD_COMMAND | --password-command |
### Repository Options (Additional) `[repository.options]`
Additional repository options - depending on backend. These can be only set in
the config file or using env variables. For variables in kebab case, use upper
snake case and prefix with "RUSTIC_REPO_OPT_" to obtain the env variable name,
e.g. `use-password = "true"` becomes `RUSTIC_REPO_OPT_USE_PASSWORD=true`.
Moreover, for opendal parameters (which need to be in lower snake case), you can
use upper snake case and prefix with "OPENDAL_" as env variable, e.g.
`application_key = "my-key"` becomes `OPENDAL_APPLICATION_KEY=my-key`.
| post-create-command | Command to execute after creating a snapshot in the local backend. | Not set | "par2create -qq -n1 -r5 %file" |
| post-delete-command | Command to execute after deleting a snapshot in the local backend. | Not set | "sh -c \"rm -f %file*.par2\"" |
### Repository Options for cold repo (Additional) `[repository.options-cold]`
Additional repository options for cold repository - depending on backend. These
can be only set in the config file or using env variables. For variables in
kebab case use upper snake case and prefix with `RUSTIC_REPO_OPTCOLD_` to obtain
the env variable name, for variables in lower snake case use upper snake case
and prefix with `OPENDALCOLD_`.
see [Repository Options](#repository-options-repository)
### Repository Options for hot repo (Additional) `[repository.options-hot]`
Additional repository options for hot repository - depending on backend. These
can be only set in the config file or using env variables. For variables in
kebab case use upper snake case and prefix with `RUSTIC_REPO_OPTHOT_` to obtain
the env variable name, for variables in lower snake case use upper snake case
and prefix with `OPENDALHOT_`.
see [Repository Options](#repository-options-repository)
### Repository Hooks `[repository.hooks]`
These external commands are run before and after each repository-accessing
commands, respectively.
See [Global Hooks](#global-hooks-globalhooks).
### Snapshot-Filter Options `[snapshot-filter]`
| filter-hosts | Array of hosts to filter snapshots. | Not set | ["myhost", "host2"] | --filter-host |
| filter-labels | Array of labels to filter snapshots. | Not set | ["mylabal"] | --filter-label |
| filter-paths | Array of pathlists to filter snapshots. | Not set | ["/home,/root"] | --filter-paths |
| filter-paths-exact | Array or string of paths to filter snapshots. Exact match. | Not set | ["path1,path2", "path3"] | --filter-paths-exact |
| filter-tags | Array of taglists to filter snapshots. | Not set | ["tag1,tag2"] | --filter-tags |
| filter-tags-exact | Array or string of tags to filter snapshots. Exact match. | Not set | ["tag1,tag2", "tag3"] | --filter-tags-exact |
| filter-before | Filter snapshots before the given date/time | Not set | "2024-01-01" | --filter-before |
| filter-after | Filter snapshots after the given date/time | Not set | "2023-01-01 11:15:23" | --filter-after |
| filter-size | Filter snapshots for a total size in the size range. | Not set | "1MB..1GB" | --filter-size |
| | If a single value is given, this is taken as lower bound. | | "500 k" | |
| filter-size-added | Filter snapshots for a size added to the repository in the size range. | Not set | "1MB..1GB" | --filter-size-added |
| | If a single value is given, this is taken as lower bound. | | "500 k" | |
| filter-fn | Custom filter function for snapshots. (only when compiled with `rhai`feature) | Not set | | --filter-fn |
| filter-jq | Custom filter jq function for snapshots. Should return bool | Not set | ".summary.files_added > 1" | --filter-jq |
| filter-last | Only use the last N snapshots. When using groups, this applies for each group. | Not set | "15" | --filter-last |
### Backup Options `[backup]`
**Note**: If set here, the backup options apply for all sources, although they
can be overwritten in the source-specific configuration, see below.
| as-path | Specifies the path for the backup when the source contains a single path. | Not set | | --as-path |
| command | Set the command saved in the snapshot. | The full command used | | --command |
| custom-ignorefiles | Array of names of custom ignorefiles which will be used to exclude files. | [] | | --custom-ignorefile |
| description | Description for the snapshot. | Not set | | --description |
| description-from | Path to a file containing the description for the snapshot. | Not set | | --description-from |
| delete-never | If true, never delete the snapshot. | false | | --delete-never |
| delete-after | Time duration after which the snapshot be deleted. | Not set | | --delete-after |
| exclude-if-present | Array of filenames which will exclude its parent directory from the backup if they are present. | [] | | --exclude-if-present |
| exclude-if-xattr | Array of xattr names. Files/directories having any of these extended attributes set will be excluded. | [] | | --exclude-if-xattr |
| force | If true, forces the backup even if no changes are detected. | false | | --force |
| git-ignore | If true, use .gitignore rules to exclude files from the backup in the source directory. | false | | --git-ignore |
| globs | Array of globs specifying what to include/exclude in the backup. | [] | | --glob |
| glob-files | Array or string of glob files specifying what to include/exclude in the backup. | [] | | --glob-file |
| group-by | Grouping strategy to find parent snapshot. | global grouping strategy | | --group-by |
| host | Host name used in the snapshot. | local hostname | | --host |
| iglobs | Like glob, but apply case-insensitive | [] | | --iglob |
| iglob-files | Like glob-file, but apply case-insensitive | [] | | --iglob-file |
| ignore-ctime | If true, ignore file change time (ctime). | false | | --ignore-ctime |
| ignore-inode | If true, ignore file inode for the backup. | false | | --ignore-inode |
| init | If true, initialize repository if it doesn't exist, yet. | false | | --init |
| json | If true, returns output of the command as json. | false | | --json |
| label | Set label for the snapshot. | Not set | | --label |
| no-require-git | (with git-ignore:) Apply .git-ignore files even if they are not in a git repository. | false | | --no-require-git |
| no-scan | Don't scan the backup source for its size (disables ETA). | false | | --no-scan |
| one-file-system | If true, only backs up files from the same filesystem as the source. | false | | --one-file-system |
| parents | Parent snapshot(s) for the backup. | Not set | | --parent |
| skip-if-unchanged | Skip saving of the snapshot if it is identical to the parent. | false | | --skip-identical-parent |
| stdin-command | Call this command and use it's stdout as stdin to backup. | Not set | | --stdin-command |
| stdin-filename | File name to be used when reading from stdin. | Not set | | --stdin-filename |
| tags | Array of tags for the backup. | [] | | --tag |
| time | Set the time saved in the snapshot. | current time | | --time |
| with-atime | If true, includes file access time (atime) in the backup. | false | | --with-atime |
| with-devid | Determines whether to include the device ID in the backup. Allowed values are `always`, `never` or `hardlink`. | "hardlink" | "always" | --with-devid |
| metrics-job | jobname used when pushing metrics (if global prometheus or opentelemetry option is set) | "rustic-backup" | "myjob" | --metrics-job |
### Backup Hooks `[backup.hooks]`
These external commands are run before and after each backup, respectively.
**Note**: Global hooks and repository hooks are run additionally.
See [Global Hooks](#global-hooks-globalhooks).
### Backup Metrics labels `[backup.metrics-labels]`
See [Global Metrics labels](#global-metrics-labels-globalmetrics-labels).
### Backup Snapshots `[[backup.snapshots]]`
**Note**: All of the backup options mentioned before can also be used as
snapshot-specific option and then only apply to this snapshot.
| name | Name to identify this snapshot (to be used with the --name CLI option) | "" | "myid" |
| sources | Array of source directories or file(s) to back up. | [] | ["/dir1", "/dir2"] |
| hooks | Hooks to run before and after backing up the defined sources. | Not set | { run-before = [], run-after = [], run-failed = [], run-finally = [] } |
Source-specific hooks are called additionally to global, repository and backup
hooks when backing up the defined sources into a snapshot.
### Forget Options `[forget]`
**Note**: At least one of the `keep-*` options must be given. Use
`keep-none = true` if you want to remove all snapshots.
| group-by | Group snapshots by given criteria before applying keep policies. | global grouping strategy | | --group-by |
| keep-last | Number of most recent snapshots to keep. | Not set | 15 | --keep-last, -l |
| keep-minutely, -M | Number of minutely snapshots to keep. | Not set | | --keep-minutely |
| keep-hourly, -H | Number of hourly snapshots to keep. | Not set | | --keep-hourly |
| keep-daily, -d | Number of daily snapshots to keep. | Not set | 8 | --keep-daily |
| keep-weekly, -w | Number of weekly snapshots to keep. | Not set | | --keep-weekly |
| keep-monthly, -m | Number of monthly snapshots to keep. | Not set | | --keep-monthly |
| keep-quarter-yearly | Number of quarter-yearly snapshots to keep. | Not set | | --keep-quarter-yearly |
| keep-half-yearly | Number of half-yearly snapshots to keep. | Not set | | --keep-half-yearly |
| keep-yearly, -y | Number of yearly snapshots to keep. | Not set | | --keep-yearly |
| keep-within-minutely | The time duration within which minutely snapshots will be kept. | Not set | "2 hours" | --keep-within-minutely |
| keep-within-hourly | The time duration within which hourly snapshots will be kept. | Not set | "1 day" | --keep-within-hourly |
| keep-within-daily | The time duration within which daily snapshots will be kept. | Not set | "7 days" | --keep-within-daily |
| keep-within-weekly | The time duration within which weekly snapshots will be kept. | Not set | | --keep-within-weekly |
| keep-within-monthly | The time duration within which monthly snapshots will be kept. | Not set | | --keep-within-monthly |
| keep-within-quarter-yearly | The time duration within which quarter-yearly snapshots will be kept. | Not set | | --keep-within-quarter-yearly |
| keep-within-half-yearly | The time duration within which half-yearly snapshots will be kept. | Not set | | --keep-within-half-yearly |
| keep-within-yearly | The time duration within which yearly snapshots will be kept. | Not set | | --keep-within-yearly |
| keep-tags | Keep snapshots containing one of these taglists. | [] | ["keep", "important" ] | --keep-tags |
| keep-ids | Keep snapshots containing one of these IDs. | [] | ["6e58f3d32" ] | --keep-id |
| keep-none | Allow to keep no snapshots. | false | true | --keep-none |
| delete-unchanged | Remove snapshots which are unchanged w.r.t previous ones. | false | true | --delete-unchanged |
| prune | If set to true, prune the repository after snapshots have been removed. | false | | --prune |
Additionally extra snapshot filter options can be given for the `forget` command
here, see Snapshot-Filter options.
### Copy Targets `[copy]`
**Note**: Copy-targets must be defined in their own config profile files.
| targets | Targets to copy to | [] | ["profile1", "profile2"] | --target |
### WebDAV Options `[webdav]`
`rustic` supports mounting snapshots via WebDAV. This is useful if you want to
access your snapshots via a file manager.
**Note**: `https://` and Authentication are not supported yet.
The following options are available to be used in your configuration file:
| address | Address of the WebDAV server. | localhost:8000 | | --address |
| path-template | The path template to use for snapshots. {id}, {id_long}, {time}, {username}, {hostname}, {label}, {tags}, {backup_start}, {backup_end} are replaced. | `[{hostname}]/[{label}]/{time}` | | --path-template |
| time-template | The time template to use to display times in the path template. See <https://pubs.opengroup.org/onlinepubs/009695399/functions/strftime.htmll> for format options. | `%Y-%m-%d_%H-%M-%S` | | --time-template |
| symlinks | If true, follows symlinks. | false | | --symlinks |
| file-access | How to handle access to files. | "forbidden" for hot/cold repositories, else "read" | | --file-access |
| snapshot-path | Specify directly which snapshot/path to serve | Not set, this will generate a virtual tree with all snapshots using path-template | | --snapshot-path |