diff --git a/docs/man/borg-key-add.1 b/docs/man/borg-key-add.1 new file mode 100644 index 0000000000..98bccec3d6 --- /dev/null +++ b/docs/man/borg-key-add.1 @@ -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. diff --git a/docs/man/borg-key-list.1 b/docs/man/borg-key-list.1 new file mode 100644 index 0000000000..5c29f9ddb8 --- /dev/null +++ b/docs/man/borg-key-list.1 @@ -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. diff --git a/docs/man/borg-key-remove.1 b/docs/man/borg-key-remove.1 new file mode 100644 index 0000000000..d99f4f9f64 --- /dev/null +++ b/docs/man/borg-key-remove.1 @@ -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. diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index d2d8ba66b9..60c4a7705f 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -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. diff --git a/docs/usage/key.rst b/docs/usage/key.rst index e9c47b6d20..b70b1feab0 100644 --- a/docs/usage/key.rst +++ b/docs/usage/key.rst @@ -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 diff --git a/docs/usage/key_add.rst.inc b/docs/usage/key_add.rst.inc new file mode 100644 index 0000000000..8e1f0b23ec --- /dev/null +++ b/docs/usage/key_add.rst.inc @@ -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 + + + +.. 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``. \ No newline at end of file diff --git a/docs/usage/key_list.rst.inc b/docs/usage/key_list.rst.inc new file mode 100644 index 0000000000..23b87ba90c --- /dev/null +++ b/docs/usage/key_list.rst.inc @@ -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 + + + +.. 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 ``*``. \ No newline at end of file diff --git a/docs/usage/key_remove.rst.inc b/docs/usage/key_remove.rst.inc new file mode 100644 index 0000000000..fa46083f8f --- /dev/null +++ b/docs/usage/key_remove.rst.inc @@ -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 + + + +.. 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. \ No newline at end of file diff --git a/scripts/make.py b/scripts/make.py index d1e52613f8..07a32ed653 100644 --- a/scripts/make.py +++ b/scripts/make.py @@ -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",