picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

man: document the new logic

This commit is contained in:
Lennart Poettering 2017-09-28 19:14:10 +02:00
parent 6c47cd7d3b
commit 4a62836033
1 changed files with 57 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
man/systemd.exec.xml
View File

@ -220,10 +220,13 @@
cannot leave files around after unit termination. Moreover <varname>ProtectSystem=strict</varname> and cannot leave files around after unit termination. Moreover <varname>ProtectSystem=strict</varname> and
<varname>ProtectHome=read-only</varname> are implied, thus prohibiting the service to write to arbitrary file <varname>ProtectHome=read-only</varname> are implied, thus prohibiting the service to write to arbitrary file
system locations. In order to allow the service to write to certain directories, they have to be whitelisted system locations. In order to allow the service to write to certain directories, they have to be whitelisted
using <varname>ReadWritePaths=</varname>, but care must be taken so that UID/GID recycling doesn't using <varname>ReadWritePaths=</varname>, but care must be taken so that UID/GID recycling doesn't create
create security issues involving files created by the service. Use <varname>RuntimeDirectory=</varname> (see security issues involving files created by the service. Use <varname>RuntimeDirectory=</varname> (see below) in
below) in order to assign a writable runtime directory to a service, owned by the dynamic user/group and order to assign a writable runtime directory to a service, owned by the dynamic user/group and removed
removed automatically when the unit is terminated. Defaults to off.</para></listitem> automatically when the unit is terminated. Use <varname>StateDirectory=</varname>,
<varname>CacheDirectory=</varname> and <varname>LogsDirectory=</varname> in order to assign a set of writable
directories for specific purposes to the service in a way that they are protected from vulnerabilities due to
UID reuse (see below). Defaults to off.</para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
@ -1753,23 +1756,58 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
<varlistentry> <varlistentry>
<term><varname>RuntimeDirectory=</varname></term> <term><varname>RuntimeDirectory=</varname></term>
<term><varname>StateDirectory=</varname></term>
<term><varname>CacheDirectory=</varname></term>
<term><varname>LogsDirectory=</varname></term>
<term><varname>ConfigurationDirectory=</varname></term>
<listitem><para>Takes a whitespace-separated list of directory names. The specified directory names must be <listitem><para>These options take a whitespace-separated list of directory names. The specified directory
relative, and may not include <literal>.</literal> or <literal>..</literal>. If set, one or more directories names must be relative, and may not include <literal>.</literal> or <literal>..</literal>. If set, one or more
including their parents by the specified names will be created below <filename>/run</filename> (for system directories by the specified names will be created (including their parents) below <filename>/run</filename>
services) or below <varname>$XDG_RUNTIME_DIR</varname> (for user services) when the unit is started. The (or <varname>$XDG_RUNTIME_DIR</varname> for user services), <filename>/var/lib</filename> (or
lowest subdirectories are removed when the unit is stopped. It is possible to preserve the directories if <varname>$XDG_CONFIG_HOME</varname> for user services), <filename>/var/cache</filename> (or
<varname>RuntimeDirectoryPreserve=</varname> is configured to <option>restart</option> or <option>yes</option>. <varname>$XDG_CACHE_HOME</varname> for user services), <filename>/var/log</filename> (or
The lowest subdirectories will have the access mode specified in <varname>RuntimeDirectoryMode=</varname>, <varname>$XDG_CONFIG_HOME</varname><filename>/log</filename> for user services), or <filename>/etc</filename>
and be owned by the user and group specified in <varname>User=</varname> and <varname>Group=</varname>. (or <varname>$XDG_CONFIG_HOME</varname> for user services), respectively, when the unit is started.</para>
This implies <varname>ReadWritePaths=</varname>, that is, the directories specified
in this option are accessible with the access mode specified in <varname>RuntimeDirectoryMode=</varname> <para>In case of <varname>RuntimeDirectory=</varname> the lowest subdirectories are removed when the unit is
even if <varname>ProtectSystem=</varname> is set to <option>strict</option>. stopped. It is possible to preserve the specified directories in this case if
Use this to manage one or more runtime directories of the unit and bind their <varname>RuntimeDirectoryPreserve=</varname> is configured to <option>restart</option> or <option>yes</option>
lifetime to the daemon runtime. This is particularly useful for unprivileged daemons that cannot create (see below). The directories specified with <varname>StateDirectory=</varname>,
<varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname>,
<varname>ConfigurationDirectory=</varname> are not removed when the unit is stopped.</para>
<para>Except in case of <varname>ConfigurationDirectory=</varname>, the innermost specified directories will be
owned by the user and group specified in <varname>User=</varname> and <varname>Group=</varname>. If the
specified directories already exist and their owning user or group do not match the configured ones, all files
and directories below the specified directories as well as the directories themselves will have their file
ownership recursively changed to match what is configured. As an optimization, if the specified directories are
already owned by the right user and group, files and directories below of them are left as-is, even if they do
not match what is requested. The innermost specified directories will have their access mode adjusted to the
what is specified in <varname>RuntimeDirectoryMode=</varname>, <varname>StateDirectoryMode=</varname>,
<varname>CacheDirectoryMode=</varname>, <varname>LogsDirectoryMode=</varname> and
<varname>ConfigurationDirectoryMode=</varname>.</para>
<para>Except in case of <varname>ConfigurationDirectory=</varname>, these options imply
<varname>ReadWritePaths=</varname> for the specified paths. When combined with
<varname>RootDirectory=</varname> or <varname>RootImage=</varname> these paths always reside on the host and
are mounted from there into the unit's file system namespace. If <varname>DynamicUser=</varname> is used in
conjunction with <varname>RuntimeDirectory=</varname>, <varname>StateDirectory=</varname>,
<varname>CacheDirectory=</varname> and <varname>LogsDirectory=</varname>, the behaviour of these options is
slightly altered: the directories are created below <filename>/run/private</filename>,
<filename>/var/lib/private</filename>, <filename>/var/cache/private</filename> and
<filename>/var/log/private</filename>, respectively, which are host directories made inaccessible to
unprivileged users, which ensures that access to these directories cannot be gained through dynamic user ID
recycling. Symbolic links are created to hide this difference in behaviour. Both from perspective of the host
and from inside the unit, the relevant directories hence always appear directly below
<filename>/run</filename>, <filename>/var/lib</filename>, <filename>/var/cache</filename> and
<filename>/var/log</filename>.</para>
<para>Use <varname>RuntimeDirectory=</varname> to manage one or more runtime directories for the unit and bind
their lifetime to the daemon runtime. This is particularly useful for unprivileged daemons that cannot create
runtime directories in <filename>/run</filename> due to lack of privileges, and to make sure the runtime runtime directories in <filename>/run</filename> due to lack of privileges, and to make sure the runtime
directory is cleaned up automatically after use. For runtime directories that require more complex or directory is cleaned up automatically after use. For runtime directories that require more complex or different
different configuration or lifetime guarantees, please consider using configuration or lifetime guarantees, please consider using
<citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<para>Example: if a system service unit has the following, <para>Example: if a system service unit has the following,
@ -1779,22 +1817,7 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
except <filename>/run/foo</filename> are owned by the user and group specified in <varname>User=</varname> and except <filename>/run/foo</filename> are owned by the user and group specified in <varname>User=</varname> and
<varname>Group=</varname>, and removed when the service is stopped. <varname>Group=</varname>, and removed when the service is stopped.
</para></listitem> </para></listitem>
</varlistentry>
<varlistentry>
<term><varname>StateDirectory=</varname></term>
<term><varname>CacheDirectory=</varname></term>
<term><varname>LogsDirectory=</varname></term>
<term><varname>ConfigurationDirectory=</varname></term>
<listitem><para>Takes a whitespace-separated list of directory names. If set, as similar to
<varname>RuntimeDirectory=</varname>, one or more directories including their parents by the specified names
will be created below <filename>/var/lib</filename>, <filename>/var/cache</filename>, <filename>/var/log</filename>,
or <filename>/etc</filename>, respectively, when the unit is started.
Unlike <varname>RuntimeDirectory=</varname>, the directories are not removed when the unit is stopped.
The lowest subdirectories will be owned by the user and group specified in <varname>User=</varname>
and <varname>Group=</varname>. The options imply <varname>ReadWritePaths=</varname>.
</para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>