From 81bacd04c581516de238689ea21886ca19bb5f19 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sun, 8 Jun 2025 13:49:09 +0200 Subject: [PATCH] docs: add docs for serve --permissions / BORG_REPO_PERMISSIONS --- docs/usage/general/environment.rst.inc | 2 ++ docs/usage/serve.rst | 6 +++++- docs/usage/serve.rst.inc | 17 ++++++++++++++++- src/borg/archiver/serve_cmd.py | 14 +++++++++++++- 4 files changed, 36 insertions(+), 3 deletions(-) diff --git a/docs/usage/general/environment.rst.inc b/docs/usage/general/environment.rst.inc index eed51a1d3..593f5ac94 100644 --- a/docs/usage/general/environment.rst.inc +++ b/docs/usage/general/environment.rst.inc @@ -62,6 +62,8 @@ General: BORG_REMOTE_PATH When set, use the given path as borg executable on the remote (defaults to "borg" if unset). Using ``--remote-path PATH`` commandline option overrides the environment variable. + BORG_REPO_PERMISSIONS + Set repository permissions, see also: :ref:`borg_serve` BORG_FILES_CACHE_SUFFIX When set to a value at least one character long, instructs borg to use a specifically named (based on the suffix) alternative files cache. This can be used to avoid loading and saving diff --git a/docs/usage/serve.rst b/docs/usage/serve.rst index acd8c876d..dcaeb6f7d 100644 --- a/docs/usage/serve.rst +++ b/docs/usage/serve.rst @@ -27,6 +27,10 @@ locations like ``/etc/environment`` or in the forced command itself (example bel $ cat ~/.ssh/authorized_keys command="borg serve --restrict-to-path /path/to/repo",restrict ssh-rsa AAAAB3[...] + # Specify repository permissions for an SSH keypair. + $ cat ~/.ssh/authorized_keys + command="borg serve --permissions=read-only",restrict ssh-rsa AAAAB3[...] + # Set a BORG_XXX environment variable on the "borg serve" side $ cat ~/.ssh/authorized_keys command="export BORG_XXX=value; borg serve [...]",restrict ssh-rsa [...] @@ -35,7 +39,7 @@ locations like ``/etc/environment`` or in the forced command itself (example bel The examples above use the ``restrict`` directive. This does automatically block potential dangerous ssh features, even when they are added in a future update. Thus, this option should be preferred. - + If you're using openssh-server < 7.2, however, you have to specify explicitly the ssh features to restrict and cannot simply use the restrict option as it has been introduced in v7.2. We recommend to use diff --git a/docs/usage/serve.rst.inc b/docs/usage/serve.rst.inc index 4d9800a6b..eadc7f32f 100644 --- a/docs/usage/serve.rst.inc +++ b/docs/usage/serve.rst.inc @@ -19,6 +19,8 @@ borg serve +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--restrict-to-repository PATH`` | restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to point directly at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. | +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--permissions`` | Set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable. | + +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | .. class:: borg-common-opt-ref | | | | :ref:`common_options` | @@ -39,6 +41,7 @@ borg serve options --restrict-to-path PATH restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to point directly to a repository. --restrict-to-repository PATH restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to point directly at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. + --permissions Set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable. :ref:`common_options` @@ -61,4 +64,16 @@ borg serve can currently support: Please note that `borg serve` does not support giving a specific repository via the `--repo` option or `BORG_REPO` environment variable. It is always the borg client which -specifies the repo to use when talking to `borg serve`. \ No newline at end of file +specifies the repo to use when talking to `borg serve`. + +The --permissions option allows enforcing repository permissions: + +- `all`: All permissions are granted (default, permissions system is not used) +- `no-delete`: Allow reading and writing, disallow deleting and overwriting data. + New archives can be created, existing archives can not be deleted. New chunks can + be added, existing chunks can not be deleted or overwritten. +- `write-only`: Allow writing, disallow reading data. + New archives can be created, existing archives can not be read. + New chunks can be added, existing chunks can not be read, deleted or overwritten. +- `read-only`: Allow reading, disallow writing or deleting data. + Existing archives can be read, but no archives can be created or deleted. \ No newline at end of file diff --git a/src/borg/archiver/serve_cmd.py b/src/borg/archiver/serve_cmd.py index a5b7e81d3..5b2cb76a8 100644 --- a/src/borg/archiver/serve_cmd.py +++ b/src/borg/archiver/serve_cmd.py @@ -38,6 +38,18 @@ class ServeMixIn: Please note that `borg serve` does not support giving a specific repository via the `--repo` option or `BORG_REPO` environment variable. It is always the borg client which specifies the repo to use when talking to `borg serve`. + + The --permissions option allows enforcing repository permissions: + + - `all`: All permissions are granted (default, permissions system is not used) + - `no-delete`: Allow reading and writing, disallow deleting and overwriting data. + New archives can be created, existing archives can not be deleted. New chunks can + be added, existing chunks can not be deleted or overwritten. + - `write-only`: Allow writing, disallow reading data. + New archives can be created, existing archives can not be read. + New chunks can be added, existing chunks can not be read, deleted or overwritten. + - `read-only`: Allow reading, disallow writing or deleting data. + Existing archives can be read, but no archives can be created or deleted. """ ) subparser = subparsers.add_parser( @@ -76,5 +88,5 @@ class ServeMixIn: "--permissions", dest="permissions", choices=["all", "no-delete", "write-only", "read-only"], - help="Set repository permission mode. Equivalent to setting BORG_REPO_PERMISSIONS environment variable.", + help="Set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable.", )