borgmatic/README.md

154 lines
4.7 KiB
Markdown
Raw Normal View History

2016-06-10 20:21:53 +02:00
title: Borgmatic
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
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
Here's an example config file:
```INI
[location]
# Space-separated list of source directories to backup.
# Globs are expanded.
source_directories: /home /etc /var/log/syslog*
# Path to local or remote backup repository.
2016-06-10 20:21:53 +02:00
repository: user@backupserver:sourcehostname.borg
[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
```
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
`encryption_passphrase` configuration variable. See the repository encryption
section of the Quick Start for more info.
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:44:11 +02:00
sudo cp sample/borgmatic.cron /etc/cron.d/borgmatic
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
## 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:
borgmatic
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.
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
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
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
First install tox, which is used for setting up testing environments:
2014-11-18 06:57:44 +01:00
pip install tox
2014-11-18 06:57:44 +01:00
Then, to actually run tests, run:
2014-11-18 06:57:44 +01:00
tox
2014-11-18 06:57:44 +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
consistency:
Write failed: Broken pipe
2016-06-10 20:21:53 +02:00
borg: Error: Connection closed by remote host
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.
## 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
issue tracker](https://tree.taiga.io/project/witten-borgmatic/issues?page=1&status=399951,399952,399955). In
order to create a new issue or comment on an issue, you'll need to [login
first](https://tree.taiga.io/login).
Other questions or comments? Contact <mailto:witten@torsion.org>.