upstream/borgbackup
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-05-28 04:03:21 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge pull request #8906 from ThomasWaldmann/permissions-docs

Browse source 
docs: add docs for serve --permissions / BORG_REPO_PERMISSIONS
This commit is contained in:
TW 2025-06-08 14:01:58 +02:00 committed by GitHub
commit 9dc18e3707
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 36 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/usage/general/environment.rst.inc
View file

@ -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

6
docs/usage/serve.rst
View file

@ -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

17
docs/usage/serve.rst.inc
View file

@ -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.

14
src/borg/archiver/serve_cmd.py
View file

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