🗃️ Repositories

Borg repositories are where your backups get stored. You can define them in borgmatic's configuration via the repositories option, something like:

repositories:
    - path: /path/to/first.borg
      label: first
    - path: /path/to/second.borg
      label: second

Each repository has a path and an optional label. The Borg repository URLs documentation has examples of valid repositories paths, but see below for some borgmatic-specific examples.

The label shows up in logged messages about the repository and also serves as a way to refer to the repository via the --repository flag on the command-line for supported actions.

When you run borgmatic's create action, it invokes Borg once for each configured repository in sequence. (So, not in parallel.) That means—in each repository—borgmatic creates a single new backup archive containing all of your source directories.

Repository-specific configuration

New in version 2.1.10 If you want certain borgmatic configuration options to apply only to particular repositories (and you don't want to mess with separate configuration files), you can specify many top-level configuration options directly under particular repositories. For example:

repositories:
    - path: /path/to/repo1.borg
      local_path: borg1
      remote_path: borg1
    - path: /path/to/repo2.borg
      local_path: borg2
      remote_path: borg2

This example demonstrates how you can specify options like local_path and remote_path to be repository specific, even though they are typically top-level configuration options that apply for all repositories.

Under the hood, borgmatic merges these values into the top-level configuration when determining the configuration to use for a particular repository—overwriting any top-level configuration options that may already exist (but just for that repository). This is performed as a shallow merge, so use includes and multiple configuration files if you need deep merging.

Note that this feature doesn't make sense for every configuration option. For instance, borgmatic consumes options like verbosity before any per-repository logic, so in that case per-repository verbosity values get silently ignored.

SSH

Backing up to a remote server via SSH looks like:

repositories:
    - path: ssh://user@host:port/./absolute/path/to/repo

Or relative to the remote user's home directory:

repositories:
    - path: ssh://user@host:port/~/relative/path/to/repo

This assumes that you've already configured SSH access (e.g. public keys, known hosts, authorized hosts, etc.) outside of borgmatic and that Borg is installed on the server.

With Borg version 2.xThe SSH syntax is a little different:

repositories:
    - path: ssh://user@host:port//absolute/path/to/repo

Or relative to the remote user's home directory:

repositories:
    - path: ssh://user@host:port/relative/path/to/repo

Also see the ssh_command configuration option for overriding the path to the SSH binary or passing it custom flags. For example:

ssh_command: ssh -i /path/to/private/key

SFTP

SFTP repositories work just like SSH repositories, but with sftp:// substituted for ssh://.

Rclone

New in Borg version 2.x If you're using Borg 2, you can backup to repositories via Rclone, which supports a large number of cloud providers. This means that Borg, via Rclone, backs up directly to a cloud provider without having to create an intermediate repository.

The borgmatic configuration for Rclone looks like:

repositories:
    - path: rclone:remote:path

Note the lack of "//" after rclone:.

This configuration assumes that you've already configured a corresponding Rclone remote.

S3 / B2

New in Borg version 2.x Borg 2 supports storing repositories directly on Amazon S3, Backblaze B2, or an S3-alike service, even without the use of Rclone or an intermediate repository. The configuration for that might look like one of the following:

repositories:
    - path: s3:access_key_id:access_key_secret@/bucket/path 
    - path: b2:access_key_id:access_key_secret@schema://hostname:port/bucket/path 

Note the lack of "//" after s3: or b2:.

When selecting your cloud hosting provider, be aware that Amazon in particular has financially supported the Trump regime and sold tech services to Israel used directly in their genocide in Gaza. Additionally, U.S. Immigration and Customs Enforcement (ICE) is powered by Amazon.

Related documentation

• How to make backups redundant
• How to provide your passwords