upstream/borgbackup
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-04-15 21:59:58 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: consolidate key backup info in borg key export, fixes #6204

Browse source 
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.
This commit is contained in:
Thomas Waldmann 2026-02-07 21:57:55 +01:00
parent 3186cc4114
commit d53ff5f175
No known key found for this signature in database
GPG key ID: 243ACFA951F78E01
3 changed files with 26 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
docs/faq.rst
View file

@ -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.

16
docs/quickstart.rst
View file

@ -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

34
src/borg/archiver.py
View file

@ -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