<refsect1>
<title>Mandatory Access Control</title>
- <variablelist>
+ <variablelist class='unit-directives'>
<varlistentry>
<term><varname>SELinuxContext=</varname></term>
<refsect1>
<title>Process Properties</title>
- <variablelist>
+ <variablelist class='unit-directives'>
<varlistentry>
<term><varname>LimitCPU=</varname></term>
<refsect1>
<title>Scheduling</title>
- <variablelist>
+ <variablelist class='unit-directives'>
<varlistentry>
<term><varname>Nice=</varname></term>
<refsect1>
<title>Sandboxing</title>
- <variablelist>
+ <para>The following sandboxing options are an effective way to limit the exposure of the system towards the unit's
+ processes. It is recommended to turn on as many of these options for each unit as is possible without negatively
+ affecting the process' ability to operate. Note that many of these sandboxing features are gracefully turned off on
+ systems where the underlying security mechanism is not available. For example, <varname>ProtectSystem=</varname>
+ has no effect if the kernel is built without file system namespacing or if the service manager runs in a container
+ manager that makes file system namespacing unavailable to its payload. Similar,
+ <varname>RestrictRealtime=</varname> has no effect on systems that lack support for SECCOMP system call filtering,
+ or in containers where support for this is turned off.</para>
+
+ <para>Also note that some sandboxing functionality is generally not available in user services (i.e. services run
+ by the per-user service manager). Specifically, the various settings requiring file system namespacing support
+ (such as <varname>ProtectSystem=</varname>) are not available, as the underlying kernel functionality is only
+ accessible to privileged processes.</para>
+
+ <variablelist class='unit-directives'>
<varlistentry>
<term><varname>ProtectSystem=</varname></term>
recommended to enable this setting for all long-running services, unless they are involved with system updates
or need to modify the operating system in other ways. If this option is used,
<varname>ReadWritePaths=</varname> may be used to exclude specific directories from being made read-only. This
- setting is implied if <varname>DynamicUser=</varname> is set. For this setting the same restrictions regarding
- mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see
- below. Defaults to off.</para></listitem>
+ setting is implied if <varname>DynamicUser=</varname> is set. This setting cannot ensure protection in all
+ cases. In general it has the same limitations as <varname>ReadOnlyPaths=</varname>, see below. Defaults to
+ off.</para></listitem>
</varlistentry>
<varlistentry>
<varname>ReadOnlyPaths=</varname>, and <literal>tmpfs</literal> is mostly equivalent to
<varname>TemporaryFileSystem=</varname>.</para>
- <para> It is recommended to enable this setting for all long-running services (in particular network-facing ones),
- to ensure they cannot get access to private user data, unless the services actually require access to the user's
- private data. This setting is implied if <varname>DynamicUser=</varname> is set. For this setting the same
- restrictions regarding mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related
- calls, see below.</para></listitem>
+ <para> It is recommended to enable this setting for all long-running services (in particular network-facing
+ ones), to ensure they cannot get access to private user data, unless the services actually require access to
+ the user's private data. This setting is implied if <varname>DynamicUser=</varname> is set. This setting cannot
+ ensure protection in all cases. In general it has the same limitations as <varname>ReadOnlyPaths=</varname>,
+ see below.</para></listitem>
</varlistentry>
<varlistentry>
<listitem><para>These options take a whitespace-separated list of directory names. The specified directory
names must be relative, and may not include <literal>..</literal>. If set, one or more
directories by the specified names will be created (including their parents) below the locations
- defined in the following table, when the unit is started.</para>
+ defined in the following table, when the unit is started. Also, the corresponding environment variable
+ is defined with the full path of directories. If multiple directories are set, then in the environment variable
+ the paths are concatenated with colon (<literal>:</literal>).</para>
<table>
- <title>Automatic directory creation</title>
- <tgroup cols='3'>
+ <title>Automatic directory creation and environment variables</title>
+ <tgroup cols='4'>
<thead>
<row>
<entry>Locations</entry>
<entry>for system</entry>
<entry>for users</entry>
+ <entry>Environment variable</entry>
</row>
</thead>
<tbody>
<entry><varname>RuntimeDirectory=</varname></entry>
<entry><filename>/run</filename></entry>
<entry><varname>$XDG_RUNTIME_DIR</varname></entry>
+ <entry><varname>$RUNTIME_DIRECTORY</varname></entry>
</row>
<row>
<entry><varname>StateDirectory=</varname></entry>
<entry><filename>/var/lib</filename></entry>
<entry><varname>$XDG_CONFIG_HOME</varname></entry>
+ <entry><varname>$STATE_DIRECTORY</varname></entry>
</row>
<row>
<entry><varname>CacheDirectory=</varname></entry>
<entry><filename>/var/cache</filename></entry>
<entry><varname>$XDG_CACHE_HOME</varname></entry>
+ <entry><varname>$CACHE_DIRECTORY</varname></entry>
</row>
<row>
<entry><varname>LogsDirectory=</varname></entry>
<entry><filename>/var/log</filename></entry>
<entry><varname>$XDG_CONFIG_HOME</varname><filename>/log</filename></entry>
+ <entry><varname>$LOGS_DIRECTORY</varname></entry>
</row>
<row>
<entry><varname>ConfigurationDirectory=</varname></entry>
<entry><filename>/etc</filename></entry>
<entry><varname>$XDG_CONFIG_HOME</varname></entry>
+ <entry><varname>$CONFIGURATION_DIRECTORY</varname></entry>
</row>
</tbody>
</tgroup>
<filename>/run/foo/bar</filename>, and <filename>/run/baz</filename>. The directories
<filename>/run/foo/bar</filename> and <filename>/run/baz</filename> 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.</para></listitem>
+ when the service is stopped.</para>
+
+ <para>Example: if a system service unit has the following,
+ <programlisting>RuntimeDirectory=foo/bar
+StateDirectory=aaa/bbb ccc</programlisting>
+ then the environment variable <literal>RUNTIME_DIRECTORY</literal> is set with <literal>/run/foo/bar</literal>, and
+ <literal>STATE_DIRECTORY</literal> is set with <literal>/var/lib/aaa/bbb:/var/lib/ccc</literal>.</para></listitem>
</varlistentry>
<varlistentry>
<varname>BindPaths=</varname>, or <varname>BindReadOnlyPaths=</varname> inside it. For a more flexible option,
see <varname>TemporaryFileSystem=</varname>.</para>
- <para>Note that restricting access with these options does not extend to submounts of a directory that are
- created later on. Non-directory paths may be specified as well. These options may be specified more than once,
+ <para>Non-directory paths may be specified as well. These options may be specified more than once,
in which case all paths listed will have limited access from within the namespace. If the empty string is
assigned to this option, the specific list is reset, and all prior assignments have no effect.</para>
<literal>+</literal> on the same path make sure to specify <literal>-</literal> first, and <literal>+</literal>
second.</para>
- <para>Note that using this setting will disconnect propagation of mounts from the service to the host
- (propagation in the opposite direction continues to work). This means that this setting may not be used for
- services which shall be able to install mount points in the main mount namespace. Note that the effect of these
- settings may be undone by privileged processes. In order to set up an effective sandboxed environment for a
- unit it is thus recommended to combine these settings with either
+ <para>Note that these settings will disconnect propagation of mounts from the unit's processes to the
+ host. This means that this setting may not be used for services which shall be able to install mount points in
+ the main mount namespace. For <varname>ReadWritePaths=</varname> and <varname>ReadOnlyPaths=</varname>
+ propagation in the other direction is not affected, i.e. mounts created on the host generally appear in the
+ unit processes' namespace, and mounts removed on the host also disappear there too. In particular, note that
+ mount propagation from host to unit will result in unmodified mounts to be created in the unit's namespace,
+ i.e. writable mounts appearing on the host will be writable in the unit's namespace too, even when propagated
+ below a path marked with <varname>ReadOnlyPaths=</varname>! Restricting access with these options hence does
+ not extend to submounts of a directory that are created later on. This means the lock-down offered by that
+ setting is not complete, and does not offer full protection. </para>
+
+ <para>Note that the effect of these settings may be undone by privileged processes. In order to set up an
+ effective sandboxed environment for a unit it is thus recommended to combine these settings with either
<varname>CapabilityBoundingSet=~CAP_SYS_ADMIN</varname> or
<varname>SystemCallFilter=~@mount</varname>.</para></listitem>
</varlistentry>
security.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>ProtectHostname=</varname></term>
+
+ <listitem><para>Takes a boolean argument. When set, sets up a new UTS namespace for the executed
+ processes. In addition, changing hostname or domainname is prevented. Defaults to off.</para>
+
+ <para>Note that the implementation of this setting might be impossible (for example if UTS namespaces are not
+ available), and the unit should be written in a way that does not solely rely on this setting for
+ security.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>ProtectKernelTunables=</varname></term>
<constant>SHM_EXEC</constant> set. Note that this option is incompatible with programs and libraries that
generate program code dynamically at runtime, including JIT execution engines, executable stacks, and code
"trampoline" feature of various C compilers. This option improves service security, as it makes harder for
- software exploits to change running code dynamically. Note that this feature is fully available on x86-64, and
- partially on x86. Specifically, the <function>shmat()</function> protection is not available on x86. Note that
- on systems supporting multiple ABIs (such as x86/x86-64) it is recommended to turn off alternative ABIs for
- services, so that they cannot be used to circumvent the restrictions of this option. Specifically, it is
- recommended to combine this option with <varname>SystemCallArchitectures=native</varname> or similar. If
- running in user mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant> capability
- (e.g. setting <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is implied.</para></listitem>
+ software exploits to change running code dynamically. However, the protection can be circumvented, if
+ the service can write to a filesystem, which is not mounted with <constant>noexec</constant> (such as
+ <filename>/dev/shm</filename>), or it can use <function>memfd_create()</function>. This can be
+ prevented by making such file systems inaccessible to the service
+ (e.g. <varname>InaccessiblePaths=/dev/shm</varname>) and installing further system call filters
+ (<varname>SystemCallFilter=~memfd_create</varname>). Note that this feature is fully available on
+ x86-64, and partially on x86. Specifically, the <function>shmat()</function> protection is not
+ available on x86. Note that on systems supporting multiple ABIs (such as x86/x86-64) it is
+ recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the
+ restrictions of this option. Specifically, it is recommended to combine this option with
+ <varname>SystemCallArchitectures=native</varname> or similar. If running in user mode, or in system
+ mode, but without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting
+ <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is implied.</para></listitem>
</varlistentry>
<varlistentry>
settings (see the discussion in <varname>PrivateMounts=</varname> 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 <option>slave</option> first. Setting this option to
- <option>shared</option> 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 <option>slave</option>.</para>
+ <option>shared</option> does not reestablish propagation in that case.</para>
<para>If not set – but file system namespaces are enabled through another file system namespace unit setting –
<option>shared</option> mount propagation is used, but — as mentioned — as <option>slave</option> is applied
<refsect1>
<title>System Call Filtering</title>
- <variablelist>
+ <variablelist class='unit-directives'>
<varlistentry>
<term><varname>SystemCallFilter=</varname></term>
<refsect1>
<title>Environment</title>
- <variablelist>
+ <variablelist class='unit-directives'>
<varlistentry>
<term><varname>Environment=</varname></term>
<para>
See <citerefentry
project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details
- about environment variables.</para></listitem>
+ about environment variables.</para>
+
+ <para>Note that environment variables are not suitable for passing secrets (such as passwords, key material, …)
+ to service processes. Environment variables set for a unit are exposed to unprivileged clients via D-Bus IPC,
+ and generally not understood as being data that requires protection. Moreover, environment variables are
+ propagated down the process tree, including across security boundaries (such as setuid/setgid executables), and
+ hence might leak to processes that should not have access to the secret data.</para></listitem>
</varlistentry>
<varlistentry>
<refsect1>
<title>Logging and Standard Input/Output</title>
- <variablelist>
+ <variablelist class='unit-directives'>
<varlistentry>
<term><varname>StandardInput=</varname></term>
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
details about named file descriptors and their ordering.</para>
- <para>This setting defaults to <option>null</option>.</para></listitem>
+ <para>This setting defaults to <option>null</option>.</para>
+
+ <para>Note that services which specify <option>DefaultDependencies=no</option> and use
+ <varname>StandardInput=</varname> or <varname>StandardOutput=</varname> with
+ <option>tty</option>/<option>tty-force</option>/<option>tty-fail</option>, should specify
+ <option>After=systemd-vconsole-setup.service</option>, to make sure that the tty intialization is
+ finished before they start.</para></listitem>
</varlistentry>
<varlistentry>
<option>syslog</option>, <option>kmsg</option>, <option>journal+console</option>,
<option>syslog+console</option>, <option>kmsg+console</option>,
<option>file:<replaceable>path</replaceable></option>, <option>append:<replaceable>path</replaceable></option>,
- <option>socket</option> or<option>fd:<replaceable>name</replaceable></option>.</para>
+ <option>socket</option> or <option>fd:<replaceable>name</replaceable></option>.</para>
<para><option>inherit</option> duplicates the file descriptor of standard input for standard output.</para>
matching. Assign an empty string to reset the list.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>LogRateLimitIntervalSec=</varname></term>
+ <term><varname>LogRateLimitBurst=</varname></term>
+
+ <listitem><para>Configures the rate limiting that is applied to messages generated by this unit. If, in the
+ time interval defined by <varname>LogRateLimitIntervalSec=</varname>, more messages than specified in
+ <varname>LogRateLimitBurst=</varname> are logged by a service, all further messages within the interval are
+ dropped until the interval is over. A message about the number of dropped messages is generated. The time
+ specification for <varname>LogRateLimitIntervalSec=</varname> may be specified in the following units: "s",
+ "min", "h", "ms", "us" (see
+ <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details).
+ The default settings are set by <varname>RateLimitIntervalSec=</varname> and <varname>RateLimitBurst=</varname>
+ configured in <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>SyslogIdentifier=</varname></term>
<refsect1>
<title>System V Compatibility</title>
- <variablelist>
+ <variablelist class='unit-directives'>
<varlistentry>
<term><varname>UtmpIdentifier=</varname></term>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><varname>$PIDFILE</varname></term>
+
+ <listitem><para>The path to the configured PID file, in case the process is forked off on behalf of a
+ service that uses the <varname>PIDFile=</varname> setting, see
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details. Service code may use this environment variable to automatically generate a PID file at
+ the location configured in the unit file. This field is set to an absolute path in the file
+ system.</para></listitem>
+ </varlistentry>
+
</variablelist>
<para>For system services, when <varname>PAMName=</varname> is enabled and <command>pam_systemd</command> is part
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
projects / thirdparty / systemd.git / blobdiff