borgmatic/borgmatic/config/schema.yaml

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). Defaults to false.
                example: true
            numeric_owner:
                type: bool
                desc: Only store/extract numeric user and group identifiers. Defaults to false.
                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. 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: scalar
                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: 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. Defaults to false.
                example: true
            exclude_if_present:
                type: scalar
                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: 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. Defaults to not set.
                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. 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: scalar
                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: 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. Defaults to unlimited.
                example: 100
            ssh_command:
                type: scalar
                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: scalar
                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: scalar
                desc: |
                    Path for Borg configuration files. Defaults to $borg_base_directory/.config/borg
                example: /path/to/base/config
            borg_cache_directory:
                type: scalar
                desc: |
                    Path for Borg cache files. Defaults to $borg_base_directory/.cache/borg
                example: /path/to/base/cache
            borg_security_directory:
                type: scalar
                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: scalar
                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: scalar
                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}"
    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: 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. Defaults to "{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 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. Defaults to checking all archives.
                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. Defaults to "{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 "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 "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 "Error while creating a backup."