diff --git a/docs/faq.rst b/docs/faq.rst index e9988c7838..2bdc6b59d5 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -381,11 +381,10 @@ How important is the $HOME/.config/borg directory? The Borg config directory has content that you should take care of: ``keys`` subdirectory - All your borg keyfile keys are stored in this directory. Please note that - borg repokey keys are stored inside the repository. You MUST make sure to have an - independent backup of these keyfiles, otherwise you cannot access your backups anymore if you lose - them. You also MUST keep these files secret; everyone who gains access to your repository and has - the corresponding keyfile (and the key passphrase) can extract it. + All your borg keyfile keys are stored in this directory. Please note that borg + repokey keys are stored inside the repository. In any case, you MUST make sure + to have an independent backup of the borg keys, see :ref:`borg_key_export` for + more details. Make sure that only you have access to the Borg config directory. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 03ea01f84f..b5313d9cf0 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -350,20 +350,9 @@ For automated backups the passphrase can be specified using the .. warning:: The repository data is totally inaccessible without the key and the key passphrase. - Make a backup copy of the key file (``keyfile`` mode) or repo config - file (``repokey`` mode) and keep it at a safe place, so you still have - the key in case it gets corrupted or lost. Also keep your passphrase - at a safe place. You can make backups using :ref:`borg_key_export` - subcommand. + In any case, make a backup of the borg key, see :ref:`borg_key_export` for + more details. - If you want to print a backup of your key to paper use the ``--paper`` - option of this command and print the result, or print this `template`_ - if you need a version with QR-Code. - - A backup inside of the backup that is encrypted with that key/passphrase - won't help you with that, of course. - -.. _template: paperkey.html .. _remote_repos: diff --git a/src/borg/archiver/key_cmds.py b/src/borg/archiver/key_cmds.py index 99cffbafef..5d7a9503ee 100644 --- a/src/borg/archiver/key_cmds.py +++ b/src/borg/archiver/key_cmds.py @@ -135,27 +135,33 @@ def build_parser_keys(self, subparsers, common_parser, mid_common_parser): key_export_epilog = process_epilog( """ + This command backs up the borg key. + If repository encryption is used, the repository is inaccessible - without the key. This command allows one to back up this essential key. + without the borg key (and the passphrase that protects the borg key). + If a repository is not encrypted, but authenticated, the borg key is + still needed to access the repository normally. + + For repositories using **keyfile** encryption the key is kept locally + on the system that is capable of doing backups. To guard against loss + or corruption of this key, the key needs to be backed up independently + of the main data backup. + + For repositories using **repokey** encryption or **authenticated** mode + the key is kept in the repository. A backup is thus not strictly needed, + but guards against the repository becoming inaccessible if the key is + corrupted or lost. + Note that the backup produced does not include the passphrase itself (i.e. the exported key stays encrypted). In order to regain access to a repository, one needs both the exported key and the original passphrase. + Keep the exported key and the passphrase at safe places. There are three 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. The ``--qr-html`` creates a printable HTML template with a QR code and a copy of the ``--paper``-formatted key. - - 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(