13 changed files with 436 additions and 130 deletions
@ -0,0 +1,45 @@ |
|||
import logging |
|||
|
|||
from borgmatic.borg.flags import make_flags |
|||
from borgmatic.execute import execute_command |
|||
|
|||
logger = logging.getLogger(__name__) |
|||
|
|||
|
|||
REPOSITORYLESS_BORG_COMMANDS = {'serve', None} |
|||
|
|||
|
|||
def run_arbitrary_borg( |
|||
repository, storage_config, options, archive=None, local_path='borg', remote_path=None |
|||
): |
|||
''' |
|||
Given a local or remote repository path, a storage config dict, a sequence of arbitrary |
|||
command-line Borg options, and an optional archive name, run an arbitrary Borg command on the |
|||
given repository/archive. |
|||
''' |
|||
lock_wait = storage_config.get('lock_wait', None) |
|||
|
|||
try: |
|||
options = options[1:] if options[0] == '--' else options |
|||
borg_command = options[0] |
|||
command_options = tuple(options[1:]) |
|||
except IndexError: |
|||
borg_command = None |
|||
command_options = () |
|||
|
|||
repository_archive = '::'.join((repository, archive)) if repository and archive else repository |
|||
|
|||
full_command = ( |
|||
(local_path,) |
|||
+ ((borg_command,) if borg_command else ()) |
|||
+ ((repository_archive,) if borg_command and repository_archive else ()) |
|||
+ command_options |
|||
+ (('--info',) if logger.getEffectiveLevel() == logging.INFO else ()) |
|||
+ (('--debug', '--show-rc') if logger.isEnabledFor(logging.DEBUG) else ()) |
|||
+ make_flags('remote-path', remote_path) |
|||
+ make_flags('lock-wait', lock_wait) |
|||
) |
|||
|
|||
return execute_command( |
|||
full_command, output_log_level=logging.WARNING, borg_local_path=local_path, |
|||
) |
|||
@ -0,0 +1,94 @@ |
|||
--- |
|||
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. |
|||
@ -0,0 +1,123 @@ |
|||
import logging |
|||
|
|||
from flexmock import flexmock |
|||
|
|||
from borgmatic.borg import borg as module |
|||
|
|||
from ..test_verbosity import insert_logging_mock |
|||
|
|||
|
|||
def test_run_arbitrary_borg_calls_borg_with_parameters(): |
|||
flexmock(module).should_receive('execute_command').with_args( |
|||
('borg', 'break-lock', 'repo'), output_log_level=logging.WARNING, borg_local_path='borg' |
|||
) |
|||
|
|||
module.run_arbitrary_borg( |
|||
repository='repo', storage_config={}, options=['break-lock'], |
|||
) |
|||
|
|||
|
|||
def test_run_arbitrary_borg_with_log_info_calls_borg_with_info_parameter(): |
|||
flexmock(module).should_receive('execute_command').with_args( |
|||
('borg', 'break-lock', 'repo', '--info'), |
|||
output_log_level=logging.WARNING, |
|||
borg_local_path='borg', |
|||
) |
|||
insert_logging_mock(logging.INFO) |
|||
|
|||
module.run_arbitrary_borg( |
|||
repository='repo', storage_config={}, options=['break-lock'], |
|||
) |
|||
|
|||
|
|||
def test_run_arbitrary_borg_with_log_debug_calls_borg_with_debug_parameter(): |
|||
flexmock(module).should_receive('execute_command').with_args( |
|||
('borg', 'break-lock', 'repo', '--debug', '--show-rc'), |
|||
output_log_level=logging.WARNING, |
|||
borg_local_path='borg', |
|||
) |
|||
insert_logging_mock(logging.DEBUG) |
|||
|
|||
module.run_arbitrary_borg( |
|||
repository='repo', storage_config={}, options=['break-lock'], |
|||
) |
|||
|
|||
|
|||
def test_run_arbitrary_borg_with_lock_wait_calls_borg_with_lock_wait_parameters(): |
|||
storage_config = {'lock_wait': 5} |
|||
flexmock(module).should_receive('execute_command').with_args( |
|||
('borg', 'break-lock', 'repo', '--lock-wait', '5'), |
|||
output_log_level=logging.WARNING, |
|||
borg_local_path='borg', |
|||
) |
|||
|
|||
module.run_arbitrary_borg( |
|||
repository='repo', storage_config=storage_config, options=['break-lock'], |
|||
) |
|||
|
|||
|
|||
def test_run_arbitrary_borg_with_archive_calls_borg_with_archive_parameter(): |
|||
storage_config = {} |
|||
flexmock(module).should_receive('execute_command').with_args( |
|||
('borg', 'break-lock', 'repo::archive'), |
|||
output_log_level=logging.WARNING, |
|||
borg_local_path='borg', |
|||
) |
|||
|
|||
module.run_arbitrary_borg( |
|||
repository='repo', storage_config=storage_config, options=['break-lock'], archive='archive', |
|||
) |
|||
|
|||
|
|||
def test_run_arbitrary_borg_with_local_path_calls_borg_via_local_path(): |
|||
flexmock(module).should_receive('execute_command').with_args( |
|||
('borg1', 'break-lock', 'repo'), output_log_level=logging.WARNING, borg_local_path='borg1' |
|||
) |
|||
|
|||
module.run_arbitrary_borg( |
|||
repository='repo', storage_config={}, options=['break-lock'], local_path='borg1', |
|||
) |
|||
|
|||
|
|||
def test_run_arbitrary_borg_with_remote_path_calls_borg_with_remote_path_parameters(): |
|||
flexmock(module).should_receive('execute_command').with_args( |
|||
('borg', 'break-lock', 'repo', '--remote-path', 'borg1'), |
|||
output_log_level=logging.WARNING, |
|||
borg_local_path='borg', |
|||
) |
|||
|
|||
module.run_arbitrary_borg( |
|||
repository='repo', storage_config={}, options=['break-lock'], remote_path='borg1', |
|||
) |
|||
|
|||
|
|||
def test_run_arbitrary_borg_passes_borg_specific_parameters_to_borg(): |
|||
flexmock(module).should_receive('execute_command').with_args( |
|||
('borg', 'list', 'repo', '--progress'), |
|||
output_log_level=logging.WARNING, |
|||
borg_local_path='borg', |
|||
) |
|||
|
|||
module.run_arbitrary_borg( |
|||
repository='repo', storage_config={}, options=['list', '--progress'], |
|||
) |
|||
|
|||
|
|||
def test_run_arbitrary_borg_omits_dash_dash_in_parameters_passed_to_borg(): |
|||
flexmock(module).should_receive('execute_command').with_args( |
|||
('borg', 'break-lock', 'repo'), output_log_level=logging.WARNING, borg_local_path='borg', |
|||
) |
|||
|
|||
module.run_arbitrary_borg( |
|||
repository='repo', storage_config={}, options=['--', 'break-lock'], |
|||
) |
|||
|
|||
|
|||
def test_run_arbitrary_borg_without_borg_specific_parameters_does_not_raise(): |
|||
flexmock(module).should_receive('execute_command').with_args( |
|||
('borg',), output_log_level=logging.WARNING, borg_local_path='borg', |
|||
) |
|||
|
|||
module.run_arbitrary_borg( |
|||
repository='repo', storage_config={}, options=[], |
|||
) |
|||
Loading…
Reference in new issue