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: str desc: | List of source directories to backup (required). Globs and tildes are expanded. example: - /home - /etc - /var/log/syslog* repositories: required: true seq: - type: str 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). Defaults to false. example: true numeric_owner: type: bool desc: Only store/extract numeric user and group identifiers. Defaults to false. example: true atime: type: bool desc: Store atime into archive. Defaults to true. example: false ctime: type: bool desc: Store ctime into archive. Defaults to true. example: false birthtime: type: bool desc: Store birthtime (creation date) into archive. Defaults to true. example: false 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. Defaults to false. example: false bsd_flags: type: bool desc: Record bsdflags (e.g. NODUMP, IMMUTABLE) in archive. Defaults to true. example: true files_cache: type: str desc: | Mode in which to operate the files cache. See https://borgbackup.readthedocs.io/en/stable/usage/create.html#description for details. Defaults to "ctime,size,inode". example: ctime,size,inode local_path: type: str desc: Alternate Borg local executable. Defaults to "borg". example: borg1 remote_path: type: str desc: Alternate Borg remote executable. Defaults to "borg". example: borg1 patterns: seq: - type: str 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: str 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: str 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: str 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. Defaults to false. example: true exclude_if_present: type: str desc: | Exclude directories that contain a file with the given filename. Defaults to not set. 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: str 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. Defaults to not set. example: "secret-tool lookup borg-repository repo-name" encryption_passphrase: type: str 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. Defaults to not set. 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 chunker_params: type: str desc: | Specify the parameters passed to then chunker (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). See https://borgbackup.readthedocs.io/en/stable/internals.html for details. Defaults to "19,23,21,4095". example: 19,23,21,4095 compression: type: str desc: | Type of compression to use when creating archives. See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create for details. Defaults to "lz4". example: lz4 remote_rate_limit: type: int desc: Remote network upload rate limit in kiBytes/second. Defaults to unlimited. example: 100 ssh_command: type: str desc: | Command to use instead of "ssh". This can be used to specify ssh options. Defaults to not set. example: ssh -i /path/to/private/key borg_base_directory: type: str desc: | Base path used for various Borg directories. Defaults to $HOME, ~$USER, or ~. See https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables for details. example: /path/to/base borg_config_directory: type: str desc: | Path for Borg configuration files. Defaults to $borg_base_directory/.config/borg example: /path/to/base/config borg_cache_directory: type: str desc: | Path for Borg cache files. Defaults to $borg_base_directory/.cache/borg example: /path/to/base/cache borg_security_directory: type: str desc: | Path for Borg security and encryption nonce files. Defaults to $borg_base_directory/.config/borg/security example: /path/to/base/config/security borg_keys_directory: type: str desc: | Path for Borg encryption key files. Defaults to $borg_base_directory/.config/borg/keys example: /path/to/base/config/keys umask: type: scalar desc: Umask to be used for borg create. Defaults to 0077. example: 0077 lock_wait: type: int desc: Maximum seconds to wait for acquiring a repository/cache lock. Defaults to 1. example: 5 archive_name_format: type: str desc: | Name of the archive. Borg placeholders can be used. See the output of "borg help placeholders" for details. Defaults to "{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}" relocated_repo_access_is_ok: type: bool desc: Bypass Borg error about a repository that has been moved. Defaults to false. example: true unknown_unencrypted_repo_access_is_ok: type: bool desc: | Bypass Borg error about a previously unknown unencrypted repository. Defaults to false. example: true 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. See https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/ if you'd like to skip pruning entirely. map: keep_within: type: str 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: str 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. Defaults to "{hostname}-". Use an empty value to disable the default. 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', 'data', 'extract', 'disabled'] unique: true desc: | List of one or more consistency checks to run: "repository", "archives", "data", and/or "extract". Defaults to "repository" and "archives". Set to "disabled" to disable all consistency checks. "repository" checks the consistency of the repository, "archives" checks all of the archives, "data" verifies the integrity of the data within the archives, and "extract" does an extraction dry-run of the most recent archive. Note that "data" implies "archives". example: - repository - archives check_repositories: seq: - type: str 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. Defaults to checking all archives. example: 3 prefix: type: str 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. Defaults to "{hostname}-". Use an empty value to disable the default. example: sourcehostname output: desc: | Options for customizing borgmatic's own output and logging. map: color: type: bool desc: | Apply color to console output. Can be overridden with --no-color command-line flag. Defaults to true. example: false hooks: desc: | Shell commands, scripts, or integrations to execute at various points during a borgmatic run. IMPORTANT: All provided commands and scripts are executed with user permissions of borgmatic. Do not forget to set secure permissions on this configuration file (chmod 0600) as well as on any script called from a hook (chmod 0700) to prevent potential shell injection or privilege escalation. map: before_backup: seq: - type: str desc: | List of one or more shell commands or scripts to execute before creating a backup, run once per configuration file. example: - echo "Starting a backup." after_backup: seq: - type: str desc: | List of one or more shell commands or scripts to execute after creating a backup, run once per configuration file. example: - echo "Created a backup." on_error: seq: - type: str desc: | List of one or more shell commands or scripts to execute when an exception occurs during a backup or when running a before_backup or after_backup hook. example: - echo "Error while creating a backup or running a backup hook." postgresql_databases: seq: - map: name: required: true type: str desc: | Database name (required if using this hook). Or "all" to dump all databases on the host. example: users hostname: type: str desc: | Database hostname to connect to. Defaults to connecting via local Unix socket. example: database.example.org port: type: int desc: Port to connect to. Defaults to 5432. example: 5433 username: type: str desc: | Username with which to connect to the database. Defaults to the username of the current user. You probably want to specify the "postgres" superuser here when the database name is "all". example: dbuser password: type: str desc: | Password with which to connect to the database. Omitting a password will only work if PostgreSQL is configured to trust the configured username without a password, or you create a ~/.pgpass file. example: trustsome1 format: type: str enum: ['plain', 'custom', 'directory', 'tar'] desc: | Database dump output format. One of "plain", "custom", "directory", or "tar". Defaults to "custom" (unlike raw pg_dump). See https://www.postgresql.org/docs/current/app-pgdump.html for details. Note that format is ignored when the database name is "all". example: directory options: type: str desc: | Additional pg_dump/pg_dumpall options to pass directly to the dump command, without performing any validation on them. See https://www.postgresql.org/docs/current/app-pgdump.html for details. example: --role=someone desc: | List of one or more PostgreSQL databases to dump before creating a backup, run once per configuration file. The database dumps are added to your source directories at runtime, backed up, and then removed afterwards. Requires pg_dump/pg_dumpall/pg_restore commands. See https://www.postgresql.org/docs/current/app-pgdump.html for details. healthchecks: type: str desc: | Healthchecks ping URL or UUID to notify when a backup begins, ends, or errors. Create an account at https://healthchecks.io if you'd like to use this service. example: https://hc-ping.com/your-uuid-here before_everything: seq: - type: str desc: | List of one or more shell commands or scripts to execute before running all actions (if one of them is "create"), run once before all configuration files. example: - echo "Starting actions." after_everything: seq: - type: str desc: | List of one or more shell commands or scripts to execute after running all actions (if one of them is "create"), run once after all configuration files. example: - echo "Completed actions." umask: type: scalar desc: Umask used when executing hooks. Defaults to the umask that borgmatic is run with. example: 0077