diff --git a/borg/archiver.py b/borg/archiver.py index 3c4682e5a..ce7655fc5 100644 --- a/borg/archiver.py +++ b/borg/archiver.py @@ -1120,9 +1120,28 @@ class Archiver: key_parsers = subparser.add_subparsers(title='required arguments', metavar='') + 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) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 20cd32d1d..f7105d6a7 100644 --- a/docs/quickstart.rst +++ b/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: diff --git a/docs/usage.rst b/docs/usage.rst index 89a9e3cc7..a3015f61b 100644 --- a/docs/usage.rst +++ b/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 diff --git a/docs/usage/key_export.rst.inc b/docs/usage/key_export.rst.inc new file mode 100644 index 000000000..47e9e119e --- /dev/null +++ b/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. diff --git a/docs/usage/key_import.rst.inc b/docs/usage/key_import.rst.inc new file mode 100644 index 000000000..71a8eed46 --- /dev/null +++ b/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.