mirror of
https://github.com/borgbackup/borg.git
synced 2026-06-13 19:00:44 -04:00
docs: add docs for "key add", "key list" and "key remove"
The multi-key feature (#9743) added the "borg key add", "borg key list" and "borg key remove" subcommands but never wired up their docs: - scripts/make.py: map key_add/key_list/key_remove to the "key" usage group, so build_man can locate their examples (it previously aborted with FileNotFoundError: docs/usage/key_add.rst). - docs/usage/key.rst: include the three new generated snippets so they show up on the HTML key page. - regenerate the affected docs: new key_{add,list,remove}.rst.inc usage snippets, new borg-key-{add,list,remove}.1 man pages, and borg-key.1 (SYNOPSIS + SEE ALSO now reference the new subcommands). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Thomas Waldmann
parent
e0c7a68a3e
commit
d5cd72b179
9 changed files with 357 additions and 2 deletions
66
docs/man/borg-key-add.1
Normal file
66
docs/man/borg-key-add.1
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
.\" Man page generated from reStructuredText
|
||||
.\" by the Docutils 0.22.4 manpage writer.
|
||||
.
|
||||
.
|
||||
.nr rst2man-indent-level 0
|
||||
.
|
||||
.de1 rstReportMargin
|
||||
\\$1 \\n[an-margin]
|
||||
level \\n[rst2man-indent-level]
|
||||
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
-
|
||||
\\n[rst2man-indent0]
|
||||
\\n[rst2man-indent1]
|
||||
\\n[rst2man-indent2]
|
||||
..
|
||||
.de1 INDENT
|
||||
.\" .rstReportMargin pre:
|
||||
. RS \\$1
|
||||
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
||||
. nr rst2man-indent-level +1
|
||||
.\" .rstReportMargin post:
|
||||
..
|
||||
.de UNINDENT
|
||||
. RE
|
||||
.\" indent \\n[an-margin]
|
||||
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.nr rst2man-indent-level -1
|
||||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "borg-key-add" "1" "2026-06-13" "" "borg backup tool"
|
||||
.SH Name
|
||||
borg-key-add \- Add a new borg key (protected by an independent passphrase) to the repository.
|
||||
.SH SYNOPSIS
|
||||
.sp
|
||||
borg [common options] key add [options]
|
||||
.SH DESCRIPTION
|
||||
.sp
|
||||
A repository can be protected by more than one borg key. Each borg key contains the
|
||||
same secret key material, but is protected by an independent (potentially different)
|
||||
passphrase, and any of them can be used to unlock the same repository. This is useful
|
||||
e.g. to give individual users their own passphrase while keeping a separate
|
||||
admin/recovery passphrase.
|
||||
.sp
|
||||
This command adds an additional borg key. It does not re\-encrypt any repository data
|
||||
and does not change the existing borg keys. The new passphrase is read from
|
||||
\fBBORG_NEW_PASSPHRASE\fP or queried interactively.
|
||||
.sp
|
||||
Each borg key has a label. The first borg key, created at repository creation time, has
|
||||
the reserved label \fBadmin\fP and is protected from deletion. Additionally added borg
|
||||
keys require a unique, user\-defined \fB\-\-label\fP\&.
|
||||
.SH OPTIONS
|
||||
.sp
|
||||
See \fIborg\-common(1)\fP for common options of Borg commands.
|
||||
.SS options
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.BI \-\-label \ LABEL
|
||||
label for the new borg key (must be unique)
|
||||
.UNINDENT
|
||||
.SH SEE ALSO
|
||||
.sp
|
||||
\fIborg\-common(1)\fP
|
||||
.SH Author
|
||||
The Borg Collective
|
||||
.\" End of generated man page.
|
||||
50
docs/man/borg-key-list.1
Normal file
50
docs/man/borg-key-list.1
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
.\" Man page generated from reStructuredText
|
||||
.\" by the Docutils 0.22.4 manpage writer.
|
||||
.
|
||||
.
|
||||
.nr rst2man-indent-level 0
|
||||
.
|
||||
.de1 rstReportMargin
|
||||
\\$1 \\n[an-margin]
|
||||
level \\n[rst2man-indent-level]
|
||||
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
-
|
||||
\\n[rst2man-indent0]
|
||||
\\n[rst2man-indent1]
|
||||
\\n[rst2man-indent2]
|
||||
..
|
||||
.de1 INDENT
|
||||
.\" .rstReportMargin pre:
|
||||
. RS \\$1
|
||||
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
||||
. nr rst2man-indent-level +1
|
||||
.\" .rstReportMargin post:
|
||||
..
|
||||
.de UNINDENT
|
||||
. RE
|
||||
.\" indent \\n[an-margin]
|
||||
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.nr rst2man-indent-level -1
|
||||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "borg-key-list" "1" "2026-06-13" "" "borg backup tool"
|
||||
.SH Name
|
||||
borg-key-list \- List the borg keys of the repository.
|
||||
.SH SYNOPSIS
|
||||
.sp
|
||||
borg [common options] key list [options]
|
||||
.SH DESCRIPTION
|
||||
.sp
|
||||
List the borg keys of the repository, showing each borg key\(aqs id, mode (\fBrepokey\fP or
|
||||
\fBkeyfile\fP), label and key derivation/encryption algorithm. The borg key used to
|
||||
unlock the repository in this invocation is marked with \fB*\fP\&.
|
||||
.SH OPTIONS
|
||||
.sp
|
||||
See \fIborg\-common(1)\fP for common options of Borg commands.
|
||||
.SH SEE ALSO
|
||||
.sp
|
||||
\fIborg\-common(1)\fP
|
||||
.SH Author
|
||||
The Borg Collective
|
||||
.\" End of generated man page.
|
||||
67
docs/man/borg-key-remove.1
Normal file
67
docs/man/borg-key-remove.1
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
.\" Man page generated from reStructuredText
|
||||
.\" by the Docutils 0.22.4 manpage writer.
|
||||
.
|
||||
.
|
||||
.nr rst2man-indent-level 0
|
||||
.
|
||||
.de1 rstReportMargin
|
||||
\\$1 \\n[an-margin]
|
||||
level \\n[rst2man-indent-level]
|
||||
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
-
|
||||
\\n[rst2man-indent0]
|
||||
\\n[rst2man-indent1]
|
||||
\\n[rst2man-indent2]
|
||||
..
|
||||
.de1 INDENT
|
||||
.\" .rstReportMargin pre:
|
||||
. RS \\$1
|
||||
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
||||
. nr rst2man-indent-level +1
|
||||
.\" .rstReportMargin post:
|
||||
..
|
||||
.de UNINDENT
|
||||
. RE
|
||||
.\" indent \\n[an-margin]
|
||||
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.nr rst2man-indent-level -1
|
||||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "borg-key-remove" "1" "2026-06-13" "" "borg backup tool"
|
||||
.SH Name
|
||||
borg-key-remove \- Remove a borg key from the repository.
|
||||
.SH SYNOPSIS
|
||||
.sp
|
||||
borg [common options] key remove [options]
|
||||
.SH DESCRIPTION
|
||||
.sp
|
||||
Remove a borg key from the repository.
|
||||
.sp
|
||||
The borg key to remove is selected by exactly one of: \fB\-\-label\fP (its label),
|
||||
\fB\-\-key\fP (its key id or a unique prefix, see \fBborg key list\fP), or
|
||||
\fB\-\-passphrase\fP (remove the borg key that was used to unlock the repository now).
|
||||
.sp
|
||||
The \fBadmin\fP borg key is protected and cannot be removed, and the last remaining
|
||||
borg key of a repository cannot be removed either.
|
||||
.SH OPTIONS
|
||||
.sp
|
||||
See \fIborg\-common(1)\fP for common options of Borg commands.
|
||||
.SS options
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.BI \-\-label \ LABEL
|
||||
remove the borg key with this label
|
||||
.TP
|
||||
.BI \-\-key \ ID
|
||||
remove the borg key with this id (or unique id prefix)
|
||||
.TP
|
||||
.B \-\-passphrase
|
||||
remove the borg key that was used to unlock the repository
|
||||
.UNINDENT
|
||||
.SH SEE ALSO
|
||||
.sp
|
||||
\fIborg\-common(1)\fP
|
||||
.SH Author
|
||||
The Borg Collective
|
||||
.\" End of generated man page.
|
||||
|
|
@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "borg-key" "1" "2026-03-15" "" "borg backup tool"
|
||||
.TH "borg-key" "1" "2026-06-13" "" "borg backup tool"
|
||||
.SH Name
|
||||
borg-key \- Manage the keyfile or repokey of a repository
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -36,12 +36,15 @@ borg-key \- Manage the keyfile or repokey of a repository
|
|||
borg [common options] key export ...
|
||||
borg [common options] key import ...
|
||||
borg [common options] key change\-passphrase ...
|
||||
borg [common options] key add ...
|
||||
borg [common options] key remove ...
|
||||
borg [common options] key list ...
|
||||
borg [common options] key change\-location ...
|
||||
.fi
|
||||
.sp
|
||||
.SH SEE ALSO
|
||||
.sp
|
||||
\fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP, \fIborg\-key\-change\-location(1)\fP
|
||||
\fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP, \fIborg\-key\-add(1)\fP, \fIborg\-key\-remove(1)\fP, \fIborg\-key\-list(1)\fP, \fIborg\-key\-change\-location(1)\fP
|
||||
.SH Author
|
||||
The Borg Collective
|
||||
.\" End of generated man page.
|
||||
|
|
|
|||
|
|
@ -67,3 +67,9 @@ Examples
|
|||
borg key export --qr-html encrypted-key-backup.html
|
||||
|
||||
.. include:: key_import.rst.inc
|
||||
|
||||
.. include:: key_add.rst.inc
|
||||
|
||||
.. include:: key_list.rst.inc
|
||||
|
||||
.. include:: key_remove.rst.inc
|
||||
|
|
|
|||
59
docs/usage/key_add.rst.inc
Normal file
59
docs/usage/key_add.rst.inc
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
|
||||
|
||||
.. _borg_key_add:
|
||||
|
||||
borg key add
|
||||
------------
|
||||
.. code-block:: none
|
||||
|
||||
borg [common options] key add [options]
|
||||
|
||||
.. only:: html
|
||||
|
||||
.. class:: borg-options-table
|
||||
|
||||
+-------------------------------------------------------+-------------------+---------------------------------------------+
|
||||
| **options** |
|
||||
+-------------------------------------------------------+-------------------+---------------------------------------------+
|
||||
| | ``--label LABEL`` | label for the new borg key (must be unique) |
|
||||
+-------------------------------------------------------+-------------------+---------------------------------------------+
|
||||
| .. class:: borg-common-opt-ref |
|
||||
| |
|
||||
| :ref:`common_options` |
|
||||
+-------------------------------------------------------+-------------------+---------------------------------------------+
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<script type='text/javascript'>
|
||||
$(document).ready(function () {
|
||||
$('.borg-options-table colgroup').remove();
|
||||
})
|
||||
</script>
|
||||
|
||||
.. only:: latex
|
||||
|
||||
|
||||
|
||||
options
|
||||
--label LABEL label for the new borg key (must be unique)
|
||||
|
||||
|
||||
:ref:`common_options`
|
||||
|
|
||||
|
||||
Description
|
||||
~~~~~~~~~~~
|
||||
|
||||
A repository can be protected by more than one borg key. Each borg key contains the
|
||||
same secret key material, but is protected by an independent (potentially different)
|
||||
passphrase, and any of them can be used to unlock the same repository. This is useful
|
||||
e.g. to give individual users their own passphrase while keeping a separate
|
||||
admin/recovery passphrase.
|
||||
|
||||
This command adds an additional borg key. It does not re-encrypt any repository data
|
||||
and does not change the existing borg keys. The new passphrase is read from
|
||||
``BORG_NEW_PASSPHRASE`` or queried interactively.
|
||||
|
||||
Each borg key has a label. The first borg key, created at repository creation time, has
|
||||
the reserved label ``admin`` and is protected from deletion. Additionally added borg
|
||||
keys require a unique, user-defined ``--label``.
|
||||
41
docs/usage/key_list.rst.inc
Normal file
41
docs/usage/key_list.rst.inc
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
|
||||
|
||||
.. _borg_key_list:
|
||||
|
||||
borg key list
|
||||
-------------
|
||||
.. code-block:: none
|
||||
|
||||
borg [common options] key list [options]
|
||||
|
||||
.. only:: html
|
||||
|
||||
.. class:: borg-options-table
|
||||
|
||||
+-------------------------------------------------------+
|
||||
| .. class:: borg-common-opt-ref |
|
||||
| |
|
||||
| :ref:`common_options` |
|
||||
+-------------------------------------------------------+
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<script type='text/javascript'>
|
||||
$(document).ready(function () {
|
||||
$('.borg-options-table colgroup').remove();
|
||||
})
|
||||
</script>
|
||||
|
||||
.. only:: latex
|
||||
|
||||
|
||||
|
||||
:ref:`common_options`
|
||||
|
|
||||
|
||||
Description
|
||||
~~~~~~~~~~~
|
||||
|
||||
List the borg keys of the repository, showing each borg key's id, mode (``repokey`` or
|
||||
``keyfile``), label and key derivation/encryption algorithm. The borg key used to
|
||||
unlock the repository in this invocation is marked with ``*``.
|
||||
60
docs/usage/key_remove.rst.inc
Normal file
60
docs/usage/key_remove.rst.inc
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
|
||||
|
||||
.. _borg_key_remove:
|
||||
|
||||
borg key remove
|
||||
---------------
|
||||
.. code-block:: none
|
||||
|
||||
borg [common options] key remove [options]
|
||||
|
||||
.. only:: html
|
||||
|
||||
.. class:: borg-options-table
|
||||
|
||||
+-------------------------------------------------------+-------------------+------------------------------------------------------------+
|
||||
| **options** |
|
||||
+-------------------------------------------------------+-------------------+------------------------------------------------------------+
|
||||
| | ``--label LABEL`` | remove the borg key with this label |
|
||||
+-------------------------------------------------------+-------------------+------------------------------------------------------------+
|
||||
| | ``--key ID`` | remove the borg key with this id (or unique id prefix) |
|
||||
+-------------------------------------------------------+-------------------+------------------------------------------------------------+
|
||||
| | ``--passphrase`` | remove the borg key that was used to unlock the repository |
|
||||
+-------------------------------------------------------+-------------------+------------------------------------------------------------+
|
||||
| .. class:: borg-common-opt-ref |
|
||||
| |
|
||||
| :ref:`common_options` |
|
||||
+-------------------------------------------------------+-------------------+------------------------------------------------------------+
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<script type='text/javascript'>
|
||||
$(document).ready(function () {
|
||||
$('.borg-options-table colgroup').remove();
|
||||
})
|
||||
</script>
|
||||
|
||||
.. only:: latex
|
||||
|
||||
|
||||
|
||||
options
|
||||
--label LABEL remove the borg key with this label
|
||||
--key ID remove the borg key with this id (or unique id prefix)
|
||||
--passphrase remove the borg key that was used to unlock the repository
|
||||
|
||||
|
||||
:ref:`common_options`
|
||||
|
|
||||
|
||||
Description
|
||||
~~~~~~~~~~~
|
||||
|
||||
Remove a borg key from the repository.
|
||||
|
||||
The borg key to remove is selected by exactly one of: ``--label`` (its label),
|
||||
``--key`` (its key id or a unique prefix, see ``borg key list``), or
|
||||
``--passphrase`` (remove the borg key that was used to unlock the repository now).
|
||||
|
||||
The ``admin`` borg key is protected and cannot be removed, and the last remaining
|
||||
borg key of a repository cannot be removed either.
|
||||
|
|
@ -299,6 +299,9 @@ class BuildMan:
|
|||
"key_change-location": "key",
|
||||
"key_export": "key",
|
||||
"key_import": "key",
|
||||
"key_add": "key",
|
||||
"key_list": "key",
|
||||
"key_remove": "key",
|
||||
"export-tar": "tar",
|
||||
"import-tar": "tar",
|
||||
"benchmark_crud": "benchmark",
|
||||
|
|
|
|||
Loading…
Reference in a new issue