Merge pull request #3884 from poettering/private-users

1 files changed, 40 insertions, 25 deletions

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 0fc658f180..2495998295 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -107,36 +107,29 @@
       <varlistentry>
         <term><varname>WorkingDirectory=</varname></term>
 
-        <listitem><para>Takes a directory path relative to the service's root
-        directory specified by <varname>RootDirectory=</varname>, or the
-        special value <literal>~</literal>. Sets the working directory
-        for executed processes. If set to <literal>~</literal>, the
-        home directory of the user specified in
-        <varname>User=</varname> is used. If not set, defaults to the
-        root directory when systemd is running as a system instance
-        and the respective user's home directory if run as user. If
-        the setting is prefixed with the <literal>-</literal>
-        character, a missing working directory is not considered
-        fatal. If <varname>RootDirectory=</varname> is not set, then
-        <varname>WorkingDirectory=</varname> is relative to the root of
-        the system running the service manager.
-        Note that setting this parameter might result in
-        additional dependencies to be added to the unit (see
-        above).</para></listitem>
+        <listitem><para>Takes a directory path relative to the service's root directory specified by
+        <varname>RootDirectory=</varname>, or the special value <literal>~</literal>. Sets the working directory for
+        executed processes. If set to <literal>~</literal>, the home directory of the user specified in
+        <varname>User=</varname> is used. If not set, defaults to the root directory when systemd is running as a
+        system instance and the respective user's home directory if run as user. If the setting is prefixed with the
+        <literal>-</literal> character, a missing working directory is not considered fatal. If
+        <varname>RootDirectory=</varname> is not set, then <varname>WorkingDirectory=</varname> is relative to the root
+        of the system running the service manager.  Note that setting this parameter might result in additional
+        dependencies to be added to the unit (see above).</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><varname>RootDirectory=</varname></term>
 
-        <listitem><para>Takes a directory path relative to the host's root directory
-        (i.e. the root of the system running the service manager). Sets the
-        root directory for executed processes, with the <citerefentry
-        project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
-        system call. If this is used, it must be ensured that the
-        process binary and all its auxiliary files are available in
-        the <function>chroot()</function> jail. Note that setting this
-        parameter might result in additional dependencies to be added
-        to the unit (see above).</para></listitem>
+        <listitem><para>Takes a directory path relative to the host's root directory (i.e. the root of the system
+        running the service manager). Sets the root directory for executed processes, with the <citerefentry
+        project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system
+        call. If this is used, it must be ensured that the process binary and all its auxiliary files are available in
+        the <function>chroot()</function> jail. Note that setting this parameter might result in additional
+        dependencies to be added to the unit (see above).</para>
+
+        <para>The <varname>PrivateUsers=</varname> setting is particularly useful in conjunction with
+        <varname>RootDirectory=</varname>. For details, see below.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -999,6 +992,28 @@
       </varlistentry>
 
       <varlistentry>
+        <term><varname>PrivateUsers=</varname></term>
+
+        <listitem><para>Takes a boolean argument. If true, sets up a new user namespace for the executed processes and
+        configures a minimal user and group mapping, that maps the <literal>root</literal> user and group as well as
+        the unit's own user and group to themselves and everything else to the <literal>nobody</literal> user and
+        group. This is useful to securely detach the user and group databases used by the unit from the rest of the
+        system, and thus to create an effective sandbox environment. All files, directories, processes, IPC objects and
+        other resources owned by users/groups not equalling <literal>root</literal> or the unit's own will stay visible
+        from within the unit but appear owned by the <literal>nobody</literal> user and group. If this mode is enabled,
+        all unit processes are run without privileges in the host user namespace (regardless if the unit's own
+        user/group is <literal>root</literal> or not). Specifically this means that the process will have zero process
+        capabilities on the host's user namespace, but full capabilities within the service's user namespace. Settings
+        such as <varname>CapabilityBoundingSet=</varname> will affect only the latter, and there's no way to acquire
+        additional capabilities in the host's user namespace. Defaults to off.</para>
+
+        <para>This setting is particularly useful in conjunction with <varname>RootDirectory=</varname>, as the need to
+        synchronize the user and group databases in the root directory and on the host is reduced, as the only users
+        and groups who need to be matched are <literal>root</literal>, <literal>nobody</literal> and the unit's own
+        user and group.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><varname>ProtectSystem=</varname></term>
 
         <listitem><para>Takes a boolean argument or