name: Borgmatic configuration file schema version: 1 map: location: desc: | Where to look for files to backup, and where to store those backups. See https://borgbackup.readthedocs.io/en/stable/quickstart.html and https://borgbackup.readthedocs.io/en/stable/usage.html#borg-create for details. required: true map: source_directories: required: true seq: - type: scalar desc: | List of source directories to backup (required). Globs and tildes are expanded. example: - /home - /etc - /var/log/syslog* repositories: required: true seq: - type: scalar desc: | Paths to local or remote repositories (required). Tildes are expanded. Multiple repositories are backed up to in sequence. See ssh_command for SSH options like identity file or port. example: - user@backupserver:sourcehostname.borg one_file_system: type: bool desc: Stay in same file system (do not cross mount points). example: true read_special: type: bool desc: | Use Borg's --read-special flag to allow backup of block and other special devices. Use with caution, as it will lead to problems if used when backing up special devices such as /dev/zero. example: false bsd_flags: type: bool desc: Record bsdflags (e.g. NODUMP, IMMUTABLE) in archive. Defaults to true. example: true files_cache: type: scalar desc: | Mode in which to operate the files cache. See https://borgbackup.readthedocs.io/en/stable/usage/create.html#description for details. example: ctime,size,inode local_path: type: scalar desc: Alternate Borg local executable. Defaults to "borg". example: borg1 remote_path: type: scalar desc: Alternate Borg remote executable. Defaults to "borg". example: borg1 patterns: seq: - type: scalar desc: | Any paths matching these patterns are included/excluded from backups. Globs are expanded. (Tildes are not.) Note that Borg considers this option experimental. See the output of "borg help patterns" for more details. Quote any value if it contains leading punctuation, so it parses correctly. example: - 'R /' - '- /home/*/.cache' - '+ /home/susan' - '- /home/*' patterns_from: seq: - type: scalar desc: | Read include/exclude patterns from one or more separate named files, one pattern per line. Note that Borg considers this option experimental. See the output of "borg help patterns" for more details. example: - /etc/borgmatic/patterns exclude_patterns: seq: - type: scalar desc: | Any paths matching these patterns are excluded from backups. Globs and tildes are expanded. See the output of "borg help patterns" for more details. example: - '*.pyc' - ~/*/.cache - /etc/ssl exclude_from: seq: - type: scalar desc: | Read exclude patterns from one or more separate named files, one pattern per line. See the output of "borg help patterns" for more details. example: - /etc/borgmatic/excludes exclude_caches: type: bool desc: | Exclude directories that contain a CACHEDIR.TAG file. See http://www.brynosaurus.com/cachedir/spec.html for details. example: true exclude_if_present: type: scalar desc: Exclude directories that contain a file with the given filename. example: .nobackup storage: desc: | Repository storage options. See https://borgbackup.readthedocs.io/en/stable/usage.html#borg-create and https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables for details. map: encryption_passcommand: type: scalar desc: | The standard output of this command is used to unlock the encryption key. Only use on repositories that were initialized with passcommand/repokey encryption. Note that if both encryption_passcommand and encryption_passphrase are set, then encryption_passphrase takes precedence. example: "secret-tool lookup borg-repository repo-name" encryption_passphrase: type: scalar desc: | Passphrase to unlock the encryption key with. Only use on repositories that were initialized with passphrase/repokey encryption. Quote the value if it contains punctuation, so it parses correctly. And backslash any quote or backslash literals as well. example: "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~" checkpoint_interval: type: int desc: | Number of seconds between each checkpoint during a long-running backup. See https://borgbackup.readthedocs.io/en/stable/faq.html#if-a-backup-stops-mid-way-does-the-already-backed-up-data-stay-there for details. Defaults to checkpoints every 1800 seconds (30 minutes). example: 1800 compression: type: scalar desc: | Type of compression to use when creating archives. See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create for details. Defaults to no compression. example: lz4 remote_rate_limit: type: int desc: Remote network upload rate limit in kiBytes/second. example: 100 ssh_command: type: scalar desc: Command to use instead of just "ssh". This can be used to specify ssh options. example: ssh -i /path/to/private/key umask: type: scalar desc: Umask to be used for borg create. example: 0077 lock_wait: type: int desc: Maximum seconds to wait for acquiring a repository/cache lock. example: 5 archive_name_format: type: scalar desc: | Name of the archive. Borg placeholders can be used. See the output of "borg help placeholders" for details. Default is "{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}". If you specify this option, you must also specify a prefix in the retention section to avoid accidental pruning of archives with a different archive name format. And you should also specify a prefix in the consistency section as well. example: "{hostname}-documents-{now}" retention: desc: | Retention policy for how many backups to keep in each category. See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details. At least one of the "keep" options is required for pruning to work. map: keep_within: type: scalar desc: Keep all archives within this time interval. example: 3H keep_secondly: type: int desc: Number of secondly archives to keep. example: 60 keep_minutely: type: int desc: Number of minutely archives to keep. example: 60 keep_hourly: type: int desc: Number of hourly archives to keep. example: 24 keep_daily: type: int desc: Number of daily archives to keep. example: 7 keep_weekly: type: int desc: Number of weekly archives to keep. example: 4 keep_monthly: type: int desc: Number of monthly archives to keep. example: 6 keep_yearly: type: int desc: Number of yearly archives to keep. example: 1 prefix: type: scalar desc: | When pruning, only consider archive names starting with this prefix. Borg placeholders can be used. See the output of "borg help placeholders" for details. Default is "{hostname}-". example: sourcehostname consistency: desc: | Consistency checks to run after backups. See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check and https://borgbackup.readthedocs.org/en/stable/usage.html#borg-extract for details. map: checks: seq: - type: str enum: ['repository', 'archives', 'extract', 'disabled'] unique: true desc: | List of one or more consistency checks to run: "repository", "archives", and/or "extract". Defaults to "repository" and "archives". Set to "disabled" to disable all consistency checks. "repository" checks the consistency of the repository, "archive" checks all of the archives, and "extract" does an extraction dry-run of just the most recent archive. example: - repository - archives check_repositories: seq: - type: scalar desc: | Paths to a subset of the repositories in the location section on which to run consistency checks. Handy in case some of your repositories are very large, and so running consistency checks on them would take too long. Defaults to running consistency checks on all repositories configured in the location section. example: - user@backupserver:sourcehostname.borg check_last: type: int desc: Restrict the number of checked archives to the last n. Applies only to the "archives" check. example: 3 prefix: type: scalar desc: | When performing the "archives" check, only consider archive names starting with this prefix. Borg placeholders can be used. See the output of "borg help placeholders" for details. Default is "{hostname}-". example: sourcehostname hooks: desc: | Shell commands or scripts to execute before and after a backup or if an error has occurred. IMPORTANT: All provided commands and scripts are executed with user permissions of borgmatic. Do not forget to set secure permissions on this file as well as on any script listed (chmod 0700) to prevent potential shell injection or privilege escalation. map: before_backup: seq: - type: scalar desc: List of one or more shell commands or scripts to execute before creating a backup. example: - echo "`date` - Starting a backup job." after_backup: seq: - type: scalar desc: List of one or more shell commands or scripts to execute after creating a backup. example: - echo "`date` - Backup created." on_error: seq: - type: scalar desc: List of one or more shell commands or scripts to execute in case an exception has occurred. example: - echo "`date` - Error while creating a backup."