Skip to content

docs: add docs for "key add", "key list" and "key remove" #9769

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ThomasWaldmann merged 1 commit into from
Jun 13, 2026
Merged

docs: add docs for "key add", "key list" and "key remove" #9769

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions docs/man/borg-key-add.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 changes: 50 additions & 0 deletions docs/man/borg-key-list.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 changes: 67 additions & 0 deletions docs/man/borg-key-remove.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
7 changes: 5 additions & 2 deletions docs/man/borg-key.1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,20 +28,23 @@ 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
.nf
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.
6 changes: 6 additions & 0 deletions docs/usage/key.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 59 additions & 0 deletions docs/usage/key_add.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 changes: 41 additions & 0 deletions docs/usage/key_list.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 changes: 60 additions & 0 deletions docs/usage/key_remove.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 3 additions & 0 deletions scripts/make.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
Loading