From d53ff5f1757af4f8697fbf9c0adc8fdd99daf8ec Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 7 Feb 2026 21:57:55 +0100 Subject: [PATCH] docs: consolidate key backup info in borg key export, fixes #6204 Consolidate key backup documentation into `borg key export` and reference it from Quickstart and FAQ to avoid duplication and inconsistency. Clarify that while `repokey` or `authenticated` mode stores the key in the repo, a separate backup is still recommended to protect against repository corruption or data loss. --- docs/faq.rst | 9 ++++----- docs/quickstart.rst | 16 ++-------------- src/borg/archiver.py | 34 ++++++++++++++++++++-------------- 3 files changed, 26 insertions(+), 33 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index 97c8f417d..b22707738 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -544,11 +544,10 @@ The Borg config directory has content that you should take care of: recovered. ``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 1f15b6dc3..8035544cf 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -370,18 +370,8 @@ 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. - - 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. + In any case, make a backup of the borg key, see :ref:`borg_key_export` for + more details. In case you lose your repository and the security information, but have an older copy of it to restore from, don't use that later for creating new @@ -389,8 +379,6 @@ For automated backups the passphrase can be specified using the values). It is better to initialize a new Borg repository. See also: :ref:`faq_corrupt_repo` -.. _template: paperkey.html - .. _remote_repos: Remote repositories diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 0470991b7..40a27125c 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -4771,28 +4771,34 @@ class Archiver: subparser.set_defaults(fallback_func=functools.partial(self.do_subcommand_help, subparser)) 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 + (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`` option creates a printable + 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 repokey encryption, the key is saved in the - repository in the config file. A backup is thus not strictly needed, - but it guards against the repository becoming inaccessible if the file - is damaged for some reason. - Examples:: borg key export /path/to/repo > encrypted-key-backup