Browse Source

Documentation updates based on the new YAML configuration.

tags/1.1.0
Dan Helfman 3 years ago
parent
commit
f98558546c
6 changed files with 51 additions and 126 deletions
  1. +41
    -13
      README.md
  2. +5
    -0
      borgmatic/commands/generate_config.py
  3. +5
    -6
      borgmatic/config/schema.yaml
  4. +0
    -48
      sample/config
  5. +0
    -56
      sample/config.yaml
  6. +0
    -3
      sample/excludes

+ 41
- 13
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 generate-borgmatic-config

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

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 mkdir /etc/borgmatic/
sudo mv config.yaml excludes /etc/borgmatic/
sudo pip install --upgrade borgmatic

Then, run:

Lastly, modify the /etc files with your desired configuration.
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

### 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
- 0
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)

+ 5
- 6
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


+ 0
- 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

+ 0
- 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

+ 0
- 3
sample/excludes View File

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

Loading…
Cancel
Save