psw/borgmatic
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Documentation updates based on the new YAML configuration.

Browse source
This commit is contained in:
Dan Helfman 2017-07-10 11:06:28 -07:00
parent 9cc7c77ba9
commit f98558546c
6 changed files with 51 additions and 126 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
README.md
View file

@ -24,6 +24,10 @@ location:
# Path to local or remote repository.
repository: user@backupserver:sourcehostname.borg
# Any paths matching these patterns are excluded from backups.
exclude_patterns:
- /home/*/.cache
retention:
# Retention policy for how many backups to keep in each category.
keep_daily: 7
@ -37,16 +41,13 @@ consistency:
- archives
```
Additionally, exclude patterns can be specified in a separate excludes config
file, one pattern per line.
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.
## Setup
## Installation
To get up and running, follow the [Borg Quick
Start](https://borgbackup.readthedocs.org/en/latest/quickstart.html) to create
@ -66,19 +67,45 @@ To install borgmatic, run the following command to download and install it:
Make sure you're using Python 3, as borgmatic does not support Python 2. (You
may have to use "pip3" instead of "pip".)
Then, download a [sample config
file](https://torsion.org/hg/borgmatic/raw-file/tip/sample/config.yaml) and a
[sample excludes
file](https://torsion.org/hg/borgmatic/raw-file/tip/sample/excludes). From the
directory where you downloaded them:
Then, generate a sample configuration file:
sudo mkdir /etc/borgmatic/
sudo mv config.yaml excludes /etc/borgmatic/
sudo generate-borgmatic-config
Lastly, modify the /etc files with your desired configuration.
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
to remove anything you don't need.
## Upgrading from atticmatic
## Upgrading
In general, all you should need to do to upgrade borgmatic is run the
following:
sudo pip install --upgrade borgmatic
However, see below about special cases.
### 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
upgrade to the new version of borgmatic:
sudo pip install --upgrade borgmatic
Then, run:
sudo upgrade-borgmatic-configuration
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.
### Upgrading from atticmatic
You can ignore this section if you're not an atticmatic user (the former name
of borgmatic).
@ -98,6 +125,7 @@ from atticmatic to borgmatic. Simply run the following commands:
That's it! borgmatic will continue using your /etc/borgmatic configuration
files.
## Usage
You can run borgmatic and start a backup simply by invoking it without

5
borgmatic/commands/generate_config.py
View file

@ -34,6 +34,11 @@ def main(): # pragma: no cover
args = parse_arguments(*sys.argv[1:])
generate.generate_sample_configuration(args.destination_filename, validate.schema_filename())
print('Generated a sample configuration file at {}.'.format(args.destination_filename))
print()
print('Please edit the file to suit your needs. The values are just representative.')
print('All fields are optional except where indicated.')
except (ValueError, OSError) as error:
print(error, file=sys.stderr)
sys.exit(1)

11
borgmatic/config/schema.yaml
View file

@ -12,7 +12,7 @@ map:
required: True
seq:
- type: scalar
desc: List of source directories to backup. Globs are expanded.
desc: List of source directories to backup (required). Globs are expanded.
example:
- /home
- /etc
@ -28,16 +28,15 @@ map:
repository:
required: True
type: scalar
desc: Path to local or remote repository.
desc: Path to local or remote repository (required).
example: user@backupserver:sourcehostname.borg
exclude_patterns:
seq:
- type: scalar
desc: |
Exclude patterns. Any paths matching these patterns are excluded from backups.
Globs are expanded. See
https://borgbackup.readthedocs.io/en/stable/usage.html#borg-help-patterns for
details.
Any paths matching these patterns are excluded from backups. Globs are expanded.
See https://borgbackup.readthedocs.io/en/stable/usage.html#borg-help-patterns
for details.
example:
- '*.pyc'
- /home/*/.cache

48
sample/config
View file

@ -1,48 +0,0 @@
[location]
# Space-separated list of source directories to backup.
# Globs are expanded.
source_directories: /home /etc /var/log/syslog*
# Stay in same file system (do not cross mount points).
#one_file_system: True
# Alternate Borg remote executable (defaults to "borg"):
#remote_path: borg1
# Path to local or remote repository.
repository: user@backupserver:sourcehostname.borg
[storage]
# Passphrase to unlock the encryption key with. Only use on repositories that
# were initialized with passphrase/repokey encryption.
#encryption_passphrase: foo
# Type of compression to use when creating archives. See
# https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create
# for details. Defaults to no compression.
#compression: lz4
# Umask to be used for borg create.
#umask: 0077
[retention]
# Retention policy for how many backups to keep in each category. See
# https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details.
#keep_within: 3H
#keep_hourly: 24
keep_daily: 7
keep_weekly: 4
keep_monthly: 6
keep_yearly: 1
#prefix: sourcehostname
[consistency]
# Space-separated list of consistency checks to run: "repository", "archives",
# or both. Defaults to both. Set to "disabled" to disable all consistency
# checks. See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check
# for details.
checks: repository archives
# Restrict the number of checked archives to the last n.
#check_last: 3

56
sample/config.yaml
View file

@ -1,56 +0,0 @@
location:
# List of source directories to backup. Globs are expanded.
source_directories:
- /home
- /etc
- /var/log/syslog*
# Stay in same file system (do not cross mount points).
#one_file_system: yes
# Alternate Borg remote executable (defaults to "borg"):
#remote_path: borg1
# Path to local or remote repository.
repository: user@backupserver:sourcehostname.borg
#storage:
# Passphrase to unlock the encryption key with. Only use on repositories
# that were initialized with passphrase/repokey encryption. Quote the value
# if it contains punctuation so it parses correctly. And backslash any
# quote or backslash literals as well.
#encryption_passphrase: "foo"
# Type of compression to use when creating archives. See
# https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create
# for details. Defaults to no compression.
#compression: lz4
# Umask to be used for borg create.
#umask: 0077
retention:
# Retention policy for how many backups to keep in each category. See
# https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for
# details.
#keep_within: 3H
#keep_hourly: 24
keep_daily: 7
keep_weekly: 4
keep_monthly: 6
keep_yearly: 1
# When pruning, only consider archive names starting with this prefix.
#prefix: sourcehostname
consistency:
# List of consistency checks to run: "repository", "archives", or both.
# Defaults to both. Set to "disabled" to disable all consistency checks.
# See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check
# for details.
checks:
- repository
- archives
# Restrict the number of checked archives to the last n.
#check_last: 3

3
sample/excludes
View file

@ -1,3 +0,0 @@
*.pyc
/home/*/.cache
/etc/ssl