- Set up backups
- Make per-application backups
- 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 or server
- Run arbitrary Borg commands
- Upgrade borgmatic
- 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 Borg commands with borgmatic takes advantage of the following, all based on your borgmatic configuration files or command-line arguments:
- configured repositories (automatically runs your Borg command once for each one)
- local and remote Borg binary paths
- SSH settings and Borg environment variables
- lock wait settings
borg action ¶
The way you run Borg with borgmatic is via the
borg action. Here's a simple
borgmatic borg break-lock
borg action in borgmatic? Time to upgrade!)
This runs Borg's
break-lock command once on each configured borgmatic
repository. Notice how the repository isn't present in the specified Borg
options, as that part is provided by borgmatic.
You can also specify Borg options for relevant commands:
borgmatic borg list --progress
This runs Borg's
list command once on each configured borgmatic
repository. However, the native
borgmatic list action should be preferred
for most use.
What if you only want to run Borg on a single configured borgmatic repository when you've got several configured? Not a problem.
borgmatic borg --repository repo.borg break-lock
And what about a single archive?
borgmatic borg --archive your-archive-name list
borg action is not without limitations:
- The Borg command you want to run (
list, etc.) must come first after the
borgaction. If you have any other Borg options to specify, provide them after. For instance,
borgmatic borg list --progresswill work, but
borgmatic borg --progress listwill not.
- borgmatic supplies the repository/archive name to Borg for you (based on
your borgmatic configuration or the
borgmatic borg --repository/
--archivearguments), so do not specify the repository/archive otherwise.
borgaction will not currently work for any Borg commands like
borg servethat do not accept a repository/archive name.
- 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.
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!