Stowage/restic
2
0
Fork 0
mirror of https://github.com/restic/restic.git synced 2025-12-08 06:09:56 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #5386 from Hello71/patch-2

Browse source 
doc: Add ambient caps example, edit file caps
This commit is contained in:
Alex Xu 2025-11-16 05:54:43 -05:00 • committed by GitHub
parent 71432c7f4b
commit bcc5417dc8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 39 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

65
doc/080_examples.rst
View file

@ -279,7 +279,7 @@ Motivation
Creating a complete backup of a machine requires a privileged process Creating a complete backup of a machine requires a privileged process
that is able to read all files. On UNIX-like systems this is that is able to read all files. On UNIX-like systems this is
traditionally the ``root`` user. Processes running as root have traditionally the ``root`` user. Processes running as root have
superpower. They cannot only read all files but do also have the power superpower. They can not only read all files but also have the power
to modify the system in any possible way. to modify the system in any possible way.
With great power comes great responsibility. If a process running as With great power comes great responsibility. If a process running as
@ -289,47 +289,60 @@ to run programs as root that you trust completely. And even if you
trust a program, it is good and common practice to run it with the trust a program, it is good and common practice to run it with the
least possible privileges. least possible privileges.
Capabilities on Linux
=====================
Fortunately, Linux has functionality to divide root's power into Fortunately, Linux has functionality to divide root's power into
single separate *capabilities*. You can remove these from a process single separate *capabilities*. The *CAP_DAC_READ_SEARCH* capability
running as root to restrict it. And you can add capabilities to a allows the current process to "Bypass file read permission checks and
process running as a normal user, which is what we are going to do. directory read and execute permission checks", which is what we need to
back up a system.
Full backup without root Using ambient capabilities (recommended)
======================== ========================================
To be able to completely backup a system, restic has to read all the
files. Luckily Linux knows a capability that allows precisely this. We
can assign this single capability to restic and then run it as an
unprivileged user.
First we create a new user called ``restic`` that is going to create First we create a new user called ``restic`` that is going to create
the backups: the backups:
.. code-block:: console .. code-block:: console
root@a3e580b6369d:/# useradd --system --create-home --shell /sbin/nologin restic # useradd --system --create-home --shell /sbin/nologin restic
Then we download and install the restic binary into the user's home The capability can be granted to a process tree using the
directory (please adjust the URL to refer to the latest restic version). ``setpriv`` command, which must be run as ``root`` user and then
switches to the ``restic`` user:
.. code-block:: console .. code-block:: console
root@a3e580b6369d:/# mkdir ~restic/bin # setpriv --no-new-privs --reuid=$(id -u restic) --regid=$(id -g restic) --init-groups --reset-env --inh-caps +DAC_READ_SEARCH --ambient-caps +DAC_READ_SEARCH restic backup --exclude={/dev,/media,/mnt,/proc,/run,/sys,/tmp,/var/tmp} /
root@a3e580b6369d:/# curl -L https://github.com/restic/restic/releases/download/v0.12.1/restic_0.12.1_linux_amd64.bz2 | bunzip2 > ~restic/bin/restic
Note that when using a systemd unit to run restic, you can use
``AmbientCapabilities=CAP_DAC_READ_SEARCH`` option to grant the capability to restic.
Using file capabilities
=======================
Alternatively, the capability can be granted to a file. First we
create a new user called ``restic`` that is going to create
the backups:
.. code-block:: console
# useradd --system --create-home --shell /sbin/nologin restic
Then we copy the restic binary into the user's home directory:
.. code-block:: console
# mkdir /home/restic/bin
# cp /usr/bin/restic /home/restic/bin/restic
Before we assign any special capability to the restic binary we Before we assign any special capability to the restic binary we
restrict its permissions so that only root and the newly created restrict its permissions so that only root and the newly created
restic user can execute it. Otherwise another - possibly untrusted - restic user can execute it. Otherwise any user could use the
user could misuse the privileged restic binary to circumvent file privileged restic binary to access any file.
access controls.
.. code-block:: console .. code-block:: console
root@a3e580b6369d:/# chown root:restic ~restic/bin/restic # chown root:restic /home/restic/bin/restic
root@a3e580b6369d:/# chmod 750 ~restic/bin/restic # chmod 750 /home/restic/bin/restic
Finally we can use ``setcap`` to add an extended attribute to the Finally we can use ``setcap`` to add an extended attribute to the
restic binary. On every execution the system will read the extended restic binary. On every execution the system will read the extended
@ -337,7 +350,7 @@ attribute, interpret it and assign capabilities accordingly.
.. code-block:: console .. code-block:: console
root@a3e580b6369d:/# setcap cap_dac_read_search=+ep ~restic/bin/restic # setcap cap_dac_read_search=+ep /home/restic/bin/restic
.. important:: The capabilities of the ``setcap`` command only applies to this .. important:: The capabilities of the ``setcap`` command only applies to this
specific copy of the restic binary. If you run ``restic self-update`` or specific copy of the restic binary. If you run ``restic self-update`` or
@ -351,5 +364,5 @@ system.
.. code-block:: console .. code-block:: console
root@a3e580b6369d:/# sudo -u restic /home/restic/bin/restic --exclude={/dev,/media,/mnt,/proc,/run,/sys,/tmp,/var/tmp} -r /tmp backup / # runuser -u restic /home/restic/bin/restic -r /tmp backup --exclude={/dev,/media,/mnt,/proc,/run,/sys,/tmp,/var/tmp} /