2016-06-10 20:21:53 +02:00
|
|
|
title: Borgmatic
|
2014-12-02 04:49:25 +01:00
|
|
|
|
2014-11-27 18:29:31 +01:00
|
|
|
## Overview
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
borgmatic (formerly atticmatic) is a simple Python wrapper script for the
|
2016-04-10 19:23:32 +02:00
|
|
|
[Borg](https://borgbackup.readthedocs.org/en/stable/) backup software that
|
2015-07-19 03:35:29 +02:00
|
|
|
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:
|
|
|
|
|
2016-01-20 13:11:15 +01:00
|
|
|
```INI
|
|
|
|
[location]
|
|
|
|
# Space-separated list of source directories to backup.
|
2016-02-13 21:05:34 +01:00
|
|
|
# Globs are expanded.
|
|
|
|
source_directories: /home /etc /var/log/syslog*
|
2016-01-20 13:11:15 +01:00
|
|
|
|
|
|
|
# Path to local or remote backup repository.
|
2016-06-10 20:21:53 +02:00
|
|
|
repository: user@backupserver:sourcehostname.borg
|
2016-01-20 13:11:15 +01:00
|
|
|
|
|
|
|
[retention]
|
|
|
|
# Retention policy for how many backups to keep in each category.
|
|
|
|
keep_daily: 7
|
|
|
|
keep_weekly: 4
|
|
|
|
keep_monthly: 6
|
|
|
|
|
|
|
|
[consistency]
|
|
|
|
# Consistency checks to run, or "disabled" to prevent checks.
|
|
|
|
checks: repository archives
|
|
|
|
```
|
2015-05-11 07:00:31 +02:00
|
|
|
|
2014-11-26 01:01:59 +01:00
|
|
|
Additionally, exclude patterns can be specified in a separate excludes config
|
|
|
|
file, one pattern per line.
|
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
borgmatic is hosted at <https://torsion.org/borgmatic> with [source code
|
|
|
|
available](https://torsion.org/hg/borgmatic). It's also mirrored on
|
|
|
|
[GitHub](https://github.com/witten/borgmatic) and
|
|
|
|
[BitBucket](https://bitbucket.org/dhelfman/borgmatic) for convenience.
|
2014-11-19 03:32:16 +01:00
|
|
|
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2014-11-27 18:29:31 +01:00
|
|
|
## Setup
|
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
|
|
|
|
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 need to set the borgmatic
|
2015-09-03 07:48:07 +02:00
|
|
|
`encryption_passphrase` configuration variable. See the repository encryption
|
|
|
|
section of the Quick Start 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
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
sudo pip install --upgrade borgmatic
|
2014-10-31 06:34:03 +01:00
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
Then, copy the following configuration files:
|
2015-07-19 03:35:29 +02:00
|
|
|
|
2015-07-19 03:44:11 +02:00
|
|
|
sudo cp sample/borgmatic.cron /etc/cron.d/borgmatic
|
2015-07-19 03:35:29 +02:00
|
|
|
sudo mkdir /etc/borgmatic/
|
|
|
|
sudo cp sample/config sample/excludes /etc/borgmatic/
|
|
|
|
|
|
|
|
Lastly, modify the /etc files with your desired configuration.
|
2014-10-31 06:34:03 +01:00
|
|
|
|
|
|
|
|
2016-06-10 20:53:45 +02:00
|
|
|
## Upgrading from atticmatic
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
sudo pip uninstall atticmatic
|
|
|
|
sudo pip install borgmatic
|
|
|
|
|
|
|
|
That's it! borgmatic will continue using your /etc/borgmatic configuration
|
|
|
|
files.
|
|
|
|
|
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:
|
|
|
|
|
2015-07-19 03:35:29 +02:00
|
|
|
borgmatic
|
|
|
|
|
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.
|
|
|
|
|
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
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
borgmatic --verbosity 1
|
2015-07-18 06:58:50 +02:00
|
|
|
|
|
|
|
Or, for even more progress spew:
|
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
borgmatic --verbosity 2
|
2014-10-31 06:34:03 +01:00
|
|
|
|
|
|
|
If you'd like to see the available command-line arguments, view the help:
|
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
borgmatic --help
|
2014-11-18 03:35:47 +01:00
|
|
|
|
|
|
|
|
2014-11-27 18:29:31 +01:00
|
|
|
## Running tests
|
2014-11-18 06:57:44 +01:00
|
|
|
|
2015-03-15 18:14:30 +01:00
|
|
|
First install tox, which is used for setting up testing environments:
|
2014-11-18 06:57:44 +01:00
|
|
|
|
2015-03-15 18:14:30 +01:00
|
|
|
pip install tox
|
2014-11-18 06:57:44 +01:00
|
|
|
|
2015-03-15 18:14:30 +01:00
|
|
|
Then, to actually run tests, run:
|
2014-11-18 06:57:44 +01:00
|
|
|
|
2015-03-15 18:14:30 +01:00
|
|
|
tox
|
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:
|
|
|
|
|
|
|
|
Write failed: Broken pipe
|
2016-06-10 20:21:53 +02:00
|
|
|
borg: Error: Connection closed by remote host
|
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:
|
|
|
|
|
|
|
|
Host *
|
|
|
|
ServerAliveInterval 120
|
|
|
|
|
|
|
|
This should make the client keep the connection alive while validating
|
|
|
|
backups.
|
|
|
|
|
|
|
|
|
2015-07-22 06:29:40 +02:00
|
|
|
## Issues and feedback
|
2014-11-18 03:35:47 +01:00
|
|
|
|
2016-06-10 20:21:53 +02:00
|
|
|
Got an issue or an idea for a feature enhancement? Check out the [borgmatic
|
2016-06-13 07:40:04 +02:00
|
|
|
issue tracker](https://tree.taiga.io/project/witten-borgmatic/issues?page=1&status=399951,399952,399955). In
|
2015-09-03 03:45:15 +02:00
|
|
|
order to create a new issue or comment on an issue, you'll need to [login
|
|
|
|
first](https://tree.taiga.io/login).
|
2015-07-22 06:29:40 +02:00
|
|
|
|
|
|
|
Other questions or comments? Contact <mailto:witten@torsion.org>.
|