-
How-to guides
- π₯ 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
- π₯ Customize warnings/errors
- π¦ 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
- verbosity
borg action
New in version 1.5.15 The way
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
variable named 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 repo-list --short
(No borgmatic repo-list
action? Try rlist
or list
instead or upgrade
borgmatic!)
This runs Borg's repo-list
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 --repository
argument
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
The ::
is a Borg placeholder that means: Substitute the repository passed in
by environment variable here.
Prior to version 1.8.0borgmatic
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 $ARCHIVE
string instead of trying to resolve it from borgmatic's shell where it's not
yet set.
Or if you don't need borgmatic to resolve an archive name like latest
, you
can do:
borgmatic borg list ::your-actual-archive-name
Prior to version 1.8.0borgmatic 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
With Borg version 2.x Either of these will list an archive:
borgmatic borg --archive latest list '$ARCHIVE'
borgmatic borg list your-actual-archive-name
Limitations
borgmatic's borg
action is not without limitations:
- The Borg command you want to run (
create
,list
, etc.) must come first after theborg
action (and any borgmatic-specific arguments). If you have other Borg options to specify, provide them after. For instance,borgmatic borg list --progress ...
will work, butborgmatic borg --progress list ...
will not. - Do not specify any global borgmatic arguments to the right of the
borg
action. (They will be passed to Borg instead of borgmatic.) If you have global borgmatic arguments, specify them before theborg
action. - Unlike other borgmatic actions, you cannot combine the
borg
action with other borgmatic actions. This is to prevent ambiguity in commands likeborgmatic borg list
, in whichlist
is 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
borg
action will not disable certain borgmatic logs to avoid interfering with JSON output. - The
borg
action bypasses most of borgmatic's machinery, so for instance monitoring hooks will not get triggered when runningborgmatic borg create
. - Prior to version 1.8.0
borgmatic implicitly injected the repository/archive arguments on the Borg
command-line for you (based on your borgmatic configuration or the
borgmatic borg --repository
/--archive
arguments)βwhich meant you couldn't specify the repository/archive directly in the Borg command. Also, in these older versions of borgmatic, theborg
action didn't work for any Borg commands likeborg serve
that do not accept a repository/archive name. - Prior to version 1.7.13 Unlike
other borgmatic actions, the
borg
action captured (and logged) all output, so interactive prompts and flags like--progress
dit not work as expected. In new versions, borgmatic runs theborg
action without capturing output, so interactive prompts work.
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!