| 1 |
'\" t |
| 2 |
.TH "SYSTEMD\-NSRESOURCED\&.SERVICE" "8" "" "systemd 261~rc3" "systemd-nsresourced.service" |
| 3 |
.\" ----------------------------------------------------------------- |
| 4 |
.\" * Define some portability stuff |
| 5 |
.\" ----------------------------------------------------------------- |
| 6 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 7 |
.\" http://bugs.debian.org/507673 |
| 8 |
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| 9 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 10 |
.ie \n(.g .ds Aq \(aq |
| 11 |
.el .ds Aq ' |
| 12 |
.\" ----------------------------------------------------------------- |
| 13 |
.\" * set default formatting |
| 14 |
.\" ----------------------------------------------------------------- |
| 15 |
.\" disable hyphenation |
| 16 |
.nh |
| 17 |
.\" disable justification (adjust text to left margin only) |
| 18 |
.ad l |
| 19 |
.\" ----------------------------------------------------------------- |
| 20 |
.\" * MAIN CONTENT STARTS HERE * |
| 21 |
.\" ----------------------------------------------------------------- |
| 22 |
.SH "NAME" |
| 23 |
systemd-nsresourced.service, systemd-nsresourced \- User Namespace Resource Delegation Service |
| 24 |
.SH "SYNOPSIS" |
| 25 |
.PP |
| 26 |
systemd\-nsresourced\&.service |
| 27 |
.PP |
| 28 |
/usr/lib/systemd/systemd\-nsresourced |
| 29 |
.SH "DESCRIPTION" |
| 30 |
.PP |
| 31 |
\fBsystemd\-nsresourced\fR |
| 32 |
is a system service that permits transient delegation of a UID/GID range to a user namespace (see |
| 33 |
\fBuser_namespaces\fR(7)) allocated by a client, via a Varlink IPC API\&. |
| 34 |
.PP |
| 35 |
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\&. |
| 36 |
.PP |
| 37 |
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 ensures that user namespaces set up this way can only write to file systems they allocate themselves or that are explicitly allowlisted via |
| 38 |
\fBsystemd\-nsresourced\fR\&. |
| 39 |
.PP |
| 40 |
\fBsystemd\-nsresourced\fR |
| 41 |
automatically ensures that any registered UID ranges show up in the system\*(Aqs NSS database via the |
| 42 |
\m[blue]\fBUser/Group Record Lookup API via Varlink\fR\m[]\&\s-2\u[1]\d\s+2\&. |
| 43 |
.PP |
| 44 |
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\&. |
| 45 |
.PP |
| 46 |
The allocation API supports |
| 47 |
\fIdelegated ranges\fR: 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 |
| 48 |
\fBAllocateUserRange()\fR |
| 49 |
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 |
| 50 |
\m[blue]\fBUsers, Groups, UIDs and GIDs on systemd Systems\fR\m[]\&\s-2\u[2]\d\s+2\&. |
| 51 |
.PP |
| 52 |
The allocation API also supports |
| 53 |
\fIidentity mappings\fR: instead of allocating a transient UID/GID range, the user namespace can be configured to map the caller\*(Aqs 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\&. |
| 54 |
.PP |
| 55 |
Additionally, the allocation API supports mapping the |
| 56 |
\fIforeign UID range\fR |
| 57 |
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\&. |
| 58 |
.PP |
| 59 |
The service provides API calls to allowlist mounts (referenced via their mount file descriptors as per Linux |
| 60 |
\fBfsmount()\fR |
| 61 |
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 |
| 62 |
\fBsystemd-nspawn\fR(1), fully unprivileged |
| 63 |
\fIRootImage=\fR |
| 64 |
(see |
| 65 |
\fBsystemd.exec\fR(5)) or fully unprivileged disk image tools such as |
| 66 |
\fBsystemd-dissect\fR(1)\&. |
| 67 |
.PP |
| 68 |
This service provides one |
| 69 |
\m[blue]\fBVarlink\fR\m[]\&\s-2\u[3]\d\s+2 |
| 70 |
service: |
| 71 |
\fBio\&.systemd\&.NamespaceResource\fR |
| 72 |
allows registering user namespaces, and assign mounts, cgroups and network interfaces to it\&. |
| 73 |
.SH "SEE ALSO" |
| 74 |
.PP |
| 75 |
\fBsystemd\fR(1), \fBsystemd-mountfsd.service\fR(8), \fBsystemd-nspawn\fR(1), \fBsystemd.exec\fR(5), \fBsystemd-dissect\fR(1), \fBuser_namespaces\fR(7) |
| 76 |
.SH "NOTES" |
| 77 |
.IP " 1." 4 |
| 78 |
User/Group Record Lookup API via Varlink |
| 79 |
.RS 4 |
| 80 |
\%https://systemd.io/USER_GROUP_API |
| 81 |
.RE |
| 82 |
.IP " 2." 4 |
| 83 |
Users, Groups, UIDs and GIDs on systemd Systems |
| 84 |
.RS 4 |
| 85 |
\%https://systemd.io/UIDS-GIDS |
| 86 |
.RE |
| 87 |
.IP " 3." 4 |
| 88 |
Varlink |
| 89 |
.RS 4 |
| 90 |
\%https://varlink.org/ |
| 91 |
.RE |