- 📥 Set up backups
- 🔀 Make per-application backups
- 🔒 Provide your passwords
- ☁️ Make backups redundant
- 📏 Deal with very large backups
- 🔎 Inspect your backups
- 🚨 Monitor your backups
- 📤 Extract a backup
- 🗄️ Backup your databases
- 🧹 Add preparation and cleanup steps
- 💾 Backup to a removable drive/server
- 🔧 Run arbitrary Borg commands
- 📦 Upgrade borgmatic/Borg
- 🏗️ Develop on borgmatic
- Reference guides
Running Borg with borgmatic
Borg has several commands and options that borgmatic does not currently support. Sometimes though, as a borgmatic user, you may find yourself wanting to take advantage of these off-the-beaten-path Borg features. You could of course drop down to running Borg directly. But then you'd give up all the niceties of your borgmatic configuration. You could file a borgmatic ticket or even a pull request to add the feature. But what if you need it now?
That's where borgmatic's support for running "arbitrary" Borg commands comes in. Running these Borg commands with borgmatic can take advantage of the following, all based on your borgmatic configuration files or command-line arguments:
- configured repositories, running your Borg command once for each one
- local and remote Borg binary paths
- SSH settings and Borg environment variables
- lock wait settings
you run Borg with borgmatic is via the
borg action. Here's a simple example:
borgmatic borg break-lock
This runs Borg's
break-lock command once with each configured borgmatic
repository, passing the repository path in as a Borg-supported environment
BORG_REPO. (The native
borgmatic break-lock action should
be preferred though for most uses.)
You can also specify Borg options for relevant commands. For instance:
borgmatic borg rlist --short
This runs Borg's
rlist command once on each configured borgmatic repository.
What if you only want to run Borg on a single configured borgmatic repository
when you've got several configured? Not a problem. The
lets you specify the repository to use, either by its path or its label:
borgmatic borg --repository repo.borg break-lock
And if you need to specify where the repository goes in the command because there are positional arguments after it:
borgmatic borg debug dump-manifest :: root
:: is a Borg placeholder that means: Substitute the repository passed in
by environment variable here.
attempted to inject the repository name directly into your Borg arguments in
the right place (which didn't always work). So your command-line in these
older versions didn't support the
Specifying an archive
For borg commands that expect an archive name, you have a few approaches. Here's one:
borgmatic borg --archive latest list '::$ARCHIVE'
The single quotes are necessary in order to pass in a literal
string instead of trying to resolve it from borgmatic's shell where it's not
Or if you don't need borgmatic to resolve an archive name like
can just do:
borgmatic borg list ::your-actual-archive-name
borgmatic provided the archive name implicitly along with the repository, attempting to inject it into your Borg arguments in the right place (which didn't always work). So your command-line in these older versions of borgmatic looked more like:
borgmatic borg --archive latest list
Either of these will list an archive:
borgmatic borg --archive latest list '$ARCHIVE'
borgmatic borg list your-actual-archive-name
borg action is not without limitations:
- The Borg command you want to run (
list, etc.) must come first after the
borgaction (and any borgmatic-specific arguments). If you have other Borg options to specify, provide them after. For instance,
borgmatic borg list --progress ...will work, but
borgmatic borg --progress list ...will not.
- Do not specify any global borgmatic arguments to the right of the
borgaction. (They will be passed to Borg instead of borgmatic.) If you have global borgmatic arguments, specify them before the
- Unlike other borgmatic actions, you cannot combine the
borgaction with other borgmatic actions. This is to prevent ambiguity in commands like
borgmatic borg list, in which
listis both a valid Borg command and a borgmatic action. In this case, only the Borg command is run.
- Unlike normal borgmatic actions that support JSON, the
borgaction will not disable certain borgmatic logs to avoid interfering with JSON output.
borgmatic borg --repository/
--archivearguments)—which meant you couldn't specify the repository/archive directly in the Borg command. Also, in these older versions of borgmatic, the
borgaction didn't work for any Borg commands like
borg servethat do not accept a repository/archive name.
borgmatic implicitly injected the repository/archive arguments on the Borg
command-line for you (based on your borgmatic configuration or the
borgaction captured (and logged) all output, so interactive prompts and flags like
--progressdit not work as expected. In new versions, borgmatic runs the
borgaction without capturing output, so interactive prompts work.
other borgmatic actions, the
In general, this
borgmatic borg feature should be considered an escape
valve—a feature of second resort. In the long run, it's preferable to wrap
Borg commands with borgmatic actions that can support them fully.
Improve this documentation
Have an idea on how to make this documentation even better? Use our issue tracker to send your feedback!