Fully rework docs for group-accessible repositories

Just tell the user what to do instead of explaining too many details.
I've dropped the read-only variant as it actually has no representation
in the local and sftp backends. Instead it relied on both backends
initially creating all directories, which can't actually be guaranteed.

Based on a suggestion by @brad2014 in significant parts.
This commit is contained in:
Michael Eischer 2025-10-03 21:19:40 +02:00
parent 537d107b6c
commit adbd4a1d18

View file

@ -786,56 +786,45 @@ On MSYS2, you can install ``winpty`` as follows:
Group accessible repositories
*****************************
Since restic version 0.14 local and SFTP repositories can be made
accessible to members of a system group. To control this we have to change
the group permissions of the top-level ``config`` file and restic will use
this as a hint to determine what permissions to apply to newly created
files. By default ``restic init`` sets repositories up to be group
inaccessible.
Since restic version 0.14, both local and SFTP repositories can be made
accessible to all the members of a given UNIX group on the repository host.
In order to give group members read-only access we simply add the read
permission bit to all repository files with ``chmod``:
.. code-block:: console
$ find /srv/restic-repo -type f -exec chmod 440 '{}' \;
$ find /srv/restic-repo -type d -exec chmod 750 '{}' \;
This serves two purposes: 1) it sets the read permission bit on the
repository config file triggering restic's logic to create new files as
group accessible and 2) it actually allows the group read access to the
files and directories.
.. note:: By default files on Unix systems are created with a user's
primary group as defined by the gid (group id) field in
``/etc/passwd``. See `passwd(5)
<https://manpages.debian.org/latest/passwd/passwd.5.en.html>`_.
For read-write access things are a bit more complicated. When users other
than the repository creator add new files in the repository they will be
group-owned by this user's primary group by default, not that of the
original repository owner, meaning the original creator wouldn't have
access to these files. That's hardly what you'd want.
To make this work we can employ the help of the ``setgid`` permission bit
available on Linux and most other Unix systems. This permission bit makes
newly created directories or files inherit both the group owner (gid) and
setgid bit (only for directories) from the parent directory. Setting this
bit requires root but since it propagates down to any new directories we
only have to do this privileged setup once:
To permit multiple users to use a repository, first run ``restic init`` to
create it, if necessary. Then, some manual intervention is currently required.
Run the following commands over the repository files themselves, which give
the required permissions (and hints to restic). Thereafter, restic commands
can be run against that repository by any member of a given UNIX group.
To allow UNIX group ``restic-users`` to read and write to a repository at
``/srv/restic-repo``, run the following commands:
.. code-block:: console
$ chgrp -R restic-users /srv/restic-repo
$ find /srv/restic-repo -type f -exec chmod 440 '{}' \;
$ find /srv/restic-repo -type d -exec chmod 2770 '{}' \;
This sets the ``setgid`` bit on all existing directories in the repository
and then grants read/write permissions for group access.
(Internally, the group read permission on the ``config`` file tells restic to
create all future files and directories inside the repository with
group-read permission, and the ``setgid`` mode bit on directories causes
restic to set the group of each newly created file to the group of its parent
directory. They thus remain accessible to all members of group ``restic-users``,
regardless of which user created them.)
.. note:: To manage who has access to the repository you can use
``usermod`` on Linux systems, to change which group controls
repository access ``chgrp -R`` is your friend.
``usermod`` on Linux systems.
For a repository accessed via SFTP, note that the user used for the SFTP connection
should belong to the appropriate group.
.. code-block:: console
$ restic backup -r sftp:restic@repohost:/srv/restic-repo
In the example, the command could be run by the local user ``root`` who can read
all the files on the client host, and send them for backup using a remote user ``restic``
to add them to the repository. In this example, ``restic`` should be part of the
``restic-users`` group on ``repohost``.
Repositories with empty password
********************************