docs: add docs for serve --permissions / BORG_REPO_PERMISSIONS

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

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

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`.
+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.

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.",
         )