mirror of https://github.com/borgbackup/borg.git
archiver: Add documentation for "key export" and "key import" commands. (#1641)
archiver: Add documentation for "key export" and "key import" commands
This commit is contained in:
parent
f2cc97da8d
commit
b84014e7d9
|
@ -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)
|
||||
|
|
|
@ -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:
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.
|
|
@ -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.
|
Loading…
Reference in New Issue