From 2f2e14b251b9929e84e8b690d0187b766dfbae20 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 1 Jun 2018 11:23:51 +0200 Subject: [PATCH] man: document the new PrivateMounts= setting Also, extend the documentation on MountFlags= substantially, hopefully addressing all the questions of #4393 Fixes: #4393 --- man/systemd.exec.xml | 79 +++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 60 insertions(+), 19 deletions(-) diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 2e01326..de4c53c 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -1278,27 +1278,68 @@ RestrictNamespaces=~cgroup net + PrivateMounts= + + Takes a boolean parameter. If set, the processes of this unit will be run in their own private + file system (mount) namespace with all mount propagation from the processes towards the host's main file system + namespace turned off. This means any file system mount points established or removed by the unit's processes + will be private to them and not be visible to the host. However, file system mount points established or + removed on the host will be propagated to the unit's processes. See mount_namespaces7 for + details on file system namespaces. Defaults to off. + + When turned on, this executes three operations for each invoked process: a new + CLONE_NEWNS namespace is created, after which all existing mounts are remounted to + MS_SLAVE to disable propagation from the unit's processes to the host (but leaving + propagation in the opposite direction in effect). Finally, the mounts are remounted again to the propagation + mode configured with MountFlags=, see below. + + File system namespaces are set up individually for each process forked off by the service manager. Mounts + established in the namespace of the process created by ExecStartPre= will hence be cleaned + up automatically as soon as that process exits and will not be available to subsequent processes forked off for + ExecStart= (and similar applies to the various other commands configured for + units). Similarly, JoinsNamespaceOf= does not permit sharing kernel mount namespaces between + units, it only enables sharing of the /tmp/ and /var/tmp/ + directories. + + Other file system namespace unit settings — PrivateMounts=, + PrivateTmp=, PrivateDevices=, ProtectSystem=, + ProtectHome=, ReadOnlyPaths=, InaccessiblePaths=, + ReadWritePaths=, … — also enable file system namespacing in a fashion equivalent to this + option. Hence it is primarily useful to explicitly request this behaviour if none of the other settings are + used. + + + MountFlags= - Takes a mount propagation flag: , or - , which control whether mounts in the file system namespace set up for this unit's - processes will receive or propagate mounts and unmounts. See mount2 for - details. Defaults to . Use to ensure that mounts and unmounts - are propagated from systemd's namespace to the service's namespace and vice versa. Use - to run processes so that none of their mounts and unmounts will propagate to the host. Use - to also ensure that no mounts and unmounts from the host will propagate into the unit - processes' namespace. If this is set to or , any mounts created - by spawned processes will be unmounted after the completion of the current command line of - ExecStartPre=, ExecStartPost=, ExecStart=, and - ExecStopPost=. Note that means that file systems mounted on the host - might stay mounted continuously in the unit's namespace, and thus keep the device busy. Note that the file - system namespace related options (PrivateTmp=, PrivateDevices=, - ProtectSystem=, ProtectHome=, ProtectKernelTunables=, - ProtectControlGroups=, ReadOnlyPaths=, - InaccessiblePaths=, ReadWritePaths=) require that mount and unmount - propagation from the unit's file system namespace is disabled, and hence downgrade to - . + Takes a mount propagation setting: , or + , which controls whether file system mount points in the file system namespaces set up + for this unit's processes will receive or propagate mounts and unmounts from other file system namespaces. See + mount2 + for details on mount propagation, and the three propagation flags in particular. + + This setting only controls the final propagation setting in effect on all mount + points of the file system namespace created for each process of this unit. Other file system namespacing unit + settings (see the discussion in PrivateMounts= above) will implicitly disable mount and + unmount propagation from the unit's processes towards the host by changing the propagation setting of all mount + points in the unit's file system namepace to first. Setting this option to + does not reestablish propagation in that case. Conversely, if this option is set, but + no other file system namespace setting is used, then new file system namespaces will be created for the unit's + processes and this propagation flag will be applied right away to all mounts within it, without the + intermediary application of . + + If not set – but file system namespaces are enabled through another file system namespace unit setting – + mount propagation is used, but — as mentioned — as is applied + first, propagation from the unit's processes to the host is still turned off. + + It is not recommended to to use mount propagation for units, as this means + temporary mounts (such as removable media) of the host will stay mounted and thus indefinitely busy in forked + off processes, as unmount propagation events won't be received by the file system namespace of the unit. + + Usually, it is best to leave this setting unmodified, and use higher level file system namespacing + options instead, in particular PrivateMounts=, see above. + -- 2.7.4