2018-09-02 07:45:13 +02:00
|
|
|
---
|
|
|
|
title: borgmatic
|
|
|
|
permalink: borgmatic/index.html
|
2018-09-02 07:38:17 +02:00
|
|
|
---
|
2014-11-27 18:29:31 +01:00
|
|
|
## Overview
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2018-08-30 07:44:12 +02:00
|
|
|
<img src="https://projects.torsion.org/witten/borgmatic/raw/branch/master/static/borgmatic.png" width="150px" style="float: right; padding-left: 1em;">
|
|
|
|
|
2018-08-30 07:57:32 +02:00
|
|
|
borgmatic is a simple Python wrapper script for the
|
2018-09-03 07:06:57 +02:00
|
|
|
[Borg](https://www.borgbackup.org/) backup software that initiates a backup,
|
|
|
|
prunes any old backups according to a retention policy, and validates backups
|
|
|
|
for consistency. The script supports specifying your settings in a declarative
|
|
|
|
configuration file rather than having to put them all on the command-line, and
|
|
|
|
handles common errors.
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2014-11-26 01:01:59 +01:00
|
|
|
Here's an example config file:
|
|
|
|
|
2017-07-05 03:23:59 +02:00
|
|
|
```yaml
|
|
|
|
location:
|
|
|
|
# List of source directories to backup. Globs are expanded.
|
|
|
|
source_directories:
|
|
|
|
- /home
|
|
|
|
- /etc
|
|
|
|
- /var/log/syslog*
|
|
|
|
|
2017-07-23 07:56:46 +02:00
|
|
|
# Paths to local or remote repositories.
|
|
|
|
repositories:
|
|
|
|
- user@backupserver:sourcehostname.borg
|
2017-07-05 03:23:59 +02:00
|
|
|
|
2017-07-10 20:06:28 +02:00
|
|
|
# Any paths matching these patterns are excluded from backups.
|
|
|
|
exclude_patterns:
|
|
|
|
- /home/*/.cache
|
|
|
|
|
2017-07-05 03:23:59 +02:00
|
|
|
retention:
|
|
|
|
# Retention policy for how many backups to keep in each category.
|
|
|
|
keep_daily: 7
|
|
|
|
keep_weekly: 4
|
|
|
|
keep_monthly: 6
|
|
|
|
|
|
|
|
consistency:
|
|
|
|
# List of consistency checks to run: "repository", "archives", or both.
|
|
|
|
checks:
|
|
|
|
- repository
|
|
|
|
- archives
|
2016-01-20 13:11:15 +01:00
|
|
|
```
|
2015-05-11 07:00:31 +02:00
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
borgmatic is hosted at <https://torsion.org/borgmatic> with [source code
|
2017-10-28 06:55:08 +02:00
|
|
|
available](https://projects.torsion.org/witten/borgmatic). It's also mirrored
|
2017-10-28 07:27:28 +02:00
|
|
|
on [GitHub](https://github.com/witten/borgmatic) for convenience.
|
2014-11-19 03:32:16 +01:00
|
|
|
|
2018-09-30 06:38:38 +02:00
|
|
|
<script src="https://asciinema.org/a/203761.js" id="asciicast-203761" async></script>
|
2018-02-20 02:44:20 +01:00
|
|
|
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2017-07-10 20:06:28 +02:00
|
|
|
## Installation
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
To get up and running, follow the [Borg Quick
|
|
|
|
Start](https://borgbackup.readthedocs.org/en/latest/quickstart.html) to create
|
2017-11-04 04:27:21 +01:00
|
|
|
a repository on a local or remote host. Note that if you plan to run borgmatic
|
|
|
|
on a schedule with cron, and you encrypt your Borg repository with a
|
|
|
|
passphrase instead of a key file, you'll either need to set the borgmatic
|
|
|
|
`encryption_passphrase` configuration variable or set the `BORG_PASSPHRASE`
|
2017-11-04 04:28:31 +01:00
|
|
|
environment variable. See the [repository encryption
|
|
|
|
section](https://borgbackup.readthedocs.io/en/latest/quickstart.html#repository-encryption)
|
|
|
|
of the Quick Start for more info.
|
2015-03-15 18:44:18 +01:00
|
|
|
|
2018-01-17 06:03:25 +01:00
|
|
|
Alternatively, the passphrase can be specified programatically by setting
|
|
|
|
either the borgmatic `encryption_passcommand` configuration variable or the
|
|
|
|
`BORG_PASSCOMMAND` environment variable. See the [Borg Security
|
|
|
|
FAQ](http://borgbackup.readthedocs.io/en/stable/faq.html#how-can-i-specify-the-encryption-passphrase-programmatically)
|
|
|
|
for more info.
|
|
|
|
|
2015-03-15 18:44:18 +01:00
|
|
|
If the repository is on a remote host, make sure that your local root user has
|
|
|
|
key-based ssh access to the desired user account on the remote host.
|
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
To install borgmatic, run the following command to download and install it:
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
sudo pip3 install --upgrade borgmatic
|
|
|
|
```
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2017-08-27 01:18:53 +02:00
|
|
|
Note that your pip binary may have a different name than "pip3". Make sure
|
|
|
|
you're using Python 3, as borgmatic does not support Python 2.
|
2017-07-03 02:18:33 +02:00
|
|
|
|
2018-05-20 01:06:54 +02:00
|
|
|
### Other ways to install
|
|
|
|
|
|
|
|
* [A borgmatic Docker image](https://hub.docker.com/r/b3vis/borgmatic/) based
|
|
|
|
on Alpine Linux.
|
|
|
|
* [Another borgmatic Docker image](https://hub.docker.com/r/coaxial/borgmatic/) based
|
|
|
|
on Alpine Linux, updated automatically whenever the Alpine image updates.
|
|
|
|
* [A borgmatic package for
|
|
|
|
Fedora](https://bodhi.fedoraproject.org/updates/?search=borgmatic).
|
|
|
|
* [A borgmatic package for Arch
|
|
|
|
Linux](https://aur.archlinux.org/packages/borgmatic/).
|
2018-05-20 01:16:54 +02:00
|
|
|
* [A borgmatic package for OpenBSD](http://ports.su/sysutils/borgmatic).
|
2018-05-20 01:06:54 +02:00
|
|
|
<br><br>
|
2017-10-26 06:24:24 +02:00
|
|
|
|
2017-07-26 06:18:51 +02:00
|
|
|
## Configuration
|
|
|
|
|
|
|
|
After you install borgmatic, generate a sample configuration file:
|
2017-07-10 20:06:28 +02:00
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
sudo generate-borgmatic-config
|
|
|
|
```
|
2017-07-10 20:06:28 +02:00
|
|
|
|
2018-04-08 21:06:15 +02:00
|
|
|
If that command is not found, then it may be installed in a location that's
|
|
|
|
not in your system `PATH`. Try looking in `/usr/local/bin/`.
|
|
|
|
|
2017-07-10 20:06:28 +02:00
|
|
|
This generates a sample configuration file at /etc/borgmatic/config.yaml (by
|
|
|
|
default). You should edit the file to suit your needs, as the values are just
|
|
|
|
representative. All fields are optional except where indicated, so feel free
|
2018-09-30 00:03:11 +02:00
|
|
|
to ignore anything you don't need.
|
2017-07-10 20:06:28 +02:00
|
|
|
|
2017-07-30 20:16:26 +02:00
|
|
|
You can also have a look at the [full configuration
|
2017-10-28 07:26:33 +02:00
|
|
|
schema](https://projects.torsion.org/witten/borgmatic/src/master/borgmatic/config/schema.yaml)
|
2017-07-30 20:16:26 +02:00
|
|
|
for the authoritative set of all configuration options. This is handy if
|
|
|
|
borgmatic has added new options since you originally created your
|
|
|
|
configuration file.
|
|
|
|
|
2017-07-10 20:06:28 +02:00
|
|
|
|
2017-07-26 06:18:51 +02:00
|
|
|
### Multiple configuration files
|
|
|
|
|
|
|
|
A more advanced usage is to create multiple separate configuration files and
|
2017-07-29 07:02:18 +02:00
|
|
|
place each one in an /etc/borgmatic.d directory. For instance:
|
2017-07-26 06:18:51 +02:00
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
sudo mkdir /etc/borgmatic.d
|
|
|
|
sudo generate-borgmatic-config --destination /etc/borgmatic.d/app1.yaml
|
|
|
|
sudo generate-borgmatic-config --destination /etc/borgmatic.d/app2.yaml
|
|
|
|
```
|
2017-07-26 06:18:51 +02:00
|
|
|
|
|
|
|
With this approach, you can have entirely different backup policies for
|
|
|
|
different applications on your system. For instance, you may want one backup
|
|
|
|
configuration for your database data directory, and a different configuration
|
|
|
|
for your user home directories.
|
|
|
|
|
|
|
|
When you set up multiple configuration files like this, borgmatic will run
|
|
|
|
each one in turn from a single borgmatic invocation. This includes, by
|
|
|
|
default, the traditional /etc/borgmatic/config.yaml as well.
|
|
|
|
|
2017-11-03 06:28:53 +01:00
|
|
|
And if you need even more customizability, you can specify alternate
|
|
|
|
configuration paths on the command-line with borgmatic's `--config` option.
|
|
|
|
See `borgmatic --help` for more information.
|
|
|
|
|
2017-07-26 06:18:51 +02:00
|
|
|
|
2018-07-29 07:22:25 +02:00
|
|
|
### Hooks
|
|
|
|
|
|
|
|
If you find yourself performing prepraration tasks before your backup runs, or
|
|
|
|
cleanup work afterwards, borgmatic hooks may be of interest. They're simply
|
|
|
|
shell commands that borgmatic executes for you at various points, and they're
|
|
|
|
configured in the `hooks` section of your configuration file.
|
|
|
|
|
|
|
|
For instance, you can specify `before_backup` hooks to dump a database to file
|
|
|
|
before backing it up, and specify `after_backup` hooks to delete the temporary
|
|
|
|
file afterwards.
|
|
|
|
|
|
|
|
borgmatic hooks run once per configuration file. `before_backup` hooks run
|
|
|
|
prior to backups of all repositories. `after_backup` hooks run afterwards, but
|
2018-07-29 07:24:24 +02:00
|
|
|
not if an error occurs in a previous hook or in the backups themselves. And
|
2018-07-29 07:22:25 +02:00
|
|
|
borgmatic runs `on_error` hooks if an error occurs.
|
|
|
|
|
|
|
|
An important security note about hooks: borgmatic executes all hook commands
|
|
|
|
with the user permissions of borgmatic itself. So to prevent potential shell
|
|
|
|
injection or privilege escalation, do not forget to set secure permissions
|
2018-08-30 07:57:32 +02:00
|
|
|
(`chmod 0700`) on borgmatic configuration files and scripts invoked by hooks.
|
2018-07-29 07:22:25 +02:00
|
|
|
|
|
|
|
See the sample generated configuration file mentioned above for specifics
|
|
|
|
about hook configuration syntax.
|
|
|
|
|
|
|
|
|
2017-07-10 20:06:28 +02:00
|
|
|
## Upgrading
|
|
|
|
|
|
|
|
In general, all you should need to do to upgrade borgmatic is run the
|
|
|
|
following:
|
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
sudo pip3 install --upgrade borgmatic
|
|
|
|
```
|
2017-07-23 05:52:29 +02:00
|
|
|
|
2017-07-10 20:06:28 +02:00
|
|
|
However, see below about special cases.
|
|
|
|
|
2017-07-23 05:52:29 +02:00
|
|
|
|
2017-07-10 20:06:28 +02:00
|
|
|
### Upgrading from borgmatic 1.0.x
|
|
|
|
|
|
|
|
borgmatic changed its configuration file format in version 1.1.0 from
|
|
|
|
INI-style to YAML. This better supports validation, and has a more natural way
|
|
|
|
to express lists of values. To upgrade your existing configuration, first
|
2017-08-06 08:32:39 +02:00
|
|
|
upgrade to the new version of borgmatic.
|
2015-07-19 03:35:29 +02:00
|
|
|
|
2017-07-23 05:52:29 +02:00
|
|
|
As of version 1.1.0, borgmatic no longer supports Python 2. If you were
|
|
|
|
already running borgmatic with Python 3, then you can simply upgrade borgmatic
|
|
|
|
in-place:
|
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
sudo pip3 install --upgrade borgmatic
|
|
|
|
```
|
2017-07-10 20:06:28 +02:00
|
|
|
|
2017-07-23 05:52:29 +02:00
|
|
|
But if you were running borgmatic with Python 2, uninstall and reinstall instead:
|
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
sudo pip uninstall borgmatic
|
|
|
|
sudo pip3 install borgmatic
|
|
|
|
```
|
2017-07-23 05:52:29 +02:00
|
|
|
|
|
|
|
The pip binary names for different versions of Python can differ, so the above
|
|
|
|
commands may need some tweaking to work on your machine.
|
|
|
|
|
|
|
|
|
|
|
|
Once borgmatic is upgraded, run:
|
2015-07-19 03:35:29 +02:00
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
sudo upgrade-borgmatic-config
|
|
|
|
```
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2017-07-10 20:06:28 +02:00
|
|
|
That will generate a new YAML configuration file at /etc/borgmatic/config.yaml
|
|
|
|
(by default) using the values from both your existing configuration and
|
|
|
|
excludes files. The new version of borgmatic will consume the YAML
|
|
|
|
configuration file instead of the old one.
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2017-07-10 20:06:28 +02:00
|
|
|
|
|
|
|
### Upgrading from atticmatic
|
2016-06-10 20:53:45 +02:00
|
|
|
|
|
|
|
You can ignore this section if you're not an atticmatic user (the former name
|
|
|
|
of borgmatic).
|
|
|
|
|
|
|
|
borgmatic only supports Borg now and no longer supports Attic. So if you're
|
|
|
|
an Attic user, consider switching to Borg. See the [Borg upgrade
|
|
|
|
command](https://borgbackup.readthedocs.io/en/stable/usage.html#borg-upgrade)
|
|
|
|
for more information. Then, follow the instructions above about setting up
|
|
|
|
your borgmatic configuration files.
|
|
|
|
|
|
|
|
If you were already using Borg with atticmatic, then you can easily upgrade
|
|
|
|
from atticmatic to borgmatic. Simply run the following commands:
|
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
sudo pip3 uninstall atticmatic
|
|
|
|
sudo pip3 install borgmatic
|
|
|
|
```
|
2016-06-10 20:53:45 +02:00
|
|
|
|
|
|
|
That's it! borgmatic will continue using your /etc/borgmatic configuration
|
|
|
|
files.
|
|
|
|
|
2017-07-10 20:06:28 +02:00
|
|
|
|
2014-11-27 18:29:31 +01:00
|
|
|
## Usage
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
You can run borgmatic and start a backup simply by invoking it without
|
2014-10-31 06:34:03 +01:00
|
|
|
arguments:
|
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
borgmatic
|
|
|
|
```
|
2015-07-19 03:35:29 +02:00
|
|
|
|
2015-02-14 18:23:40 +01:00
|
|
|
This will also prune any old backups as per the configured retention policy,
|
|
|
|
and check backups for consistency problems due to things like file damage.
|
|
|
|
|
2017-07-29 07:02:18 +02:00
|
|
|
If you'd like to see the available command-line arguments, view the help:
|
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
borgmatic --help
|
|
|
|
```
|
2017-07-29 07:02:18 +02:00
|
|
|
|
2017-08-27 01:13:41 +02:00
|
|
|
Note that borgmatic prunes archives *before* creating an archive, so as to
|
|
|
|
free up space for archiving. This means that when a borgmatic run finishes,
|
|
|
|
there may still be prune-able archives. Not to worry, as they will get cleaned
|
|
|
|
up at the start of the next run.
|
|
|
|
|
2017-07-29 07:02:18 +02:00
|
|
|
### Verbosity
|
|
|
|
|
2014-11-26 01:01:59 +01:00
|
|
|
By default, the backup will proceed silently except in the case of errors. But
|
|
|
|
if you'd like to to get additional information about the progress of the
|
2015-07-18 06:58:50 +02:00
|
|
|
backup as it proceeds, use the verbosity option:
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
borgmatic --verbosity 1
|
|
|
|
```
|
2015-07-18 06:58:50 +02:00
|
|
|
|
|
|
|
Or, for even more progress spew:
|
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
borgmatic --verbosity 2
|
|
|
|
```
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2017-07-29 07:02:18 +02:00
|
|
|
### À la carte
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2017-07-29 07:02:18 +02:00
|
|
|
If you want to run borgmatic with only pruning, creating, or checking enabled,
|
|
|
|
the following optional flags are available:
|
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
borgmatic --prune
|
|
|
|
borgmatic --create
|
|
|
|
borgmatic --check
|
|
|
|
```
|
2017-07-29 07:02:18 +02:00
|
|
|
|
|
|
|
You can run with only one of these flags provided, or you can mix and match
|
|
|
|
any number of them. This supports use cases like running consistency checks
|
|
|
|
from a different cron job with a different frequency, or running pruning with
|
|
|
|
a different verbosity level.
|
2014-11-18 03:35:47 +01:00
|
|
|
|
2018-08-30 07:57:32 +02:00
|
|
|
Additionally, borgmatic provides convenient flags for Borg's
|
|
|
|
[list](https://borgbackup.readthedocs.io/en/stable/usage/list.html) and
|
|
|
|
[info](https://borgbackup.readthedocs.io/en/stable/usage/info.html)
|
|
|
|
functionality:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
borgmatic --list
|
|
|
|
borgmatic --info
|
|
|
|
```
|
|
|
|
|
2018-09-27 17:12:54 +02:00
|
|
|
You can include an optional `--json` flag with `--create`, `--list`, or
|
|
|
|
`--info` to get the output formatted as JSON.
|
2018-08-30 07:57:32 +02:00
|
|
|
|
2014-11-18 03:35:47 +01:00
|
|
|
|
2016-07-04 07:07:53 +02:00
|
|
|
## Autopilot
|
|
|
|
|
|
|
|
If you want to run borgmatic automatically, say once a day, the you can
|
2016-07-04 18:19:34 +02:00
|
|
|
configure a job runner to invoke it periodically.
|
|
|
|
|
|
|
|
### cron
|
|
|
|
|
|
|
|
If you're using cron, download the [sample cron
|
2018-07-29 05:29:55 +02:00
|
|
|
file](https://projects.torsion.org/witten/borgmatic/src/master/sample/cron/borgmatic).
|
2016-07-04 07:07:53 +02:00
|
|
|
Then, from the directory where you downloaded it:
|
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
sudo mv borgmatic /etc/cron.d/borgmatic
|
|
|
|
sudo chmod +x /etc/cron.d/borgmatic
|
|
|
|
```
|
2016-07-04 18:19:34 +02:00
|
|
|
|
|
|
|
You can modify the cron file if you'd like to run borgmatic more or less frequently.
|
|
|
|
|
|
|
|
### systemd
|
|
|
|
|
|
|
|
If you're using systemd instead of cron to run jobs, download the [sample
|
|
|
|
systemd service
|
2017-10-28 07:26:33 +02:00
|
|
|
file](https://projects.torsion.org/witten/borgmatic/src/master/sample/systemd/borgmatic.service)
|
2016-07-04 18:19:34 +02:00
|
|
|
and the [sample systemd timer
|
2017-10-28 07:26:33 +02:00
|
|
|
file](https://projects.torsion.org/witten/borgmatic/src/master/sample/systemd/borgmatic.timer).
|
2016-07-04 18:19:34 +02:00
|
|
|
Then, from the directory where you downloaded them:
|
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
|
|
|
sudo mv borgmatic.service borgmatic.timer /etc/systemd/system/
|
|
|
|
sudo systemctl enable borgmatic.timer
|
|
|
|
sudo systemctl start borgmatic.timer
|
|
|
|
```
|
2016-07-04 18:19:34 +02:00
|
|
|
|
|
|
|
Feel free to modify the timer file based on how frequently you'd like
|
|
|
|
borgmatic to run.
|
2016-07-04 07:07:53 +02:00
|
|
|
|
|
|
|
|
2018-06-17 23:55:57 +02:00
|
|
|
## Support and contributing
|
2014-11-18 06:57:44 +01:00
|
|
|
|
2018-06-17 23:55:57 +02:00
|
|
|
### Issues
|
|
|
|
|
|
|
|
You've got issues? Or an idea for a feature enhancement? We've got an [issue
|
|
|
|
tracker](https://projects.torsion.org/witten/borgmatic/issues). In order to
|
|
|
|
create a new issue or comment on an issue, you'll need to [login
|
|
|
|
first](https://projects.torsion.org/user/login). Note that you can login with
|
|
|
|
an existing GitHub account if you prefer.
|
|
|
|
|
|
|
|
Other questions or comments? Contact <mailto:witten@torsion.org>.
|
|
|
|
|
|
|
|
|
|
|
|
### Contributing
|
|
|
|
|
|
|
|
If you'd like to contribute to borgmatic development, please feel free to
|
|
|
|
submit a [Pull Request](https://projects.torsion.org/witten/borgmatic/pulls)
|
|
|
|
or open an [issue](https://projects.torsion.org/witten/borgmatic/issues) first
|
|
|
|
to discuss your idea. We also accept Pull Requests on GitHub, if that's more
|
|
|
|
your thing. In general, contributions are very welcome. We don't bite!
|
|
|
|
|
|
|
|
|
2018-07-29 00:02:17 +02:00
|
|
|
### Code style
|
|
|
|
|
|
|
|
Start with [PEP 8](https://www.python.org/dev/peps/pep-0008/). But then, apply
|
2018-07-29 07:22:25 +02:00
|
|
|
the following deviations from it:
|
2018-07-29 00:02:17 +02:00
|
|
|
|
|
|
|
* For strings, prefer single quotes over double quotes.
|
|
|
|
* Limit all lines to a maximum of 100 characters.
|
|
|
|
* Use trailing commas within multiline values or argument lists.
|
2018-07-29 00:21:19 +02:00
|
|
|
* For multiline constructs, put opening and closing delimeters on lines
|
|
|
|
separate from their contents.
|
|
|
|
* Within multiline constructs, use standard four-space indentation. Don't align
|
|
|
|
indentation with an opening delimeter.
|
2018-07-29 00:02:17 +02:00
|
|
|
|
2018-09-30 07:45:00 +02:00
|
|
|
borgmatic code uses the [Black](https://github.com/ambv/black) code formatter,
|
|
|
|
so some additional code style requirements will be enforced as well. See the
|
|
|
|
Black documentation for more information.
|
|
|
|
|
2018-07-29 00:02:17 +02:00
|
|
|
|
2018-06-17 23:55:57 +02:00
|
|
|
### Development
|
|
|
|
|
|
|
|
To get set up to hack on borgmatic, first clone master via HTTPS or SSH:
|
|
|
|
|
2018-08-30 08:01:11 +02:00
|
|
|
```bash
|
2018-06-17 23:55:57 +02:00
|
|
|
git clone https://projects.torsion.org/witten/borgmatic.git
|
|
|
|
```
|
|
|
|
|
|
|
|
Or:
|
2014-11-18 06:57:44 +01:00
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
2018-06-17 23:55:57 +02:00
|
|
|
git clone ssh://git@projects.torsion.org:3022/witten/borgmatic.git
|
2017-10-28 19:45:27 +02:00
|
|
|
```
|
2014-11-18 06:57:44 +01:00
|
|
|
|
2018-06-17 23:55:57 +02:00
|
|
|
Then, install borgmatic
|
2018-07-29 05:27:18 +02:00
|
|
|
"[editable](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs)"
|
2018-06-17 23:55:57 +02:00
|
|
|
so that you can easily run borgmatic commands while you're hacking on them to
|
|
|
|
make sure your changes work.
|
|
|
|
|
|
|
|
```bash
|
|
|
|
cd borgmatic/
|
|
|
|
pip3 install --editable --user .
|
|
|
|
```
|
|
|
|
|
|
|
|
Note that this will typically install the borgmatic commands into
|
|
|
|
`~/.local/bin`, which may or may not be on your PATH. There are other ways to
|
|
|
|
install borgmatic editable as well, for instance into the system Python
|
|
|
|
install (so without `--user`, as root), or even into a
|
|
|
|
[virtualenv](https://virtualenv.pypa.io/en/stable/). How or where you install
|
|
|
|
borgmatic is up to you, but generally an editable install makes development
|
|
|
|
and testing easier.
|
|
|
|
|
|
|
|
|
|
|
|
### Running tests
|
|
|
|
|
|
|
|
Assuming you've cloned the borgmatic source code as described above, and
|
|
|
|
you're in the `borgmatic/` working copy, install tox, which is used for
|
|
|
|
setting up testing environments:
|
2014-11-18 06:57:44 +01:00
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```bash
|
2018-04-10 05:34:59 +02:00
|
|
|
sudo pip3 install tox
|
|
|
|
```
|
|
|
|
|
|
|
|
Finally, to actually run tests, run:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
cd borgmatic
|
2017-10-28 19:45:27 +02:00
|
|
|
tox
|
|
|
|
```
|
2014-11-18 06:57:44 +01:00
|
|
|
|
2018-09-30 07:45:00 +02:00
|
|
|
Note that while running borgmatic itself only requires Python 3+, running
|
|
|
|
borgmatic's tests require Python 3.6+.
|
|
|
|
|
|
|
|
If when running tests, you get an error from the
|
|
|
|
[Black](https://github.com/ambv/black) code formatter about files that would
|
|
|
|
be reformatted, you can ask Black to format them for you via the following:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
tox -e black
|
|
|
|
```
|
|
|
|
|
2014-11-18 06:57:44 +01:00
|
|
|
|
2015-02-28 20:03:22 +01:00
|
|
|
## Troubleshooting
|
|
|
|
|
|
|
|
### Broken pipe with remote repository
|
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
When running borgmatic on a large remote repository, you may receive errors
|
|
|
|
like the following, particularly while "borg check" is validating backups for
|
2015-02-28 20:03:22 +01:00
|
|
|
consistency:
|
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```text
|
2015-02-28 20:03:22 +01:00
|
|
|
Write failed: Broken pipe
|
2016-06-10 20:21:53 +02:00
|
|
|
borg: Error: Connection closed by remote host
|
2017-10-28 19:45:27 +02:00
|
|
|
```
|
2015-02-28 20:03:22 +01:00
|
|
|
|
|
|
|
This error can be caused by an ssh timeout, which you can rectify by adding
|
|
|
|
the following to the ~/.ssh/config file on the client:
|
|
|
|
|
2017-10-28 19:45:27 +02:00
|
|
|
```text
|
2015-02-28 20:03:22 +01:00
|
|
|
Host *
|
|
|
|
ServerAliveInterval 120
|
2017-10-28 19:45:27 +02:00
|
|
|
```
|
2015-02-28 20:03:22 +01:00
|
|
|
|
|
|
|
This should make the client keep the connection alive while validating
|
|
|
|
backups.
|
|
|
|
|
|
|
|
|
2017-07-23 06:07:09 +02:00
|
|
|
### libyaml compilation errors
|
|
|
|
|
|
|
|
borgmatic depends on a Python YAML library (ruamel.yaml) that will optionally
|
|
|
|
use a C YAML library (libyaml) if present. But if it's not installed, then
|
|
|
|
when installing or upgrading borgmatic, you may see errors about compiling the
|
|
|
|
YAML library. If so, not to worry. borgmatic should install and function
|
|
|
|
correctly even without the C YAML library. And borgmatic won't be any faster
|
|
|
|
with the C library present, so you don't need to go out of your way to install
|
|
|
|
it.
|