]>
Commit | Line | Data |
---|---|---|
8aee931e LP |
1 | <?xml version='1.0'?> <!--*-nxml-*--> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> | |
5 | ||
6 | <refentry id="systemd-nsresourced.service" conditional='ENABLE_NSRESOURCED'> | |
7 | ||
8 | <refentryinfo> | |
9 | <title>systemd-nsresourced.service</title> | |
10 | <productname>systemd</productname> | |
11 | </refentryinfo> | |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>systemd-nsresourced.service</refentrytitle> | |
15 | <manvolnum>8</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>systemd-nsresourced.service</refname> | |
20 | <refname>systemd-nsresourced</refname> | |
21 | <refpurpose>User Namespace Resource Delegation Service</refpurpose> | |
22 | </refnamediv> | |
23 | ||
24 | <refsynopsisdiv> | |
25 | <para><filename>systemd-nsresourced.service</filename></para> | |
26 | <para><filename>/usr/lib/systemd/systemd-nsresourced</filename></para> | |
27 | </refsynopsisdiv> | |
28 | ||
29 | <refsect1> | |
30 | <title>Description</title> | |
31 | ||
32 | <para><command>systemd-nsresourced</command> is a system service that permits transient delegation of a a | |
33 | UID/GID range to a user namespace (see <citerefentry | |
34 | project='man-pages'><refentrytitle>user_namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>) | |
35 | allocated by a client, via a Varlink IPC API.</para> | |
36 | ||
37 | <para>Unprivileged clients may allocate a user namespace, and then request a UID/GID range to be assigned | |
38 | to it via this service. The user namespace may then be used to run containers and other sandboxes, and/or | |
39 | apply it to an id-mapped mount.</para> | |
40 | ||
41 | <para>Allocations of UIDs/GIDs this way are transient: when a user namespace goes away, its UID/GID range | |
42 | is returned to the pool of available ranges. In order to ensure that clients cannot gain persistency in | |
43 | their transient UID/GID range a BPF-LSM based policy is enforced that ensures that user namespaces set up | |
44 | this way can only write to file systems they allocate themselves or that are explicitly allowlisted via | |
45 | <command>systemd-nsresourced</command>.</para> | |
46 | ||
47 | <para><command>systemd-nsresourced</command> automatically ensures that any registered UID ranges show up | |
48 | in the system's NSS database via the <ulink url="https://systemd.io/USER_GROUP_API">User/Group Record | |
49 | Lookup API via Varlink</ulink>.</para> | |
50 | ||
51 | <para>Currently, only UID/GID ranges consisting of either exactly 1 or exactly 65536 UIDs/GIDs can be | |
52 | registered with this service. Moreover, UIDs and GIDs are always allocated together, and | |
53 | symmetrically.</para> | |
54 | ||
55 | <para>The service provides API calls to allowlist mounts (referenced via their mount file descriptors as | |
56 | per Linux <function>fsmount()</function> API), to pass ownership of a cgroup subtree to the user | |
57 | namespace and to delegate a virtual Ethernet device pair to the user namespace. When used in combination | |
58 | this is sufficient to implement fully unprivileged container environments, as implemented by | |
59 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, fully | |
60 | unprivileged <varname>RootImage=</varname> (see | |
61 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>) or | |
62 | fully unprivileged disk image tools such as | |
63 | <citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> | |
64 | ||
65 | <para>This service provides one <ulink url="https://varlink.org/">Varlink</ulink> service: | |
66 | <constant>io.systemd.NamespaceResource</constant> allows registering user namespaces, and assign mounts, | |
67 | cgroups and network interfaces to it.</para> | |
68 | </refsect1> | |
69 | ||
70 | <refsect1> | |
71 | <title>See Also</title> | |
72 | <para> | |
73 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
74 | <citerefentry><refentrytitle>systemd-mountfsd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
75 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
76 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
77 | <citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
78 | <citerefentry project='man-pages'><refentrytitle>user_namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
79 | </para> | |
80 | </refsect1> | |
81 | </refentry> |