Browse Source

Documentation updates based on the new YAML configuration.

Dan Helfman 1 year 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:
24 24
     # Path to local or remote repository.
25 25
     repository: user@backupserver:sourcehostname.borg
26 26
 
27
+    # Any paths matching these patterns are excluded from backups.
28
+    exclude_patterns:
29
+        - /home/*/.cache
30
+
27 31
 retention:
28 32
     # Retention policy for how many backups to keep in each category.
29 33
     keep_daily: 7
@@ -37,16 +41,13 @@ consistency:
37 41
         - archives
38 42
 ```
39 43
 
40
-Additionally, exclude patterns can be specified in a separate excludes config
41
-file, one pattern per line.
42
-
43 44
 borgmatic is hosted at <https://torsion.org/borgmatic> with [source code
44 45
 available](https://torsion.org/hg/borgmatic). It's also mirrored on
45 46
 [GitHub](https://github.com/witten/borgmatic) and
46 47
 [BitBucket](https://bitbucket.org/dhelfman/borgmatic) for convenience.
47 48
 
48 49
 
49
-## Setup
50
+## Installation
50 51
 
51 52
 To get up and running, follow the [Borg Quick
52 53
 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:
66 67
 Make sure you're using Python 3, as borgmatic does not support Python 2. (You
67 68
 may have to use "pip3" instead of "pip".)
68 69
 
69
-Then, download a [sample config
70
-file](https://torsion.org/hg/borgmatic/raw-file/tip/sample/config.yaml) and a
71
-[sample excludes
72
-file](https://torsion.org/hg/borgmatic/raw-file/tip/sample/excludes). From the
73
-directory where you downloaded them:
70
+Then, generate a sample configuration file:
71
+
72
+    sudo generate-borgmatic-config
73
+
74
+This generates a sample configuration file at /etc/borgmatic/config.yaml (by
75
+default). You should edit the file to suit your needs, as the values are just
76
+representative. All fields are optional except where indicated, so feel free
77
+to remove anything you don't need.
78
+
79
+
80
+## Upgrading
81
+
82
+In general, all you should need to do to upgrade borgmatic is run the
83
+following:
84
+
85
+    sudo pip install --upgrade borgmatic
86
+
87
+However, see below about special cases.
88
+
89
+### Upgrading from borgmatic 1.0.x
90
+
91
+borgmatic changed its configuration file format in version 1.1.0 from
92
+INI-style to YAML. This better supports validation, and has a more natural way
93
+to express lists of values. To upgrade your existing configuration, first
94
+upgrade to the new version of borgmatic:
74 95
 
75
-    sudo mkdir /etc/borgmatic/
76
-    sudo mv config.yaml excludes /etc/borgmatic/
96
+    sudo pip install --upgrade borgmatic
97
+
98
+Then, run:
77 99
 
78
-Lastly, modify the /etc files with your desired configuration.
100
+    sudo upgrade-borgmatic-configuration
79 101
 
102
+That will generate a new YAML configuration file at /etc/borgmatic/config.yaml
103
+(by default) using the values from both your existing configuration and
104
+excludes files. The new version of borgmatic will consume the YAML
105
+configuration file instead of the old one.
80 106
 
81
-## Upgrading from atticmatic
107
+
108
+### Upgrading from atticmatic
82 109
 
83 110
 You can ignore this section if you're not an atticmatic user (the former name
84 111
 of borgmatic).
@@ -98,6 +125,7 @@ from atticmatic to borgmatic. Simply run the following commands:
98 125
 That's it! borgmatic will continue using your /etc/borgmatic configuration
99 126
 files.
100 127
 
128
+
101 129
 ## Usage
102 130
 
103 131
 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
34 34
         args = parse_arguments(*sys.argv[1:])
35 35
 
36 36
         generate.generate_sample_configuration(args.destination_filename, validate.schema_filename())
37
+
38
+        print('Generated a sample configuration file at {}.'.format(args.destination_filename))
39
+        print()
40
+        print('Please edit the file to suit your needs. The values are just representative.')
41
+        print('All fields are optional except where indicated.')
37 42
     except (ValueError, OSError) as error:
38 43
         print(error, file=sys.stderr)
39 44
         sys.exit(1)

+ 5
- 6
borgmatic/config/schema.yaml View File

@@ -12,7 +12,7 @@ map:
12 12
                 required: True
13 13
                 seq:
14 14
                     - type: scalar
15
-                desc: List of source directories to backup. Globs are expanded.
15
+                desc: List of source directories to backup (required). Globs are expanded.
16 16
                 example:
17 17
                     - /home
18 18
                     - /etc
@@ -28,16 +28,15 @@ map:
28 28
             repository:
29 29
                 required: True
30 30
                 type: scalar
31
-                desc: Path to local or remote repository.
31
+                desc: Path to local or remote repository (required).
32 32
                 example: user@backupserver:sourcehostname.borg
33 33
             exclude_patterns:
34 34
                 seq:
35 35
                     - type: scalar
36 36
                 desc: |
37
-                    Exclude patterns. Any paths matching these patterns are excluded from backups.
38
-                    Globs are expanded. See
39
-                    https://borgbackup.readthedocs.io/en/stable/usage.html#borg-help-patterns for
40
-                    details.
37
+                    Any paths matching these patterns are excluded from backups. Globs are expanded.
38
+                    See https://borgbackup.readthedocs.io/en/stable/usage.html#borg-help-patterns
39
+                    for details.
41 40
                 example:
42 41
                     - '*.pyc'
43 42
                     - /home/*/.cache

+ 0
- 48
sample/config View File

@@ -1,48 +0,0 @@
1
-[location]
2
-# Space-separated list of source directories to backup.
3
-# Globs are expanded.
4
-source_directories: /home /etc /var/log/syslog*
5
-
6
-# Stay in same file system (do not cross mount points).
7
-#one_file_system: True
8
-
9
-# Alternate Borg remote executable (defaults to "borg"):
10
-#remote_path: borg1
11
-
12
-# Path to local or remote repository.
13
-repository: user@backupserver:sourcehostname.borg
14
-
15
-[storage]
16
-# Passphrase to unlock the encryption key with. Only use on repositories that
17
-# were initialized with passphrase/repokey encryption.
18
-#encryption_passphrase: foo
19
-
20
-# Type of compression to use when creating archives. See
21
-# https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create
22
-# for details. Defaults to no compression.
23
-#compression: lz4
24
-
25
-# Umask to be used for borg create.
26
-#umask: 0077
27
-
28
-[retention]
29
-# Retention policy for how many backups to keep in each category. See
30
-# https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details.
31
-#keep_within: 3H
32
-#keep_hourly: 24
33
-keep_daily: 7
34
-keep_weekly: 4
35
-keep_monthly: 6
36
-keep_yearly: 1
37
-
38
-#prefix: sourcehostname
39
-
40
-[consistency]
41
-# Space-separated list of consistency checks to run: "repository", "archives",
42
-# or both. Defaults to both. Set to "disabled" to disable all consistency
43
-# checks. See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check
44
-# for details.
45
-checks: repository archives
46
-
47
-# Restrict the number of checked archives to the last n.
48
-#check_last: 3

+ 0
- 56
sample/config.yaml View File

@@ -1,56 +0,0 @@
1
-location:
2
-    # List of source directories to backup. Globs are expanded.
3
-    source_directories:
4
-        - /home
5
-        - /etc
6
-        - /var/log/syslog*
7
-
8
-    # Stay in same file system (do not cross mount points).
9
-    #one_file_system: yes
10
-
11
-    # Alternate Borg remote executable (defaults to "borg"):
12
-    #remote_path: borg1
13
-
14
-    # Path to local or remote repository.
15
-    repository: user@backupserver:sourcehostname.borg
16
-
17
-#storage:
18
-    # Passphrase to unlock the encryption key with. Only use on repositories
19
-    # that were initialized with passphrase/repokey encryption. Quote the value
20
-    # if it contains punctuation so it parses correctly. And backslash any
21
-    # quote or backslash literals as well.
22
-    #encryption_passphrase: "foo"
23
-
24
-    # Type of compression to use when creating archives. See
25
-    # https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create
26
-    # for details. Defaults to no compression.
27
-    #compression: lz4
28
-
29
-    # Umask to be used for borg create.
30
-    #umask: 0077
31
-
32
-retention:
33
-    # Retention policy for how many backups to keep in each category. See
34
-    # https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for
35
-    # details.
36
-    #keep_within: 3H
37
-    #keep_hourly: 24
38
-    keep_daily: 7
39
-    keep_weekly: 4
40
-    keep_monthly: 6
41
-    keep_yearly: 1
42
-
43
-    # When pruning, only consider archive names starting with this prefix.
44
-    #prefix: sourcehostname
45
-
46
-consistency:
47
-    # List of consistency checks to run: "repository", "archives", or both.
48
-    # Defaults to both. Set to "disabled" to disable all consistency checks.
49
-    # See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check
50
-    # for details.
51
-    checks:
52
-        - repository
53
-        - archives
54
-
55
-    # Restrict the number of checked archives to the last n.
56
-    #check_last: 3

+ 0
- 3
sample/excludes View File

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

Loading…
Cancel
Save