archiver: Add documentation for "key export" and "key import" commands. (#1641)

archiver: Add documentation for "key export" and "key import" commands

borg/archiver.py

@@ -1120,9 +1120,28 @@ class Archiver:
 
         key_parsers = subparser.add_subparsers(title='required arguments', metavar='<command>')
 
+        key_export_epilog = textwrap.dedent("""
+        If repository encryption is used, the repository is inaccessible
+        without the key. This command allows to backup this essential key.
+
+        There are two backup formats. The normal backup format is suitable for
+        digital storage as a file. The ``--paper`` backup format is optimized
+        for printing and typing in while importing, with per line checks to
+        reduce problems with manual input.
+
+        For repositories using keyfile encryption the key is saved locally
+        on the system that is capable of doing backups. To guard against loss
+        of this key, the key needs to be backed up independently of the main
+        data backup.
+
+        For repositories using the repokey encryption the key is saved in the
+        repository in the config file. A backup is thus not strictly needed,
+        but guards against the repository becoming inaccessible if the file
+        is damaged for some reason.
+        """)
         subparser = key_parsers.add_parser('export', parents=[common_parser],
                                           description=self.do_key_export.__doc__,
-                                          epilog="",
+                                          epilog=key_export_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
                                           help='export repository key for backup')
         subparser.set_defaults(func=self.do_key_export)
@@ -1134,9 +1153,17 @@ class Archiver:
                                default=False,
                                help='Create an export suitable for printing and later type-in')
 
+        key_import_epilog = textwrap.dedent("""
+        This command allows to restore a key previously backed up with the
+        export command.
+
+        If the ``--paper`` option is given, the import will be an interactive
+        process in which each line is checked for plausibility before
+        proceeding to the next line. For this format PATH must not be given.
+        """)
         subparser = key_parsers.add_parser('import', parents=[common_parser],
                                           description=self.do_key_import.__doc__,
-                                          epilog="",
+                                          epilog=key_import_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
                                           help='import repository key from backup')
         subparser.set_defaults(func=self.do_key_import)

docs/quickstart.rst

@@ -228,8 +228,13 @@ For automated backups the passphrase can be specified using the
     the key in case it gets corrupted or lost. Also keep your passphrase
     at a safe place.
 
-    The backup that is encrypted with that key/passphrase won't help you
-    with that, of course.
+    You can make backups using :ref:`borg_key_export` subcommand.
+
+    If you want to print a backup of your key to paper use the ``--paper``
+    option of this command and print the result.
+
+    A backup inside of the backup that is encrypted with that key/passphrase
+    won't help you with that, of course.
 
 .. _remote_repos:
 

docs/usage.rst

@@ -484,6 +484,12 @@ Examples
     $ fusermount -u /tmp/mymountpoint
 
 
+.. include:: usage/key_export.rst.inc
+
+
+.. include:: usage/key_import.rst.inc
+
+
 .. include:: usage/change-passphrase.rst.inc
 
 Examples

docs/usage/key_export.rst.inc

@@ -0,0 +1,57 @@
+.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
+
+.. _borg_key_export:
+
+borg key export
+---------------
+::
+
+    usage: borg key export [-h] [--critical] [--error] [--warning] [--info]
+                           [--debug] [--lock-wait N] [--show-rc]
+                           [--no-files-cache] [--umask M] [--remote-path PATH]
+                           [--paper]
+                           [REPOSITORY] [PATH]
+    
+    Export the repository key for backup
+    
+    positional arguments:
+      REPOSITORY
+      PATH                  where to store the backup
+    
+    optional arguments:
+      -h, --help            show this help message and exit
+      --critical            work on log level CRITICAL
+      --error               work on log level ERROR
+      --warning             work on log level WARNING (default)
+      --info, -v, --verbose
+                            work on log level INFO
+      --debug               work on log level DEBUG
+      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
+      --show-rc             show/log the return code (rc)
+      --no-files-cache      do not load/update the file metadata cache used to
+                            detect unchanged files
+      --umask M             set umask to M (local and remote, default: 0077)
+      --remote-path PATH    set remote path to executable (default: "borg")
+      --paper               Create an export suitable for printing and later type-
+                            in
+    
+Description
+~~~~~~~~~~~
+
+If repository encryption is used, the repository is inaccessible
+without the key. This command allows to backup this essential key.
+
+There are two backup formats. The normal backup format is suitable for
+digital storage as a file. The ``--paper`` backup format is optimized for
+print out and later type-in, with per line checks to reduce problems
+with manual input.
+
+For repositories using keyfile encryption the key is saved locally
+on the system that is capable of doing backups. To guard against loss
+of this key the key needs to be backed up independent of the main data
+backup.
+
+For repositories using the repokey encryption the key is saved in the
+repository in the config file. A backup is thus not strictly needed,
+but guards against the repository becoming inaccessible if the file
+is damaged for some reason.

docs/usage/key_import.rst.inc

@@ -0,0 +1,45 @@
+.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
+
+.. _borg_key_import:
+
+borg key import
+---------------
+::
+
+    usage: borg key import [-h] [--critical] [--error] [--warning] [--info]
+                           [--debug] [--lock-wait N] [--show-rc]
+                           [--no-files-cache] [--umask M] [--remote-path PATH]
+                           [--paper]
+                           [REPOSITORY] [PATH]
+    
+    Import the repository key from backup
+    
+    positional arguments:
+      REPOSITORY
+      PATH                  path to the backup
+    
+    optional arguments:
+      -h, --help            show this help message and exit
+      --critical            work on log level CRITICAL
+      --error               work on log level ERROR
+      --warning             work on log level WARNING (default)
+      --info, -v, --verbose
+                            work on log level INFO
+      --debug               work on log level DEBUG
+      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
+      --show-rc             show/log the return code (rc)
+      --no-files-cache      do not load/update the file metadata cache used to
+                            detect unchanged files
+      --umask M             set umask to M (local and remote, default: 0077)
+      --remote-path PATH    set remote path to executable (default: "borg")
+      --paper               interactively import from a backup done with --paper
+    
+Description
+~~~~~~~~~~~
+
+This command allows to restore a key previously backed up with the
+export command.
+
+If the ``--paper`` option is given, the import will be an interactive
+process in which each line is checked for plausibility before
+proceeding to the next line. For this format PATH must not be given.