---
obj: application
website: https://torsion.org/borgmatic
arch-wiki: https://wiki.archlinux.org/title/Borgmatic
repo: https://github.com/borgmatic-collective/borgmatic
rev: 2024-03-14
---

# borgmatic
borgmatic is simple, configuration-driven backup software for servers and workstations based on [borg](borg.md) backup. Protect your files with client-side encryption. Backup your databases too. Monitor it all with integrated third-party services.

Example Config File:
```yml
# List of source directories to backup.
source_directories:
    - /home
    - /etc

# Paths of local or remote repositories to backup to.
repositories:
    - path: ssh://k8pDxu32@k8pDxu32.repo.borgbase.com/./repo
      label: borgbase
    - path: /var/lib/backups/local.borg
      label: local

# Retention policy for how many backups to keep.
keep_daily: 7
keep_weekly: 4
keep_monthly: 6

# List of checks to run to validate your backups.
checks:
    - name: repository
    - name: archives
      frequency: 2 weeks

# Custom preparation scripts to run.
before_backup:
    - prepare-for-backup.sh

# Databases to dump and include in backups.
postgresql_databases:
    - name: users

# Third-party services to notify you if backups aren't happening.
healthchecks:
    ping_url: https://hc-ping.com/be067061-cf96-4412-8eae-62b0c50d6a8c
```

## Configuration
Below is a sample borgmatic configuration file including all available options for the most recent version of borgmatic.
The configuration files should live in `/etc/borgmatic/config.yaml`

If you're using an older version of borgmatic, some of these options may not work, and you should instead generate a sample configuration file specific to your borgmatic version.

```yml
# Constants to use in the configuration file. Within option values,
# all occurrences of the constant name in curly braces will be
# replaced with the constant value. For example, if you have a
# constant named "app_name" with the value "myapp", then the string
# "{app_name}" will be replaced with "myapp" in the configuration
# file.
constants:
    app_name: myapp
    user: myuser

# List of source directories and files to back up. Globs and tildes
# are expanded. Do not backslash spaces in path names.
source_directories:
    - /home
    - /etc
    - /var/log/syslog*
    - /home/user/path with spaces

# A required list of local or remote repositories with paths and
# optional labels (which can be used with the --repository flag to
# select a repository). Tildes are expanded. Multiple repositories are
# backed up to in sequence. Borg placeholders can be used. See the
# output of "borg help placeholders" for details. See ssh_command for
# SSH options like identity file or port. If systemd service is used,
# then add local repository paths in the systemd service file to the
# ReadWritePaths list. Prior to borgmatic 1.7.10, repositories was a
# list of plain path strings.
repositories:
    - path: ssh://user@backupserver/./sourcehostname.borg
      label: backupserver
    - path: /mnt/backup
      label: local

# Working directory for the "borg create" command. Tildes are
# expanded. Useful for backing up using relative paths. See
# http://borgbackup.readthedocs.io/en/stable/usage/create.html for
# details. Defaults to not set.
working_directory: /path/to/working/directory

# Stay in same file system; do not cross mount points beyond the given
# source directories. Defaults to false. But when a database hook is
# used, the setting here is ignored and one_file_system is considered true.
one_file_system: true

# Only store/extract numeric user and group identifiers. Defaults to false.
numeric_ids: true

# Store atime into archive. Defaults to true in Borg < 1.2, false in
# Borg 1.2+.
atime: false

# Store ctime into archive. Defaults to true.
ctime: false

# Store birthtime (creation date) into archive. Defaults to true.
birthtime: false

# 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. But when a database hook is used, the setting here is ignored
# and read_special is considered true.
read_special: false

# Record filesystem flags (e.g. NODUMP, IMMUTABLE) in archive.
# Defaults to true.
flags: true

# Mode in which to operate the files cache. See
# http://borgbackup.readthedocs.io/en/stable/usage/create.html for
# details. Defaults to "ctime,size,inode".
files_cache: ctime,size,inode

# Alternate Borg local executable. Defaults to "borg".
local_path: borg1

# Alternate Borg remote executable. Defaults to "borg".
remote_path: borg1

# Any paths matching these patterns are included/excluded from
# backups. Globs are expanded. (Tildes are not.) See the output of
# "borg help patterns" for more details. Quote any value if it
# contains leading punctuation, so it parses correctly. Note that only
# one of "patterns" and "source_directories" may be used.
patterns:
    - R /
    - '- /home/*/.cache'
    - + /home/susan
    - '- /home/*'

# 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.
patterns_from:
    - /etc/borgmatic/patterns

# Any paths matching these patterns are excluded from backups. Globs
# and tildes are expanded. Note that a glob pattern must either start
# with a glob or be an absolute path. Do not backslash spaces in path
# names. See the output of "borg help patterns" for more details.
exclude_patterns:
    - '*.pyc'
    - /home/*/.cache
    - '*/.vim*.tmp'
    - /etc/ssl
    - /home/user/path with spaces

# Read exclude patterns from one or more separate named files, one
# pattern per line. See the output of "borg help patterns" for more
# details.
exclude_from:
    - /etc/borgmatic/excludes

# Exclude directories that contain a CACHEDIR.TAG file. See
# http://www.brynosaurus.com/cachedir/spec.html for details. Defaults
# to false.
exclude_caches: true

# Exclude directories that contain a file with the given filenames.
# Defaults to not set.
exclude_if_present:
    - .nobackup

# If true, the exclude_if_present filename is included in backups.
# Defaults to false, meaning that the exclude_if_present filename is omitted from backups.
keep_exclude_tags: true

# Exclude files with the NODUMP flag. Defaults to false.
exclude_nodump: true

# Path for additional source files used for temporary internal state like borgmatic database dumps. Note that changing this path prevents "borgmatic restore" from finding any database dumps created before the change. Defaults to ~/.borgmatic
borgmatic_source_directory: /tmp/borgmatic

# Store configuration files used to create a backup in the backup itself. Defaults to true. Changing this to false prevents "borgmatic bootstrap" from extracting configuration files from the backup.
store_config_files: false

# If true, then source directories must exist, otherwise an error is raised. Defaults to false.
source_directories_must_exist: true

# The standard output of this command is used to unlock the encryption key. Only use on repositories that were initialized with passcommand/repokey/keyfile encryption. Note that if both encryption_passcommand and encryption_passphrase are set, then encryption_passphrase takes precedence. Defaults to not set.
encryption_passcommand: secret-tool lookup borg-repository repo-name

# Passphrase to unlock the encryption key with. Only use on repositories that were initialized with passphrase/repokey/keyfile 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.
encryption_passphrase: "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"

# Number of seconds between each checkpoint during a long-running backup. See https://borgbackup.readthedocs.io/en/stable/faq.html for details. Defaults to checkpoints every 1800 seconds (30 minutes).
checkpoint_interval: 1800

# Number of backed up bytes between each checkpoint during a long-running backup. Only supported with Borg 2+. See
# https://borgbackup.readthedocs.io/en/stable/faq.html for details.
# Defaults to only time-based checkpointing (see "checkpoint_interval") instead of volume-based checkpointing.
checkpoint_volume: 1048576

# Specify the parameters passed to the 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".
chunker_params: 19,23,21,4095

# Type of compression to use when creating archives. See http://borgbackup.readthedocs.io/en/stable/usage/create.html for details. Defaults to "lz4".
compression: lz4

# Remote network upload rate limit in kiBytes/second. Defaults to unlimited.
upload_rate_limit: 100

# Number of times to retry a failing backup before giving up. Defaults to 0 (i.e., does not attempt retry).
retries: 3

# Wait time between retries (in seconds) to allow transient issues to pass. Increases after each retry by that same wait time as a form of backoff. Defaults to 0 (no wait).
retry_wait: 10

# Directory where temporary Borg files are stored. Defaults to $TMPDIR. See "Resource Usage" at https://borgbackup.readthedocs.io/en/stable/usage/general.html for details.
temporary_directory: /path/to/tmpdir

# Command to use instead of "ssh". This can be used to specify ssh options. Defaults to not set.
ssh_command: ssh -i /path/to/private/key

# Base path used for various Borg directories. Defaults to $HOME, ~$USER, or ~.
borg_base_directory: /path/to/base

# Path for Borg configuration files. Defaults to $borg_base_directory/.config/borg
borg_config_directory: /path/to/base/config

# Path for Borg cache files. Defaults to $borg_base_directory/.cache/borg
borg_cache_directory: /path/to/base/cache

# Maximum time to live (ttl) for entries in the Borg files cache.
borg_files_cache_ttl: 20

# Path for Borg security and encryption nonce files. Defaults to $borg_base_directory/.config/borg/security
borg_security_directory: /path/to/base/config/security

# Path for Borg encryption key files. Defaults to $borg_base_directory/.config/borg/keys
borg_keys_directory: /path/to/base/config/keys

# A list of Borg exit codes that should be elevated to errors or squashed to warnings as indicated. By default, Borg error exit codes (2 to 99) are treated as errors while warning exit codes (1 and 100+) are treated as warnings. Exit codes other than 1 and 2 are only present in Borg 1.4.0+.
borg_exit_codes:
    - code: 13
      treat_as: warning
    - code: 100
      treat_as: error

# Umask used for when executing Borg or calling hooks. Defaults to 0077 for Borg or the umask that borgmatic is run with for hooks.
umask: 77

# Maximum seconds to wait for acquiring a repository/cache lock.
# Defaults to 1.
lock_wait: 5

# 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}". When running actions like rlist, info, or check, borgmatic automatically tries to match only archives created with this name format.
archive_name_format: '{hostname}-documents-{now}'

# A Borg pattern for filtering down the archives used by borgmatic actions that operate on multiple archives. For Borg 1.x, use a shell pattern here and see the output of "borg help placeholders" for details. For Borg 2.x, see the output of "borg help match-archives". If match_archives is not specified, borgmatic defaults to deriving the match_archives value from archive_name_format.
match_archives: sh:{hostname}-*

# Bypass Borg error about a repository that has been moved. Defaults to not bypassing.
relocated_repo_access_is_ok: true

# Bypass Borg error about a previously unknown unencrypted repository.
# Defaults to not bypassing.
unknown_unencrypted_repo_access_is_ok: true

# Bypass Borg confirmation about check with repair option. Defaults to an interactive prompt from Borg.
check_i_know_what_i_am_doing: true

# Additional options to pass directly to particular Borg commands, handy for Borg options that borgmatic does not yet support natively.
# Note that borgmatic does not perform any validation on these options. Running borgmatic with "--verbosity 2" shows the exact Borg command-line invocation.
extra_borg_options:
    # Extra command-line options to pass to "borg init".
    init: --extra-option

    # Extra command-line options to pass to "borg create".
    create: --extra-option

    # Extra command-line options to pass to "borg prune".
    prune: --extra-option

    # Extra command-line options to pass to "borg compact".
    compact: --extra-option

    # Extra command-line options to pass to "borg check".
    check: --extra-option

# Keep all archives within this time interval. See "skip_actions" for disabling pruning altogether.
keep_within: 3H

# Number of secondly archives to keep.
keep_secondly: 60

# Number of minutely archives to keep.
keep_minutely: 60

# Number of hourly archives to keep.
keep_hourly: 24

# Number of daily archives to keep.
keep_daily: 7

# Number of weekly archives to keep.
keep_weekly: 4

# Number of monthly archives to keep.
keep_monthly: 6

# Number of yearly archives to keep.
keep_yearly: 1

# Deprecated. When pruning or checking archives, only consider archive names starting with this prefix. Borg placeholders can be used. See the output of "borg help placeholders" for details. If a prefix is not specified, borgmatic defaults to matching archives based on the archive_name_format (see above).
prefix: sourcehostname

# List of one or more consistency checks to run on a periodic basis (if "frequency" is set) or every time borgmatic runs checks (if "frequency" is omitted).
checks:
    # Name of consistency check to run: "repository",
    # "archives", "data", and/or "extract". "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". See "skip_actions" for disabling checks altogether.
    - name: repository

      # How frequently to run this type of consistency check (as a best effort). The value is a number followed by a unit of time. E.g., "2 weeks" to run this consistency check no more than every two weeks for a given repository or "1 month" to run it no more than monthly. Defaults to "always": running this check every time checks are run.
      frequency: 2 weeks

# Paths or labels for a subset of the configured "repositories" (see above) 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 configured repositories.
check_repositories:
    - user@backupserver:sourcehostname.borg

# Restrict the number of checked archives to the last n. Applies only to the "archives" check. Defaults to checking all archives.
check_last: 3

# Apply color to console output. Can be overridden with --no-color command-line flag. Defaults to true.
color: false

# List of one or more actions to skip running for this configuration file, even if specified on the command-line (explicitly or implicitly). This is handy for append-only configurations where you never want to run "compact" or checkless configuration where you want to skip "check". Defaults to not skipping any actions.
skip_actions:
    - compact

# List of one or more shell commands or scripts to execute before allthe actions for each repository.
before_actions:
    - echo Starting actions.

# List of one or more shell commands or scripts to execute before creating a backup, run once per repository.
before_backup:
    - echo Starting a backup.

# List of one or more shell commands or scripts to execute before pruning, run once per repository.
before_prune:
    - echo Starting pruning.

# List of one or more shell commands or scripts to execute before compaction, run once per repository.
before_compact:
    - echo Starting compaction.

# List of one or more shell commands or scripts to execute before consistency checks, run once per repository.
before_check:
    - echo Starting checks.

# List of one or more shell commands or scripts to execute before extracting a backup, run once per repository.
before_extract:
    - echo Starting extracting.

# List of one or more shell commands or scripts to execute after creating a backup, run once per repository.
after_backup:
    - echo Finished a backup.

# List of one or more shell commands or scripts to execute after compaction, run once per repository.
after_compact:
    - echo Finished compaction.

# List of one or more shell commands or scripts to execute after pruning, run once per repository.
after_prune:
    - echo Finished pruning.

# List of one or more shell commands or scripts to execute after consistency checks, run once per repository.
after_check:
    - echo Finished checks.

# List of one or more shell commands or scripts to execute after extracting a backup, run once per repository.
after_extract:
    - echo Finished extracting.

# List of one or more shell commands or scripts to execute after all actions for each repository.
after_actions:
    - echo Finished actions.

# List of one or more shell commands or scripts to execute when an exception occurs during a "create", "prune", "compact", or "check" action or an associated before/after hook.
on_error:
    - echo Error during create/prune/compact/check.

# List of one or more shell commands or scripts to execute before running all actions (if one of them is "create"). These are collected from all configuration files and then run once before all of them (prior to all actions).
before_everything:
    - echo Starting actions.

# List of one or more shell commands or scripts to execute after running all actions (if one of them is "create"). These are collected from all configuration files and then run once after all of them (after any action).
after_everything:
    - echo Completed actions.

# 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 and streamed directly to Borg. Requires pg_dump/pg_dumpall/pg_restore commands. See https://www.postgresql.org/docs/current/app-pgdump.html and https://www.postgresql.org/docs/current/libpq-ssl.html for details.
postgresql_databases:
    # Database name (required if using this hook). Or "all" to dump all databases on the host. (Also set the "format" to dump each database to a separate file instead of one combined file.) Note that using this database hook implicitly enables both read_special and one_file_system (see above) to support dump and restore streaming.
    - name: users

      # Database hostname to connect to. Defaults to connecting via local Unix socket.
      hostname: database.example.org

      # Database hostname to restore to. Defaults to the "hostname" option.
      restore_hostname: database.example.org

      # Port to connect to. Defaults to 5432.
      port: 5433

      # Port to restore to. Defaults to the "port" option.
      restore_port: 5433

      # 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".
      username: dbuser

      # Username with which to restore the database. Defaults to the "username" option.
      restore_username: dbuser

      # 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.
      password: trustsome1

      # Password with which to connect to the restore database. Defaults to the "password" option.
      restore_password: trustsome1

      # Do not output commands to set ownership of objects to match the original database. By default, pg_dump and pg_restore issue ALTER OWNER or SET SESSION AUTHORIZATION statements to set ownership of created schema elements. These statements will fail unless the initial connection to the database is made by a superuser.
      no_owner: true

      # Database dump output format. One of "plain", "custom", "directory", or "tar". Defaults to "custom" (unlike raw pg_dump) for a single database. Or, when database name is "all" and format is blank, dumps all databases to a single file. But if a format is specified with an "all" database name, dumps each database to a separate file of that format, allowing more convenient restores of individual databases. See the pg_dump documentation for more about formats.
      format: directory

      # SSL mode to use to connect to the database server. One of "disable", "allow", "prefer", "require", "verify-ca" or "verify-full". Defaults to "disable".
      ssl_mode: require

      # Path to a client certificate.
      ssl_cert: /root/.postgresql/postgresql.crt

      # Path to a private client key.
      ssl_key: /root/.postgresql/postgresql.key

      # Path to a root certificate containing a list of trusted certificate authorities.
      ssl_root_cert: /root/.postgresql/root.crt

      # Path to a certificate revocation list.
      ssl_crl: /root/.postgresql/root.crl

      # Command to use instead of "pg_dump" or "pg_dumpall". This can be used to run a specific pg_dump version (e.g., one inside a running container). Defaults to "pg_dump" for single database dump or "pg_dumpall" to dump all databases.
      pg_dump_command: docker exec my_pg_container pg_dump

      # Command to use instead of "pg_restore". This can be used to run a specific pg_restore version (e.g., one inside a running container). Defaults to "pg_restore".
      pg_restore_command: docker exec my_pg_container pg_restore

      # Command to use instead of "psql". This can be used to run a specific psql version (e.g., one inside a running container). Defaults to "psql".
      psql_command: docker exec my_pg_container psql

      # Additional pg_dump/pg_dumpall options to pass directly to the dump command, without performing any validation on them. See pg_dump documentation for details.
      options: --role=someone

      # Additional psql options to pass directly to the psql command that lists available databases, without performing any validation on them. See psql documentation for details.
      list_options: --role=someone

      # Additional pg_restore/psql options to pass directly to the restore command, without performing any validation on them. See pg_restore/psql documentation for details.
      restore_options: --role=someone

      # Additional psql options to pass directly to the analyze command run after a restore, without performing any validation on them. See psql documentation for details.
      analyze_options: --role=someone

# List of one or more MariaDB databases to dump before creating a backup, run once per configuration file. The database dumps are added to your source directories at runtime and streamed directly to Borg. Requires mariadb-dump/mariadb commands. See https://mariadb.com/kb/en/library/mysqldump/ for details.
mariadb_databases:
    # Database name (required if using this hook). Or "all" to dump all databases on the host. Note that using this database hook implicitly enables both read_special and one_file_system (see above) to support dump and restore streaming.
    - name: users

      # Database hostname to connect to. Defaults to connecting via local Unix socket.
      hostname: database.example.org

      # Database hostname to restore to. Defaults to the "hostname" option.
      restore_hostname: database.example.org

      # Port to connect to. Defaults to 3306.
      port: 3307

      # Port to restore to. Defaults to the "port" option.
      restore_port: 5433

      # Username with which to connect to the database. Defaults to the username of the current user.
      username: dbuser

      # Username with which to restore the database. Defaults to the "username" option.
      restore_username: dbuser

      # Password with which to connect to the database. Omitting a password will only work if MariaDB is configured to trust the configured username without a password.
      password: trustsome1

      # Command to use instead of "mariadb-dump". This can be used to run a specific mariadb_dump version (e.g., one inside a running container). Defaults to "mariadb-dump".
      mariadb_dump_command: docker exec mariadb_container mariadb-dump

      # Command to run instead of "mariadb". This can be used to run a specific mariadb version (e.g., one inside a running container). Defaults to "mariadb".
      mariadb_command: docker exec mariadb_container mariadb

      # Password with which to connect to the restore database. Defaults to the "password" option.
      restore_password: trustsome1

      # Database dump output format. Currently only "sql" is supported. Defaults to "sql" for a single database. Or, when database name is "all" and format is blank, dumps all databases to a single file. But if a format is specified with an "all" database name, dumps each database to a separate file of that format, allowing more convenient restores of individual databases.
      format: directory

      # Use the "--add-drop-database" flag with mariadb-dump, causing the database to be dropped right before restore. Defaults to true.
      add_drop_database: false

      # Additional mariadb-dump options to pass directly to the dump command, without performing any validation on them. See mariadb-dump documentation for details.
      options: --skip-comments

      # Additional options to pass directly to the mariadb command that lists available databases, without performing any validation on them. See mariadb command documentation for details.
      list_options: --defaults-extra-file=mariadb.cnf

      # Additional options to pass directly to the mariadb command that restores database dumps, without performing any validation on them. See mariadb command documentation for details.
      restore_options: --defaults-extra-file=mariadb.cnf

# List of one or more MySQL databases to dump before creating a backup, run once per configuration file. The database dumps are added to your source directories at runtime and streamed directly to Borg. Requires mysqldump/mysql commands. See https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html for details.
mysql_databases:
    # Database name (required if using this hook). Or "all" to dump all databases on the host. Note that using this database hook implicitly enables both read_special and one_file_system (see above) to support dump and restore streaming.
    - name: users

      # Database hostname to connect to. Defaults to connecting via local Unix socket.
      hostname: database.example.org

      # Database hostname to restore to. Defaults to the "hostname" option.
      restore_hostname: database.example.org

      # Port to connect to. Defaults to 3306.
      port: 3307

      # Port to restore to. Defaults to the "port" option.
      restore_port: 5433

      # Username with which to connect to the database. Defaults to the username of the current user.
      username: dbuser

      # Username with which to restore the database. Defaults to the "username" option.
      restore_username: dbuser

      # Password with which to connect to the database. Omitting a password will only work if MySQL is configured to trust the configured username without a password.
      password: trustsome1

      # Password with which to connect to the restore database. Defaults to the "password" option.
      restore_password: trustsome1

      # Command to use instead of "mysqldump". This can be used to run a specific mysql_dump version (e.g., one inside a running container). Defaults to "mysqldump".
      mysql_dump_command: docker exec mysql_container mysqldump

      # Command to run instead of "mysql". This can be used to run a specific mysql version (e.g., one inside a running container). Defaults to "mysql".
      mysql_command: docker exec mysql_container mysql

      # Database dump output format. Currently only "sql" is supported. Defaults to "sql" for a single database. Or, when database name is "all" and format is blank, dumps all databases to a single file. But if a format is specified with an "all" database name, dumps each database to a separate file of that format, allowing more convenient restores of individual databases.
      format: directory

      # Use the "--add-drop-database" flag with mysqldump, causing the database to be dropped right before restore.
      # Defaults to true.
      add_drop_database: false

      # Additional mysqldump options to pass directly to the dump command, without performing any validation on them. See mysqldump documentation for details.
      options: --skip-comments

      # Additional options to pass directly to the mysql command that lists available databases, without performing any validation on them. See mysql command documentation for details.
      list_options: --defaults-extra-file=my.cnf

      # Additional options to pass directly to the mysql command that restores database dumps, without performing any validation on them. See mysql command documentation for details.
      restore_options: --defaults-extra-file=my.cnf

sqlite_databases:
    # This is used to tag the database dump file with a name. It is not the path to the database file itself. The name "all" has no special meaning for SQLite databases.
    - name: users

      # Path to the SQLite database file to dump. If relative, it is relative to the current working directory. Note that using this database hook implicitly enables both read_special and one_file_system (see above) to support dump and restore streaming.
      path: /var/lib/sqlite/users.db

      # Path to the SQLite database file to restore to. Defaults to the "path" option.
      restore_path: /var/lib/sqlite/users.db

# List of one or more MongoDB databases to dump before creating a backup, run once per configuration file. The database dumps are added to your source directories at runtime and streamed directly to Borg. Requires mongodump/mongorestore commands. See https://docs.mongodb.com/database-tools/mongodump/ and https://docs.mongodb.com/database-tools/mongorestore/ for details.
mongodb_databases:
    # Database name (required if using this hook). Or "all" to dump all databases on the host. Note that using this database hook implicitly enables both read_special and one_file_system (see above) to support dump and restore streaming.
    - name: users

      # Database hostname to connect to. Defaults to connecting to localhost.
      hostname: database.example.org

      # Database hostname to restore to. Defaults to the "hostname" option.
      restore_hostname: database.example.org

      # Port to connect to. Defaults to 27017.
      port: 27018

      # Port to restore to. Defaults to the "port" option.
      restore_port: 5433

      # Username with which to connect to the database. Skip it if no authentication is needed.
      username: dbuser

      # Username with which to restore the database. Defaults to the "username" option.
      restore_username: dbuser

      # Password with which to connect to the database. Skip it if no authentication is needed.
      password: trustsome1

      # Password with which to connect to the restore database. Defaults to the "password" option.
      restore_password: trustsome1

      # Authentication database where the specified username exists. If no authentication database is specified, the database provided in "name" is used. If "name" is "all", the "admin" database is used.
      authentication_database: admin

      # Database dump output format. One of "archive", or "directory". Defaults to "archive". See mongodump documentation for details. Note that format is ignored when the database name is "all".
      format: directory

      # Additional mongodump options to pass directly to the dump command, without performing any validation on them. See mongodump documentation for details.
      options: --dumpDbUsersAndRoles

      # Additional mongorestore options to pass directly to the dump command, without performing any validation on them. See mongorestore documentation for details.
      restore_options: --restoreDbUsersAndRoles

ntfy:
    # The topic to publish to. See https://ntfy.sh/docs/publish/ for details.
    topic: topic

    # The address of your self-hosted ntfy.sh instance.
    server: https://ntfy.your-domain.com

    # The username used for authentication.
    username: testuser

    # The password used for authentication.
    password: fakepassword

    start:
        # The title of the message.
        title: Ping!

        # The message body to publish.
        message: Your backups have failed.

        # The priority to set.
        priority: urgent

        # Tags to attach to the message.
        tags: incoming_envelope

    finish:
        # The title of the message.
        title: Ping!

        # The message body to publish.
        message: Your backups have failed.

        # The priority to set.
        priority: urgent

        # Tags to attach to the message.
        tags: incoming_envelope

    fail:
        # The title of the message.
        title: Ping!

        # The message body to publish.
        message: Your backups have failed.

        # The priority to set.
        priority: urgent

        # Tags to attach to the message.
        tags: incoming_envelope

    # List of one or more monitoring states to ping for: "start", "finish", and/or "fail". Defaults to pinging for failure only.
    states:
        - start
        - finish

apprise:
    # A list of Apprise services to publish to with URLs and labels. The labels are used for logging. A full list of services and their configuration can be found at https://github.com/caronc/apprise/wiki.
    services:
        - url: kodi://user@hostname
          label: kodi
        - url: line://Token@User
          label: line

    start:
        # Specify the message title. If left unspecified, no title is sent.
        title: Ping!

        # Specify the message body.
        body: Starting backup process.

    finish:
        # Specify the message title. If left unspecified, no title is sent.
        title: Ping!

        # Specify the message body.
        body: Backups successfully made.

    fail:
        # Specify the message title. If left unspecified, no title is sent.
        title: Ping!

        # Specify the message body.
        body: Your backups have failed.

    # List of one or more monitoring states to ping for: "start", "finish", and/or "fail". Defaults to pinging for failure only. For each selected state, corresponding configuration for the message title and body should be given. If any is left unspecified, a generic message is emitted instead.
    states:
        - start
        - finish

# Configuration for a monitoring integration with Healthchecks. Create an account at https://healthchecks.io (or self-host Healthchecks) if you'd like to use this service. See borgmatic monitoring documentation for details.
healthchecks:
    # Healthchecks ping URL or UUID to notify when a backup begins, ends, errors, or to send only logs.
    ping_url: https://hc-ping.com/your-uuid-here

    # Verify the TLS certificate of the ping URL host. Defaults to true.
    verify_tls: false

    # Send borgmatic logs to Healthchecks as part the "finish", "fail", and "log" states. Defaults to true.
    send_logs: false

    # Number of bytes of borgmatic logs to send to Healthchecks, ideally the same as PING_BODY_LIMIT configured on the Healthchecks server. Set to 0 to send all logs and disable this truncation. Defaults to 100000.
    ping_body_limit: 200000

    # List of one or more monitoring states to ping for: "start", "finish", "fail", and/or "log". Defaults to pinging for all states.
    states:
        - finish

# Configuration for a monitoring integration with Cronitor. Create an account at https://cronitor.io if you'd like to use this service. See borgmatic monitoring documentation for details.
cronitor:
    # Cronitor ping URL to notify when a backup begins, ends, or errors.
    ping_url: https://cronitor.link/d3x0c1

# Configuration for a monitoring integration with PagerDuty. Create an account at https://www.pagerduty.com if you'd like to use this service. See borgmatic monitoring documentation for details.
pagerduty:
    # PagerDuty integration key used to notify PagerDuty when a backup errors.
    integration_key: a177cad45bd374409f78906a810a3074

# Configuration for a monitoring integration with Cronhub. Create an account at https://cronhub.io if you'd like to use this service. See borgmatic monitoring documentation for details.
cronhub:
    # Cronhub ping URL to notify when a backup begins, ends, or errors.
    ping_url: https://cronhub.io/ping/1f5e3410-254c-5587

# Configuration for a monitoring integration with Grafana loki. You can send the logs to a self-hosted instance or create an account at https://grafana.com/auth/sign-up/create-user. See borgmatic monitoring documentation for details.
loki:
    # Grafana loki log URL to notify when a backup begins, ends, or fails.
    url: http://localhost:3100/loki/api/v1/push

    # Allows setting custom labels for the logging stream. At least one label is required. "__hostname" gets replaced by the machine hostname automatically. "__config" gets replaced by just the name of the configuration file. "__config_path" gets replaced by the full path of the configuration file.
    labels:
        app: borgmatic
        config: __config
        hostname: __hostname
```

## CLI
Here are all of the available borgmatic command-line flags for the most recent version of borgmatic, including the separate flags for each action (sub-command).Most of the flags listed here do not have equivalents in borgmatic's configuration file.

### Global Options
| Option                              | Description                                                                                                                                             |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-c, --config CONFIG_PATHS`         | Configuration filename or directory                                                                                                                     |
| `-n, --dry-run`                     | Go through but do not actually write to any repositories                                                                                                |
| `-v, --verbosity {-2,-1,0,1,2}`     | Verbose Output                                                                                                                                          |
| `--log-file LOG_FILE`               | Write [log](../../dev/Log.md) messages to this file instead of syslog                                                                                   |
| `--log-json`                        | Write [log](../../dev/Log.md) messages and console output as one [JSON](../../files/JSON.md) object per log line instead of formatted text              |
| `--override OPTION.SUBOPTION=VALUE` | Configuration file option to override with specified value, see documentation for overriding list or key/value options, can specify flag multiple times |

### borgmatic rcreate
Create a new, empty [Borg](borg.md) repository

| Option                               | Description                                                                                                                                                    |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-e ENCRYPTION_MODE`                 | Borg repository encryption mode                                                                                                                                |
| `--source-repository KEY_REPOSITORY` | Path to an existing Borg repository whose key material should be reused [Borg 2.x+ only]                                                                       |
| `--repository REPOSITORY`            | Path of the new repository to create (must be already specified in a borgmatic configuration file), defaults to the configured repository if there is only one |
| `--copy-crypt-key`                   | Copy the crypt key used for authenticated encryption from the source repository, defaults to a new random key [Borg 2.x+ only]                                 |
| `--append-only`                      | Create an append-only repository                                                                                                                               |
| `--storage-quota STORAGE_QUOTA`      | Create a repository with a fixed storage quota                                                                                                                 |
| `--make-parent-dirs`                 | Create any missing parent directories of the repository directory                                                                                              |

### borgmatic transfer
Transfer archives from one repository to another, optionally upgrading the transferred data [Borg 2.0+only]

| Option                                                                    | Description                                                                                                                                                |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY`                                                 | Path of existing destination repository to transfer archives to, defaults to the configured repository if there is only one                                |
| `--source-repository SOURCE_REPOSITORY`                                   | Path of existing source repository to transfer archives from                                                                                               |
| `--archive ARCHIVE`                                                       | Name of single archive to transfer (or "latest"), defaults to transferring all archives                                                                    |
| `--upgrader UPGRADER`                                                     | Upgrader type used to convert the transferred data, e.g. "From12To20" to upgrade data from Borg 1.2 to 2.0 format, defaults to no conversion               |
| `--progress`                                                              | Display progress as each archive is transferred                                                                                                            |
| `-a PATTERN`,<br>`--match-archives PATTERN`,<br>`--glob-archives PATTERN` | Only transfer archives with names matching this pattern                                                                                                    |
| `--sort-by KEYS`                                                          | Comma-separated list of sorting keys                                                                                                                       |
| `--first N`                                                               | Only transfer first N archives after other filters are applied                                                                                             |
| `--last N`                                                                | Only transfer last N archives after other filters are applied                                                                                              |
| `--oldest TIMESPAN`                                                       | Transfer archives within a specified time range starting from the timestamp of the oldest archive (e.g. 7d or 12m) [Borg 2.x+ only]                        |
| `--newest TIMESPAN`                                                       | Transfer archives within a time range that ends at timestamp of the newest archive and starts a specified time range ago (e.g. 7d or 12m) [Borg 2.x+ only] |
| `--older TIMESPAN`                                                        | Transfer archives that are older than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]                                     |
| `--newer TIMESPAN`                                                        | Transfer archives that are newer than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]                                     |


### borgmatic create
Create an archive (actually perform a backup)

| Option                    | Description                                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY` | Path of specific existing repository to backup to (must be already specified in a borgmatic configuration file) |
| `--progress`              | Display progress for each file as it is backed up                                                               |
| `--stats`                 | Display statistics of archive                                                                                   |
| `--list`,<br>`--files`    | Show per-file details                                                                                           |
| `--json`                  | Output results as [JSON](../../files/JSON.md)                                                                   |


### borgmatic prune
Prune archives according to the retention policy (with Borg 1.2+, you must run compact afterwards to actually free space)

| Option                    | Description                                                                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY` | Path of specific existing repository to prune (must be already specified in a borgmatic configuration file)                                             |
| `--stats`                 | Display statistics of archive                                                                                                                           |
| `--list`                  | List archives kept/pruned                                                                                                                               |
| `--oldest TIMESPAN`       | Prune archives within a specified time range starting from the timestamp of the oldest archive (e.g. 7d or 12m) [Borg 2.x+ only]                        |
| `--newest TIMESPAN`       | Prune archives within a time range that ends at timestamp of the newest archive and starts a specified time range ago (e.g. 7d or 12m) [Borg 2.x+ only] |
| `--older TIMESPAN`        | Prune archives that are older than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]                                     |
| `--newer TIMESPAN`        | Prune archives that are newer than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]                                     |



### borgmatic compact
Compact segments to free space [Borg 1.2+, borgmatic 1.5.23+ only]

| Option                    | Description                                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY` | Path of specific existing repository to compact (must be already specified in a borgmatic configuration file) |
| `--progress`              | Display progress as each segment is compacted                                                                 |
| `--cleanup-commits`       | Cleanup commit-only 17-byte segment files left behind by Borg 1.1 [flag in Borg 1.2 only]                     |
| `--threshold THRESHOLD`   | Minimum saved space percentage threshold for compacting a segment, defaults to 10                             |

### borgmatic check
Check archives for consistency

| Option                                                                    | Description                                                                                                                                                                 |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY`                                                 | Path of specific existing repository to check (must be already specified in a borgmatic configuration file)                                                                 |
| `--progress`                                                              | Display progress for each file as it is checked                                                                                                                             |
| `--repair`                                                                | Attempt to repair any inconsistencies found (for interactive use)                                                                                                           |
| `-a PATTERN`,<br>`--match-archives PATTERN`,<br>`--glob-archives PATTERN` | Only check archives with names matching this pattern                                                                                                                        |
| `--only CHECK`                                                            | Run a particular consistency check (repository, archives, data, or extract) instead of configured checks (subject to configured frequency, can specify flag multiple times) |
| `--force`                                                                 | Ignore configured check frequencies and run checks unconditionally                                                                                                          |

### borgmatic extract
Extract files from a named archive to the current directory

| Option                                  | Description                                                                                                                                        |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY`               | Path of repository to extract, defaults to the configured repository if there is only one                                                          |
| `--archive ARCHIVE`                     | Name of archive to extract (or "latest")                                                                                                           |
| `--path PATH`,<br>`--restore-path PATH` | Path to extract from archive, can specify flag multiple times, defaults to the entire archive                                                      |
| `--destination PATH`                    | Directory to extract files into, defaults to the current directory                                                                                 |
| `--strip-components NUMBER`             | Number of leading path components to remove from each extracted path or "all" to strip all leading path components. Skip paths with fewer elements |
| `--progress`                            | Display progress for each file as it is extracted                                                                                                  |

### borgmatic config
Perform configuration file related operations

#### borgmatic config bootstrap
Extract the borgmatic configuration files from a named archive

| Option                                                    | Description                                                                                                                                                                       |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY`                                 | Path of repository to extract config files from                                                                                                                                   |
| `--borgmatic-source-directory BORGMATIC_SOURCE_DIRECTORY` | Path that stores the config files used to create an archive and additional source files used for temporary internal state like borgmatic database dumps. Defaults to ~/.borgmatic |
| `--archive ARCHIVE`                                       | Name of archive to extract config files from, defaults to "latest"                                                                                                                |
| `--destination PATH`                                      | Directory to extract config files into, defaults to /                                                                                                                             |
| `--strip-components NUMBER`                               | Number of leading path components to remove from each extracted path or "all" to strip all leading path components. Skip paths with fewer elements                                |
| `--progress`                                              | Display progress for each file as it is extracted                                                                                                                                 |
| `--ssh-command COMMAND`                                   | Command to use instead of "[ssh](../network/SSH.md)"                                                                                                                              |

#### borgmatic config generate
Generate a sample borgmatic configuration file

| Option                                                             | Description                                                                                                    |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `-s SOURCE_FILENAME`,<br>`--source SOURCE_FILENAME`                | Optional configuration file to merge into the generated configuration, useful for upgrading your configuration |
| `-d DESTINATION_FILENAME`,<br>`--destination DESTINATION_FILENAME` | Destination configuration file, default: /etc/borgmatic/config.yaml                                            |
| `--overwrite`                                                      | Whether to overwrite any existing destination file, defaults to false                                          |

#### borgmatic config validate
Validate borgmatic configuration files specified with `--config`

### borgmatic export-tar
Export an archive to a [tar](../cli/compression/tar.md)-formatted file or stream

| Option                      | Description                                                                                         |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY`   | Path of repository to export from, defaults to the configured repository if there is only one       |
| `--archive ARCHIVE`         | Name of archive to export (or "latest")                                                             |
| `--path PATH`               | Path to export from archive, can specify flag multiple times, defaults to the entire archive        |
| `--destination PATH`        | Path to destination export tar file, or "-" for stdout                                              |
| `--tar-filter TAR_FILTER`   | Name of filter program to pipe data through                                                         |
| `--list`,<br>`--files`      | Show per-file details                                                                               |
| `--strip-components NUMBER` | Number of leading path components to remove from each exported path. Skip paths with fewer elements |

### borgmatic mount
Mount a named archive as a FUSE filesystem

| Option                    | Description                                                                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY` | Path of repository to use, defaults to the configured repository if there is only one                                                  |
| `--archive ARCHIVE`       | Name of archive to mount (or "latest")                                                                                                 |
| `--mount-point PATH`      | Path where filesystem is to be mounted                                                                                                 |
| `--path PATH`             | Path to mount from archive, can specify multiple times, defaults to the entire archive                                                 |
| `--foreground`            | Stay in foreground until ctrl-C is pressed                                                                                             |
| `--first N`               | Mount first N archives after other filters are applied                                                                                 |
| `--last N`                | Mount last N archives after other filters are applied                                                                                  |
| `--oldest TIMESPAN`       | Mount archives within a specified time range starting from the timestamp of the oldest archive [Borg 2.x+ only]                        |
| `--newest TIMESPAN`       | Mount archives within a time range that ends at timestamp of the newest archive and starts a specified time range ago [Borg 2.x+ only] |
| `--older TIMESPAN`        | Mount archives that are older than the specified time range from the current time [Borg 2.x+ only]                                     |
| `--newer TIMESPAN`        | Mount archives that are newer than the specified time range from the current time [Borg 2.x+ only]                                     |
| `--options OPTIONS`       | Extra Borg mount options                                                                                                               |

### borgmatic umount
Unmount a mounted FUSE filesystem

| Option               | Description                   |
| -------------------- | ----------------------------- |
| `--mount-point PATH` | Path of filesystem to unmount |

### borgmatic restore
Restore data source (e.g. database) dumps from a named archive. (To extract
files instead, use "borgmatic extract".)

| Option                                     | Description                                                                                                                                                                                            |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--repository REPOSITORY`                  | Path of repository to restore from, defaults to the configured repository if there is only one                                                                                                         |
| `--archive ARCHIVE`                        | Name of archive to restore from (or "latest")                                                                                                                                                          |
| `--data-source NAME`,<br>`--database NAME` | Name of data source (e.g. database) to restore from archive, must be defined in borgmatic's configuration, can specify flag multiple times, defaults to all data sources in the archive                |
| `--schema NAME`                            | Name of schema to restore from the data source, can specify flag multiple times, defaults to all schemas. Schemas are only supported for PostgreSQL and [MongoDB](../development/MongoDB.md) databases |
| `--hostname HOSTNAME`                      | Database hostname to restore to. Defaults to the "restore_hostname" option in borgmatic's configuration                                                                                                |
| `--port PORT`                              | Database port to restore to. Defaults to the "restore_port" option in borgmatic's configuration                                                                                                        |
| `--username USERNAME`                      | Username with which to connect to the database. Defaults to the "restore_username" option in borgmatic's configuration                                                                                 |
| `--password PASSWORD`                      | Password with which to connect to the restore database. Defaults to the "restore_password" option in borgmatic's configuration                                                                         |
| `--restore-path RESTORE_PATH`              | Path to restore SQLite database dumps to. Defaults to the "restore_path" option in borgmatic's configuration                                                                                           |

### borgmatic rlist
List the archives in a repository

| Option                                                                    | Description                                                                                                                           |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY`                                                 | Path of repository to list, defaults to the configured repositories                                                                   |
| `--short`                                                                 | Output only archive names                                                                                                             |
| `--format FORMAT`                                                         | Format for archive listing                                                                                                            |
| `--json`                                                                  | Output results as [JSON](../../files/JSON.md)                                                                                         |
| `-P PREFIX`,<br>`--prefix PREFIX`                                         | Deprecated. Only list archive names starting with this prefix                                                                         |
| `-a PATTERN`,<br>`--match-archives PATTERN`,<br>`--glob-archives PATTERN` | Only list archive names matching this pattern                                                                                         |
| `--sort-by KEYS`                                                          | Comma-separated list of sorting keys                                                                                                  |
| `--first N`                                                               | List first N archives after other filters are applied                                                                                 |
| `--last N`                                                                | List last N archives after other filters are applied                                                                                  |
| `--oldest TIMESPAN`                                                       | List archives within a specified time range starting from the timestamp of the oldest archive [Borg 2.x+ only]                        |
| `--newest TIMESPAN`                                                       | List archives within a time range that ends at timestamp of the newest archive and starts a specified time range ago [Borg 2.x+ only] |
| `--older TIMESPAN`                                                        | List archives that are older than the specified time range from the current time [Borg 2.x+ only]                                     |
| `--newer TIMESPAN`                                                        | List archives that are newer than the specified time range from the current time [Borg 2.x+ only]                                     |

### borgmatic list
List the files in an archive or search for a file across archives

| Option                                                                    | Description                                                                                                                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY`                                                 | Path of repository containing archive to list, defaults to the configured repositories                                                            |
| `--archive ARCHIVE`                                                       | Name of the archive to list (or "latest")                                                                                                         |
| `--path PATH`                                                             | Path or pattern to list from a single selected archive (via "--archive"), can specify flag multiple times, defaults to listing the entire archive |
| `--find PATH`                                                             | Partial path or pattern to search for and list across multiple archives, can specify flag multiple times                                          |
| `--short`                                                                 | Output only path names                                                                                                                            |
| `--format FORMAT`                                                         | Format for file listing                                                                                                                           |
| `--json`                                                                  | Output results as [JSON](../../files/JSON.md)                                                                                                     |
| `-P PREFIX`,<br>`--prefix PREFIX`                                         | Deprecated. Only list archive names starting with this prefix                                                                                     |
| `-a PATTERN`,<br>`--match-archives PATTERN`,<br>`--glob-archives PATTERN` | Only list archive names matching this pattern                                                                                                     |
| `--sort-by KEYS`                                                          | Comma-separated list of sorting keys                                                                                                              |
| `--first N`                                                               | List first N archives after other filters are applied                                                                                             |
| `--last N`                                                                | List last N archives after other filters are applied                                                                                              |
| `-e PATTERN`,<br>`--exclude PATTERN`                                      | Exclude paths matching the pattern                                                                                                                |
| `--exclude-from FILENAME`                                                 | Exclude paths from exclude file, one per line                                                                                                     |
| `--pattern PATTERN`                                                       | Include or exclude paths matching a pattern                                                                                                       |
| `--patterns-from FILENAME`                                                | Include or exclude paths matching patterns from pattern file, one per line                                                                        |

### borgmatic rinfo
Show repository summary information such as disk space used

| Option                    | Description                                                                                     |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY` | Path of repository to show info for, defaults to the configured repository if there is only one |
| `--json`                  | Output results as [JSON](../../files/JSON.md)                                                   |

### borgmatic info
Show archive summary information such as disk space used

| Option                                                                    | Description                                                                                                                                    |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY`                                                 | Path of repository containing archive to show info for, defaults to the configured repository if there is only one                             |
| `--archive ARCHIVE`                                                       | Name of archive to show info for (or "latest")                                                                                                 |
| `--json`                                                                  | Output results as JSON                                                                                                                         |
| `-P PREFIX`,<br>`--prefix PREFIX`                                         | Deprecated. Only show info for archive names starting with this prefix                                                                         |
| `-a PATTERN`,<br>`--match-archives PATTERN`,<br>`--glob-archives PATTERN` | Only show info for archive names matching this pattern                                                                                         |
| `--sort-by KEYS`                                                          | Comma-separated list of sorting keys                                                                                                           |
| `--first N`                                                               | Show info for first N archives after other filters are applied                                                                                 |
| `--last N`                                                                | Show info for last N archives after other filters are applied                                                                                  |
| `--oldest TIMESPAN`                                                       | Show info for archives within a specified time range starting from the timestamp of the oldest archive [Borg 2.x+ only]                        |
| `--newest TIMESPAN`                                                       | Show info for archives within a time range that ends at timestamp of the newest archive and starts a specified time range ago [Borg 2.x+ only] |
| `--older TIMESPAN`                                                        | Show info for archives that are older than the specified time range from the current time [Borg 2.x+ only]                                     |
| `--newer TIMESPAN`                                                        | Show info for archives that are newer than the specified time range from the current time [Borg 2.x+ only]                                     |

### borgmatic break-lock
Break [Borg](borg.md) repository and cache locks left behind by [Borg](borg.md) aborting

| Option                    | Description                                                                                          |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--repository REPOSITORY` | Path of repository to break the lock for, defaults to the configured repository if there is only one |

## Automatic Backups
You can use [Systemd](../../linux/systemd/Systemd.md) to run backups periodically.

Configure these files and place them in `/etc/systemd/system/`

**borgmatic.service**:
```
[Unit]
Description=borgmatic backup
Wants=network-online.target
After=network-online.target
# Prevent borgmatic from running unless the machine is plugged into power. Remove this line if you
# want to allow borgmatic to run anytime.
ConditionACPower=true

[Service]
Type=oneshot

# Security settings for systemd running as root, optional but recommended to improve security. You
# can disable individual settings if they cause problems for your use case. For more details, see
# the systemd manual: https://www.freedesktop.org/software/systemd/man/systemd.exec.html
LockPersonality=true
# Certain borgmatic features like Healthchecks integration need MemoryDenyWriteExecute to be off.
# But you can try setting it to "yes" for improved security if you don't use those features.
MemoryDenyWriteExecute=no
NoNewPrivileges=yes
PrivateDevices=yes
PrivateTmp=yes
ProtectClock=yes
ProtectControlGroups=yes
ProtectHostname=yes
ProtectKernelLogs=yes
ProtectKernelModules=yes
ProtectKernelTunables=yes
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
RestrictNamespaces=yes
RestrictRealtime=yes
RestrictSUIDSGID=yes
SystemCallArchitectures=native
SystemCallFilter=@system-service
SystemCallErrorNumber=EPERM
# To restrict write access further, change "ProtectSystem" to "strict" and
# uncomment "ReadWritePaths", "TemporaryFileSystem", "BindPaths" and
# "BindReadOnlyPaths". Then add any local repository paths to the list of
# "ReadWritePaths". This leaves most of the filesystem read-only to borgmatic.
ProtectSystem=full
# ReadWritePaths=-/mnt/my_backup_drive
# This will mount a tmpfs on top of /root and pass through needed paths
# TemporaryFileSystem=/root:ro
# BindPaths=-/root/.cache/borg -/root/.config/borg -/root/.borgmatic
# BindReadOnlyPaths=-/root/.ssh

# May interfere with running external programs within borgmatic hooks.
CapabilityBoundingSet=CAP_DAC_READ_SEARCH CAP_NET_RAW

# Lower CPU and I/O priority.
Nice=19
CPUSchedulingPolicy=batch
IOSchedulingClass=best-effort
IOSchedulingPriority=7
IOWeight=100

Restart=no
# Prevent rate limiting of borgmatic log events. If you are using an older version of systemd that
# doesn't support this (pre-240 or so), you may have to remove this option.
LogRateLimitIntervalSec=0

# Delay start to prevent backups running during boot. Note that systemd-inhibit requires dbus and
# dbus-user-session to be installed.
ExecStartPre=sleep 1m
ExecStart=systemd-inhibit --who="borgmatic" --what="sleep:shutdown" --why="Prevent interrupting scheduled backup" /root/.local/bin/borgmatic --verbosity -2 --syslog-verbosity 1
```

**borgmatic.timer**:
```
[Unit]
Description=Run borgmatic backup

[Timer]
OnCalendar=daily
Persistent=true
RandomizedDelaySec=3h

[Install]
WantedBy=timers.target
```

Then activate the timer:

```bash
sudo systemctl enable --now borgmatic.timer
```
