From ff28be77249bc28ba28006c8313fb470166a3d1b Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Mon, 10 Jul 2017 11:06:28 -0700 Subject: [PATCH] Documentation updates based on the new YAML configuration. --- README.md | 54 +++++++++++++++++++------- borgmatic/commands/generate_config.py | 5 +++ borgmatic/config/schema.yaml | 11 +++--- sample/config | 48 ----------------------- sample/config.yaml | 56 --------------------------- sample/excludes | 3 -- 6 files changed, 51 insertions(+), 126 deletions(-) delete mode 100644 sample/config delete mode 100644 sample/config.yaml delete mode 100644 sample/excludes diff --git a/README.md b/README.md index 5e69283ae..b1225c346 100644 --- a/README.md +++ b/README.md @@ -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 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 diff --git a/borgmatic/commands/generate_config.py b/borgmatic/commands/generate_config.py index 0f0474086..ba88ddf8c 100644 --- a/borgmatic/commands/generate_config.py +++ b/borgmatic/commands/generate_config.py @@ -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) diff --git a/borgmatic/config/schema.yaml b/borgmatic/config/schema.yaml index 97f13d98a..dfd0c55bb 100644 --- a/borgmatic/config/schema.yaml +++ b/borgmatic/config/schema.yaml @@ -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 diff --git a/sample/config b/sample/config deleted file mode 100644 index e778aaacd..000000000 --- a/sample/config +++ /dev/null @@ -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 diff --git a/sample/config.yaml b/sample/config.yaml deleted file mode 100644 index daac2305f..000000000 --- a/sample/config.yaml +++ /dev/null @@ -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 diff --git a/sample/excludes b/sample/excludes deleted file mode 100644 index 7e81c882a..000000000 --- a/sample/excludes +++ /dev/null @@ -1,3 +0,0 @@ -*.pyc -/home/*/.cache -/etc/ssl