SYSTEMD-NS...D.SERVICE(8)

this is the SYSTEMD-NS...D.SERVICE(8) page, aka the systemd-nsresourced.service manual, and bestie, it's literally all about user namespace resource delegation — no cap 💅

✨ NAME ✨

systemd-nsresourced.service, systemd-nsresourced — User Namespace Resource Delegation Service

🌸 SYNOPSIS 🌸

systemd-nsresourced.service
/usr/lib/systemd/systemd-nsresourced

💖 DESCRIPTION 💖

okay so systemd-nsresourced is a system service, and its whole thing is permitting transient delegation of a UID/GID range to a user namespace (peep user_namespaces(7)) that a client allocated, all via a Varlink IPC API. slay.

Unprivileged clients may allocate a user namespace, and then request a UID/GID range to be assigned to it via this service. after that? the user namespace may then be used to run containers and other sandboxes, and/or apply it to an id-mapped mount. iconic.

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. and to make sure clients cannot gain persistency in their transient UID/GID range, a BPF-LSM based policy is enforced that ensures user namespaces set up this way can only write to file systems they allocate themselves or that are explicitly allowlisted via systemd-nsresourced. so yeah, no sneaky permanent vibes 🫶

systemd-nsresourced automatically ensures that any registered UID ranges show up in the system's NSS database via the User/Group Record Lookup API via Varlink[1]. literally making sure everyone gets seen 💫

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. cute little pairings, periodt.

the allocation API supports delegated ranges: 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 AllocateUserRange() 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 Users, Groups, UIDs and GIDs on systemd Systems[2]. nesting slay ✨

the allocation API also supports identity mappings: 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. main character privilege energy, honestly 👑

additionally, the allocation API supports mapping the foreign UID range 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. giving them the keys to the right files 🗝️

the service provides API calls to allowlist mounts (referenced via their mount file descriptors as per Linux fsmount() 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 systemd-nspawn(1), fully unprivileged RootImage= (see systemd.exec(5)) or fully unprivileged disk image tools such as systemd-dissect(1). it's giving full unprivileged container fantasy 🔥

this service provides one Varlink[3] service: io.systemd.NamespaceResource allows registering user namespaces, and assign mounts, cgroups and network interfaces to it. one service, lots of delegation, we love to see it 🌈

note bestie: combining usage of systemd-nsresourced and systems based on /etc/subuid and /etc/subgid 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). so like… check your ranges before you wreck your ranges 😭

🔥 SEE ALSO 🔥

systemd(1), systemd-mountfsd.service(8), systemd-nspawn(1), systemd.exec(5), systemd-dissect(1), user_namespaces(7)

🎀 NOTES 🎀

1. User/Group Record Lookup API via Varlink — https://systemd.io/USER_GROUP_API
2. Users, Groups, UIDs and GIDs on systemd Systems — https://systemd.io/UIDS-GIDS
3. Varlink — https://varlink.org/

---

and that's the whole page, sourced from systemd 261.3 — version vibes only, bestie 💖🦋