forked from borgmatic-collective/borgmatic
95 lines
3.6 KiB
Markdown
95 lines
3.6 KiB
Markdown
---
|
|
title: How to run arbitrary Borg commands
|
|
eleventyNavigation:
|
|
key: Run arbitrary Borg commands
|
|
parent: How-to guides
|
|
order: 10
|
|
---
|
|
## 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](https://torsion.org/borgmatic/#issues) or even a [pull
|
|
request](https://torsion.org/borgmatic/#contributing) 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
|
|
* verbosity
|
|
|
|
|
|
### borg action
|
|
|
|
The way you run Borg with borgmatic is via the `borg` action. Here's a simple
|
|
example:
|
|
|
|
```bash
|
|
borgmatic borg break-lock
|
|
```
|
|
|
|
(No `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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
borgmatic borg --repository repo.borg break-lock
|
|
```
|
|
|
|
And what about a single archive?
|
|
|
|
```bash
|
|
borgmatic borg --archive your-archive-name list
|
|
```
|
|
|
|
### Limitations
|
|
|
|
borgmatic's `borg` action is not without limitations:
|
|
|
|
* The Borg command you want to run (`create`, `list`, etc.) *must* come first
|
|
after the `borg` action. If you have any other Borg options to specify,
|
|
provide them after. For instance, `borgmatic borg list --progress` will work,
|
|
but `borgmatic borg --progress list` will not.
|
|
* borgmatic supplies the repository/archive name to Borg for you (based on
|
|
your borgmatic configuration or the `borgmatic borg --repository`/`--archive`
|
|
arguments), so do not specify the repository/archive otherwise.
|
|
* The `borg` action will not currently work for any Borg commands like `borg
|
|
serve` that do not accept a repository/archive name.
|
|
* 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* the `borg` action.
|
|
* Unlike other borgmatic actions, you cannot combine the `borg` action with
|
|
other borgmatic actions. This is to prevent ambiguity in commands like
|
|
`borgmatic borg list`, in which `list` 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.
|
|
|
|
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.
|