From a06c9ac27782f21cd0eaf4078f4588b4f8cd2585 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 7 May 2021 11:44:26 +0200 Subject: [PATCH] man: document new nspawn --bind-user= feature --- docs/UIDS-GIDS.md | 5 ++-- man/systemd-nspawn.xml | 52 ++++++++++++++++++++++++++++++++++++++++++ man/systemd.nspawn.xml | 10 ++++++++ 3 files changed, 65 insertions(+), 2 deletions(-) diff --git a/docs/UIDS-GIDS.md b/docs/UIDS-GIDS.md index e289a9b68e..5342ccd166 100644 --- a/docs/UIDS-GIDS.md +++ b/docs/UIDS-GIDS.md @@ -241,8 +241,9 @@ the artifacts the container manager persistently leaves in the system. | 5 | `tty` group | `systemd` | `/etc/passwd` | | 6…999 | System users | Distributions | `/etc/passwd` | | 1000…60000 | Regular users | Distributions | `/etc/passwd` + LDAP/NIS/… | -| 60001…60513 | Human Users (homed) | `systemd` | `nss-systemd` | -| 60514…61183 | Unused | | | +| 60001…60513 | Human users (homed) | `systemd` | `nss-systemd` | +| 60514…60577 | Host users mapped into containers | `systemd` | `systemd-nspawn` | +| 60578…61183 | Unused | | | | 61184…65519 | Dynamic service users | `systemd` | `nss-systemd` | | 65520…65533 | Unused | | | | 65534 | `nobody` user | Linux | `/etc/passwd` + `nss-systemd` | diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 403636545a..e929d32f62 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1352,6 +1352,58 @@ After=sys-subsystem-net-devices-ens1.device make them read-only, using . + + + + Binds the home directory of the specified user on the host into the container. Takes + the name of an existing user on the host as argument. May be used multiple times to bind multiple + users into the container. This does three things: + + + The user's home directory is bind mounted from the host into + /run/hosts/home/. + + An additional UID/GID mapping is added that maps the host user's UID/GID to a + container UID/GID, allocated from the 60514…60577 range. + + A JSON user and group record is generated in /run/userdb/ that + describes the mapped user. It contains a minimized representation of the host's user record, + adjusted to the UID/GID and home directory path assigned to the user in the container. The + nss-systemd8 + glibc NSS module will pick up these records from there and make them available in the container's + user/group databases. + + + The combination of the three operations above ensures that it is possible to log into the + host's user account inside the container as if it was local to the container. The user is only mapped + transiently, while the container is running and the mapping itself does not result in persistent + changes to the container (except maybe for generated log messages at login time, and similar). Note + that in particular the UID/GID assignment in the container is not made persistently. If the user is + mapped transiently, it is best to not allow the user to make persistent changes to the container. If + the user leaves files or directories owned by the user, and those UIDs/GIDs are recycled during later + container invocations (possibly with a different mapping), those files + and directories will be accessible to the "new" user. + + The user/group record mapping only works if the container contains systemd 249 or newer, with + nss-systemd properly configured in nsswitch.conf. See + nss-systemd8 for + details. + + Note that the user record propagated from the host into the container will contain the UNIX + password hash of the user, so that seamless logins in the container are possible. If the container is + less trusted than the host it's hence important to use a strong UNIX password hash function + (e.g. yescrypt or similar, with the $y$ hash prefix). + + When binding a user from the host into the container checks are executed to ensure that the + username is not yet known in the container. Moreover, it is checked that the UID/GID allocated for it + is not currently defined in the user/group databases of the container. Both checks directly access + the container's /etc/passwd and /etc/group, and thus might + not detect existing accounts in other databases. + + This operation is only supported in combination with + /. + + diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml index 186616b6ad..7ba8e361b4 100644 --- a/man/systemd.nspawn.xml +++ b/man/systemd.nspawn.xml @@ -415,6 +415,16 @@ is privileged (see above). + + BindUser= + + Binds a user from the host into the container. This option is equivalent to the + command line switch , see + systemd-nspawn1 + for details about the specific options supported. This setting is privileged (see + above). + + TemporaryFileSystem=