liberated-systemd/man/systemd-nsresourced.service.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

<refentry id="systemd-nsresourced.service" conditional='ENABLE_NSRESOURCED'>

  <refentryinfo>
    <title>systemd-nsresourced.service</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>systemd-nsresourced.service</refentrytitle>
    <manvolnum>8</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>systemd-nsresourced.service</refname>
    <refname>systemd-nsresourced</refname>
    <refpurpose>User Namespace Resource Delegation Service</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para><filename>systemd-nsresourced.service</filename></para>
    <para><filename>/usr/lib/systemd/systemd-nsresourced</filename></para>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><command>systemd-nsresourced</command> is a system service that permits transient delegation of a
    UID/GID range to a user namespace (see <citerefentry
    project='man-pages'><refentrytitle>user_namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
    allocated by a client, via a Varlink IPC API.</para>

    <para>Unprivileged clients may allocate a user namespace, and then request a UID/GID range to be assigned
    to it via this service. The user namespace may then be used to run containers and other sandboxes, and/or
    apply it to an id-mapped mount.</para>

    <para>Allocations of UIDs/GIDs this way are transient: when a user namespace goes away, its UID/GID range
    is returned to the pool of available ranges. In order to ensure that clients cannot gain persistency in
    their transient UID/GID range a BPF-LSM based policy is enforced that refuses to create inodes — or
    change ownership of them — that would end up owned by a transient UID/GID on a file system outliving the
    user namespace the range was assigned to. Writes to file systems the user namespace allocated itself are
    hence permitted, as those are torn down together with it, and so are writes through id-mapped mounts that
    translate the transient range into something else before it reaches the disk. As a stacking file system
    such as <literal>overlayfs</literal> writes to a separate upper layer that would not be covered by the
    checks on the overlay mount itself, mounting a writable <literal>overlayfs</literal> instance is refused
    for these user namespaces unless its upper layer, too, is torn down together with the user namespace, or
    is an id-mapped mount that translates the transient range away before it reaches the disk. The policy
    does not cover <literal>cgroupfs</literal>, whose superblock is shared system-wide and cannot be
    id-mapped: the only part of it a transient range owns is the cgroup subtree delegated to the user
    namespace (see below), which is torn down together with the user namespace, hence user namespaces may
    freely create cgroups below it.</para>

    <para><command>systemd-nsresourced</command> automatically ensures that any registered UID ranges show up
    in the system's NSS database via the <ulink url="https://systemd.io/USER_GROUP_API">User/Group Record
    Lookup API via Varlink</ulink>.</para>

    <para>Currently, only UID/GID ranges consisting of either exactly 1 or exactly 65536 UIDs/GIDs can be
    registered with this service. Moreover, UIDs and GIDs are always allocated together, and
    symmetrically.</para>

    <para>The allocation API supports <emphasis>delegated ranges</emphasis>: additional UID/GID ranges that
    are mapped 1:1 into the user namespace rather than being translated to a target UID/GID. These delegated
    ranges enable nested user namespace scenarios where a container needs to create child user namespaces
    with their own transient UID ranges. Normally, the kernel restricts which UIDs can be mapped into a user
    namespace to those that are also mapped in the parent. Delegated ranges solve this by pre-allocating
    additional ranges that are visible inside the user namespace and can be used by nested
    <function>AllocateUserRange()</function> calls. Up to 16 delegated ranges can be requested per user
    namespace, each of size 65536. The ranges are allocated from the container UID ranges as per
    <ulink url="https://systemd.io/UIDS-GIDS">Users, Groups, UIDs and GIDs on systemd Systems</ulink>.</para>

    <para>The allocation API also supports <emphasis>identity mappings</emphasis>: instead of allocating a
    transient UID/GID range, the user namespace can be configured to map the caller's UID/GID to root (UID
    0) inside the namespace, or to itself. Identity mappings can be combined with delegated ranges to enter
    a privileged user namespace from which the container can be set up after which the container can run in
    one of the delegated ranges. Identity mapped users are not subject to BPF-LSM write restrictions unlike
    the transient ranges.</para>

    <para>Additionally, the allocation API supports mapping the <emphasis>foreign UID range</emphasis> into
    the user namespace. When this option is enabled, the foreign UID range is mapped 1:1 into the user
    namespace, allowing processes inside to access and manipulate files owned by the foreign UID range.</para>

    <para>The service provides API calls to delegate mounts (referenced via their mount file descriptors as
    per Linux <function>fsmount()</function> API), to pass ownership of a cgroup subtree to the user
    namespace and to delegate a virtual Ethernet device pair to the user namespace. When used in combination
    this is sufficient to implement fully unprivileged container environments, as implemented by
    <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, fully
    unprivileged <varname>RootImage=</varname> (see
    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>) or
    fully unprivileged disk image tools such as
    <citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>

    <para>This service provides one <ulink url="https://varlink.org/">Varlink</ulink> service:
    <constant>io.systemd.NamespaceResource</constant> allows registering user namespaces, and assign mounts,
    cgroups and network interfaces to it.</para>

    <para>Note that combining usage of <command>systemd-nsresourced</command> and systems based on
    <filename>/etc/subuid</filename> and <filename>/etc/subgid</filename> might result in undefined
    behavior if UID or GID ranges defined in those files overlap with the UID or GID ranges used by
    nsresourced (the foreign UID range).</para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para><simplelist type="inline">
      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-mountfsd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry project='man-pages'><refentrytitle>user_namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
    </simplelist></para>
  </refsect1>
</refentry>