<para>A few execution parameters result in additional, automatic
dependencies to be added.</para>
- <para>Units with <varname>WorkingDirectory=</varname> or
- <varname>RootDirectory=</varname> set automatically gain
- dependencies of type <varname>Requires=</varname> and
- <varname>After=</varname> on all mount units required to access
- the specified paths. This is equivalent to having them listed
- explicitly in <varname>RequiresMountsFor=</varname>.</para>
+ <para>Units with <varname>WorkingDirectory=</varname>, <varname>RootDirectory=</varname> or
+ <varname>RootImage=</varname> set automatically gain dependencies of type <varname>Requires=</varname> and
+ <varname>After=</varname> on all mount units required to access the specified paths. This is equivalent to having
+ them listed explicitly in <varname>RequiresMountsFor=</varname>.</para>
<para>Similar, units with <varname>PrivateTmp=</varname> enabled automatically get mount unit dependencies for all
mounts required to access <filename>/tmp</filename> and <filename>/var/tmp</filename>. They will also gain an
<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>
+ <varname>RootDirectory=</varname>/<varname>RootImage=</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>
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>
+ <para>The <varname>MountAPIVFS=</varname> and <varname>PrivateUsers=</varname> settings are particularly useful
+ in conjunction with <varname>RootDirectory=</varname>. For details, see below.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RootImage=</varname></term>
+ <listitem><para>Takes a path to a block device node or regular file as argument. This call is similar to
+ <varname>RootDirectory=</varname> however mounts a file system hierarchy from a block device node or loopback
+ file instead of a directory. The device node or file system image file needs to contain a file system without a
+ partition table, or a file system within an MBR/MS-DOS or GPT partition table with only a single
+ Linux-compatible partition, or a set of file systems within a GPT partition table that follows the <ulink
+ url="https://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable Partitions
+ Specification</ulink>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>MountAPIVFS=</varname></term>
+
+ <listitem><para>Takes a boolean argument. If on, a private mount namespace for the unit's processes is created
+ and the API file systems <filename>/proc</filename>, <filename>/sys</filename>, and <filename>/dev</filename>
+ are mounted inside of it, unless they are already mounted. Note that this option has no effect unless used in
+ conjunction with <varname>RootDirectory=</varname>/<varname>RootImage=</varname> as these three mounts are
+ generally mounted in the host anyway, and unless the root directory is changed, the private mount namespace
+ will be a 1:1 copy of the host's, and include these three mounts. Note that the <filename>/dev</filename> file
+ system of the host is bind mounted if this option is used without <varname>PrivateDevices=</varname>. To run
+ the service with a private, minimal version of <filename>/dev/</filename>, combine this option with
+ <varname>PrivateDevices=</varname>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Group=</varname></term>
<listitem><para>Set the UNIX user or group that the processes are executed as, respectively. Takes a single
- user or group name, or numeric ID as argument. For system services (services run by the system service manager,
+ user or group name, or a numeric ID as argument. For system services (services run by the system service manager,
i.e. managed by PID 1) and for user services of the root user (services managed by root's instance of
<command>systemd --user</command>), the default is <literal>root</literal>, but <varname>User=</varname> may be
used to specify a different user. For user services of any other user, switching user identity is not
permitted, hence the only valid setting is the same user the user's service manager is running as. If no group
is set, the default group of the user is used. This setting does not affect commands whose command line is
- prefixed with <literal>+</literal>.</para></listitem>
+ prefixed with <literal>+</literal>.</para>
+
+ <para>Note that restrictions on the user/group name syntax are enforced: the specified name must consist only
+ of the characters a-z, A-Z, 0-9, <literal>_</literal> and <literal>-</literal>, except for the first character
+ which must be one of a-z, A-Z or <literal>_</literal> (i.e. numbers and <literal>-</literal> are not permitted
+ as first character). The user/group name must have at least one character, and at most 31. These restrictions
+ are enforced in order to avoid ambiguities and to ensure user/group names and unit files remain portable among
+ Linux systems.</para>
+
+ <para>When used in conjunction with <varname>DynamicUser=</varname> the user/group name specified is
+ dynamically allocated at the time the service is started, and released at the time the service is stopped —
+ unless it is already allocated statically (see below). If <varname>DynamicUser=</varname> is not used the
+ specified user and group must have been created statically in the user database no later than the moment the
+ service is started, for example using the
+ <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> facility, which
+ is applied at boot or package install time.</para></listitem>
</varlistentry>
<varlistentry>
assignments have no effect. Variable expansion is not
performed inside the strings, however, specifier expansion is
possible. The $ character has no special meaning. If you need
- to assign a value containing spaces to a variable, use double
+ to assign a value containing spaces or the equals sign to a variable, use double
quotes (") for the assignment.</para>
<para>Example:
access a process might have to the file system hierarchy. Each setting takes a space-separated list of paths
relative to the host's root directory (i.e. the system running the service manager). Note that if paths
contain symlinks, they are resolved relative to the root directory set with
- <varname>RootDirectory=</varname>.</para>
+ <varname>RootDirectory=</varname>/<varname>RootImage=</varname>.</para>
<para>Paths listed in <varname>ReadWritePaths=</varname> are accessible from within the namespace with the same
access modes as from outside of it. Paths listed in <varname>ReadOnlyPaths=</varname> are accessible for
<para>Paths in <varname>ReadWritePaths=</varname>, <varname>ReadOnlyPaths=</varname> and
<varname>InaccessiblePaths=</varname> may be prefixed with <literal>-</literal>, in which case they will be
ignored when they do not exist. If prefixed with <literal>+</literal> the paths are taken relative to the root
- directory of the unit, as configured with <varname>RootDirectory=</varname>, instead of relative to the root
- directory of the host (see above). When combining <literal>-</literal> and <literal>+</literal> on the same
- path make sure to specify <literal>-</literal> first, and <literal>+</literal> second.</para>
+ directory of the unit, as configured with <varname>RootDirectory=</varname>/<varname>RootImage=</varname>,
+ instead of relative to the root directory of the host (see above). When combining <literal>-</literal> and
+ <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
source path, destination path and option string, where the latter two are optional. If only a source path is
specified the source and destination is taken to be the same. The option string may be either
<literal>rbind</literal> or <literal>norbind</literal> for configuring a recursive or non-recursive bind
- mount. If the destination parth is omitted, the option string must be omitted too.</para>
+ mount. If the destination path is omitted, the option string must be omitted too.</para>
<para><varname>BindPaths=</varname> creates regular writable bind mounts (unless the source file system mount
is already marked read-only), while <varname>BindReadOnlyPaths=</varname> creates read-only bind mounts. These
that in this case both read-only and regular bind mounts are reset, regardless which of the two settings is
used.</para>
- <para>This option is particularly useful when <varname>RootDirectory=</varname> is used. In this case the
- source path refers to a path on the host file system, while the destination path referes to a path below the
- root directory of the unit.</para></listitem>
+ <para>This option is particularly useful when <varname>RootDirectory=</varname>/<varname>RootImage=</varname>
+ is used. In this case the source path refers to a path on the host file system, while the destination path
+ refers to a path below the root directory of the unit.</para></listitem>
</varlistentry>
<varlistentry>
<varname>After=</varname> dependencies on all mount units necessary to access <filename>/tmp</filename> and
<filename>/var/tmp</filename>. Moreover an implicitly <varname>After=</varname> ordering on
<citerefentry><refentrytitle>systemd-tmpfiles-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- is added.</para></listitem>
+ is added.</para>
+
+ <para>Note that the implementation of this setting might be impossible (for example if mount 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>PrivateDevices=</varname></term>
- <listitem><para>Takes a boolean argument. If true, sets up a new /dev namespace for the executed processes and
- only adds API pseudo devices such as <filename>/dev/null</filename>, <filename>/dev/zero</filename> or
+ <listitem><para>Takes a boolean argument. If true, sets up a new <filename>/dev</filename> mount for the
+ executed processes and only adds API pseudo devices such as <filename>/dev/null</filename>,
+ <filename>/dev/zero</filename> or
<filename>/dev/random</filename> (as well as the pseudo TTY subsystem) to it, but no physical devices such as
<filename>/dev/sda</filename>, system memory <filename>/dev/mem</filename>, system ports
<filename>/dev/port</filename> and others. This is useful to securely turn off physical device access by the
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details). 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. The /dev namespace will be
- mounted read-only and 'noexec'. The latter may break old programs which try to set up executable memory by
+ services which shall be able to install mount points in the main mount namespace. The new <filename>/dev</filename>
+ will be mounted read-only and 'noexec'. The latter may break old programs which try to set up executable memory by
using <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> of
- <filename>/dev/zero</filename> instead of using <constant>MAP_ANON</constant>. 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 above.
+ <filename>/dev/zero</filename> instead of using <constant>MAP_ANON</constant>. For this setting the same restrictions
+ regarding mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see above.
If turned on and 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>
+ capability (e.g. setting <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is implied.
+ </para>
+
+ <para>Note that the implementation of this setting might be impossible (for example if mount 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>
configures only the loopback network device
<literal>lo</literal> inside it. No other network devices will
be available to the executed process. This is useful to
- securely turn off network access by the executed process.
+ turn off network access by the executed process.
Defaults to false. It is possible to run two or more units
within the same private network namespace by using the
<varname>JoinsNamespaceOf=</varname> directive, see
The latter has the effect that AF_UNIX sockets in the abstract
socket namespace will become unavailable to the processes
(however, those located in the file system will continue to be
- accessible).</para></listitem>
+ accessible).</para>
+
+ <para>Note that the implementation of this setting might be impossible (for example if network 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>
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>
+ <para>This setting is particularly useful in conjunction with
+ <varname>RootDirectory=</varname>/<varname>RootImage=</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>
+
+ <para>Note that the implementation of this setting might be impossible (for example if user 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>
<filename>/proc/sys</filename>, <filename>/sys</filename>, <filename>/proc/sysrq-trigger</filename>,
<filename>/proc/latency_stats</filename>, <filename>/proc/acpi</filename>,
<filename>/proc/timer_stats</filename>, <filename>/proc/fs</filename> and <filename>/proc/irq</filename> will
- be made read-only to all processes of the unit. Usually, tunable kernel variables should only be written at
- boot-time, with the <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- mechanism. Almost no services need to write to these at runtime; it is hence recommended to turn this on for
- most services. For this setting the same restrictions regarding mount propagation and privileges apply as for
- <varname>ReadOnlyPaths=</varname> and related calls, see above. Defaults to off.
- If turned on and 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. Note that this option does not prevent kernel tuning through IPC interfaces
- and external programs. However <varname>InaccessiblePaths=</varname> can be used to
- make some IPC file system objects inaccessible.</para></listitem>
+ be made read-only to all processes of the unit. Usually, tunable kernel variables should be initialized only at
+ boot-time, for example with the
+ <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> mechanism. Few
+ services need to write to these at runtime; it is hence recommended to turn this on for most services. For this
+ setting the same restrictions regarding mount propagation and privileges apply as for
+ <varname>ReadOnlyPaths=</varname> and related calls, see above. Defaults to off. If turned on and if running
+ in user mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. services
+ for which <varname>User=</varname> is set), <varname>NoNewPrivileges=yes</varname> is implied. Note that this
+ option does not prevent indirect changes to kernel tunables effected by IPC calls to other processes. However,
+ <varname>InaccessiblePaths=</varname> may be used to make relevant IPC file system objects inaccessible. If
+ <varname>ProtectKernelTunables=</varname> is set, <varname>MountAPIVFS=yes</varname> is
+ implied.</para></listitem>
</varlistentry>
<varlistentry>
unit. Except for container managers no services should require write access to the control groups hierarchies;
it is hence recommended to turn this on for most services. For this setting the same restrictions regarding
mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see
- above. Defaults to off.</para></listitem>
+ above. Defaults to off. If <varname>ProtectControlGroups=</varname> is set, <varname>MountAPIVFS=yes</varname> is
+ implied.</para></listitem>
</varlistentry>
<varlistentry>
filter is reset, all prior assignments will have no effect. This does not affect commands prefixed with
<literal>+</literal>.</para>
+ <para>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.</para>
+
<para>Note that strict system call filters may impact execution and error handling code paths of the service
invocation. Specifically, access to the <function>execve</function> system call is required for the execution
of the service binary — if it is blocked service invocation will necessarily fail. Also, if execution of the
<entry>@resources</entry>
<entry>System calls for changing resource limits, memory and scheduling parameters (<citerefentry project='man-pages'><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>setpriority</refentrytitle><manvolnum>2</manvolnum></citerefentry>, …)</entry>
</row>
+ <row>
+ <entry>@setuid</entry>
+ <entry>System calls for changing user ID and group ID credentials, (<citerefentry project='man-pages'><refentrytitle>setuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>setgid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>setresuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, …)</entry>
+ </row>
<row>
<entry>@swap</entry>
<entry>System calls for enabling/disabling swap devices (<citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>swapoff</refentrytitle><manvolnum>2</manvolnum></citerefentry>)</entry>
<varlistentry>
<term><varname>SystemCallArchitectures=</varname></term>
- <listitem><para>Takes a space-separated list of architecture identifiers to
- include in the system call filter. The known architecture identifiers are the same
- as for <varname>ConditionArchitecture=</varname> described in
- <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- as well as <constant>x32</constant>, <constant>mips64-n32</constant>,
- <constant>mips64-le-n32</constant>, and the special identifier
- <constant>native</constant>. Only system calls of the specified architectures will
- be permitted to processes of this unit. This is an effective way to disable
- compatibility with non-native architectures for processes, for example to prohibit
- execution of 32-bit x86 binaries on 64-bit x86-64 systems. The special
- <constant>native</constant> identifier implicitly maps to the native architecture
- of the system (or more strictly: to the architecture the system manager is
- compiled for). If running in user mode, or in system mode, but without the
- <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting
- <varname>User=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is
- implied. Note that setting this option to a non-empty list implies that
- <constant>native</constant> is included too. By default, this option is set to the
- empty list, i.e. no architecture system call filtering is applied.
- </para></listitem>
+ <listitem><para>Takes a space-separated list of architecture identifiers to include in the system call
+ filter. The known architecture identifiers are the same as for <varname>ConditionArchitecture=</varname>
+ described in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ as well as <constant>x32</constant>, <constant>mips64-n32</constant>, <constant>mips64-le-n32</constant>, and
+ the special identifier <constant>native</constant>. Only system calls of the specified architectures will be
+ permitted to processes of this unit. This is an effective way to disable compatibility with non-native
+ architectures for processes, for example to prohibit execution of 32-bit x86 binaries on 64-bit x86-64
+ systems. The special <constant>native</constant> identifier implicitly maps to the native architecture of the
+ system (or more strictly: to the architecture the system manager is compiled for). If running in user mode, or
+ in system mode, but without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting
+ <varname>User=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is implied. Note that setting this
+ option to a non-empty list implies that <constant>native</constant> is included too. By default, this option is
+ set to the empty list, i.e. no system call architecture filtering is applied.</para>
+
+ <para>Note that system call filtering is not equally effective on all architectures. For example, on x86
+ filtering of network socket-related calls is not possible, due to ABI limitations — a limitation that x86-64
+ does not have, however. On systems supporting multiple ABIs at the same time — such as x86/x86-64 — it is hence
+ recommended to limit the set of permitted system call architectures so that secondary ABIs may not be used to
+ circumvent the restrictions applied to the native ABI of the system. In particular, setting
+ <varname>SystemCallArchitectures=native</varname> is a good choice for disabling non-native ABIs.</para>
+
+ <para>System call architectures may also be restricted system-wide via the
+ <varname>SystemCallArchitectures=</varname> option in the global configuration. See
+ <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+ details.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>RestrictAddressFamilies=</varname></term>
- <listitem><para>Restricts the set of socket address families
- accessible to the processes of this unit. Takes a
- space-separated list of address family names to whitelist,
- such as
- <constant>AF_UNIX</constant>,
- <constant>AF_INET</constant> or
- <constant>AF_INET6</constant>. When
- prefixed with <constant>~</constant> the listed address
- families will be applied as blacklist, otherwise as whitelist.
- Note that this restricts access to the
- <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- system call only. Sockets passed into the process by other
- means (for example, by using socket activation with socket
- units, see
- <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
- are unaffected. Also, sockets created with
- <function>socketpair()</function> (which creates connected
- AF_UNIX sockets only) are unaffected. Note that this option
- has no effect on 32-bit x86 and is ignored (but works
- correctly on x86-64). If running in user mode, or in system
- mode, but without the <constant>CAP_SYS_ADMIN</constant>
- capability (e.g. setting <varname>User=nobody</varname>),
- <varname>NoNewPrivileges=yes</varname> is implied. By
- default, no restriction applies, all address families are
- accessible to processes. If assigned the empty string, any
- previous list changes are undone.</para>
-
- <para>Use this option to limit exposure of processes to remote
- systems, in particular via exotic network protocols. Note that
- in most cases, the local <constant>AF_UNIX</constant> address
- family should be included in the configured whitelist as it is
- frequently used for local communication, including for
+ <listitem><para>Restricts the set of socket address families accessible to the processes of this unit. Takes a
+ space-separated list of address family names to whitelist, such as <constant>AF_UNIX</constant>,
+ <constant>AF_INET</constant> or <constant>AF_INET6</constant>. When prefixed with <constant>~</constant> the
+ listed address families will be applied as blacklist, otherwise as whitelist. Note that this restricts access
+ to the <citerefentry
+ project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call
+ only. Sockets passed into the process by other means (for example, by using socket activation with socket
+ units, see <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
+ are unaffected. Also, sockets created with <function>socketpair()</function> (which creates connected AF_UNIX
+ sockets only) are unaffected. Note that this option has no effect on 32-bit x86, s390, s390x, mips, mips-le,
+ ppc, ppc-le, pcc64, ppc64-le and is ignored (but works correctly on other ABIs, including x86-64). 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=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is implied. By default,
+ no restrictions apply, all address families are accessible to processes. If assigned the empty string, any
+ previous address familiy restriction changes are undone. This setting does not affect commands prefixed with
+ <literal>+</literal>.</para>
+
+ <para>Use this option to limit exposure of processes to remote access, in particular via exotic and sensitive
+ network protocols, such as <constant>AF_PACKET</constant>. Note that in most cases, the local
+ <constant>AF_UNIX</constant> address family should be included in the configured whitelist as it is frequently
+ used for local communication, including for
<citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- logging. This does not affect commands prefixed with <literal>+</literal>.</para></listitem>
+ logging.</para></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Restricts access to Linux namespace functionality for the processes of this unit. For details
about Linux namespaces, see
- <citerefentry><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Either takes a
+ <citerefentry project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Either takes a
boolean argument, or a space-separated list of namespace type identifiers. If false (the default), no
restrictions on namespace creation and switching are made. If true, access to any kind of namespacing is
prohibited. Otherwise, a space-separated list of namespace type identifiers must be specified, consisting of
any combination of: <constant>cgroup</constant>, <constant>ipc</constant>, <constant>net</constant>,
<constant>mnt</constant>, <constant>pid</constant>, <constant>user</constant> and <constant>uts</constant>. Any
namespace type listed is made accessible to the unit's processes, access to namespace types not listed is
- prohibited (whitelisting). By prepending the list with a single tilda character (<literal>~</literal>) the
+ prohibited (whitelisting). By prepending the list with a single tilde character (<literal>~</literal>) the
effect may be inverted: only the listed namespace types will be made inaccessible, all unlisted ones are
permitted (blacklisting). If the empty string is assigned, the default namespace restrictions are applied,
which is equivalent to false. Internally, this setting limits access to the
<citerefentry><refentrytitle>setns</refentrytitle><manvolnum>2</manvolnum></citerefentry> system calls, taking
the specified flags parameters into account. Note that — if this option is used — in addition to restricting
creation and switching of the specified types of namespaces (or all of them, if true) access to the
- <function>setns()</function> system call with a zero flags parameter is prohibited.
- 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>
+ <function>setns()</function> system call with a zero flags parameter is prohibited. This setting is only
+ supported on x86, x86-64, mips, mips-le, mips64, mips64-le, mips64-n32, mips64-le-n32, ppc64, ppc64-le,
+ s390 and s390x, and enforces no restrictions on other architectures. 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>
<varlistentry>
<term><varname>RuntimeDirectory=</varname></term>
+
+ <listitem><para>Takes a whitespace-separated list of directory names. The specified directory names must be
+ relative, and may not include <literal>.</literal> or <literal>..</literal>. If set, one or more directories
+ including their parents by the specified names will be created below <filename>/run</filename> (for system
+ services) or below <varname>$XDG_RUNTIME_DIR</varname> (for user services) when the unit is started. The
+ lowest subdirectories are removed when the unit is stopped. It is possible to preserve the directories if
+ <varname>RuntimeDirectoryPreserve=</varname> is configured to <option>restart</option> or <option>yes</option>.
+ The lowest subdirectories will have the access mode specified in <varname>RuntimeDirectoryMode=</varname>,
+ and be owned by the user and group specified in <varname>User=</varname> and <varname>Group=</varname>.
+ This implies <varname>ReadWritePaths=</varname>, that is, the directories specified
+ in this option are accessible with the access mode specified in <varname>RuntimeDirectoryMode=</varname>
+ even if <varname>ProtectSystem=</varname> is set to <option>strict</option>.
+ Use this to manage one or more runtime directories of 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
+ directory is cleaned up automatically after use. For runtime directories that require more complex or
+ different configuration or lifetime guarantees, please consider using
+ <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+ <para>Example: if a system service unit has the following,
+ <programlisting>RuntimeDirectory=foo/bar baz</programlisting>
+ the service manager creates <filename>/run/foo</filename> (if it does not exist), <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>
+ </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>
<term><varname>RuntimeDirectoryMode=</varname></term>
+ <term><varname>StateDirectoryMode=</varname></term>
+ <term><varname>CacheDirectoryMode=</varname></term>
+ <term><varname>LogsDirectoryMode=</varname></term>
+ <term><varname>ConfigurationDirectoryMode=</varname></term>
+
+ <listitem><para>Specifies the access mode of the directories specified in
+ <varname>RuntimeDirectory=</varname>, <varname>StateDirectory=</varname>, <varname>CacheDirectory=</varname>,
+ <varname>LogsDirectory=</varname>, or <varname>ConfigurationDirectory=</varname>, respectively, as an octal number.
+ Defaults to <constant>0755</constant>. See "Permissions" in
+ <citerefentry project='man-pages'><refentrytitle>path_resolution</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for a discussion of the meaning of permission bits.
+ </para></listitem>
+ </varlistentry>
- <listitem><para>Takes a list of directory names. If set, one
- or more directories by the specified names will be created
- below <filename>/run</filename> (for system services) or below
- <varname>$XDG_RUNTIME_DIR</varname> (for user services) when
- the unit is started, and removed when the unit is stopped. The
- directories will have the access mode specified in
- <varname>RuntimeDirectoryMode=</varname>, and will be owned by
- the user and group specified in <varname>User=</varname> and
- <varname>Group=</varname>. Use this to manage one or more
- runtime directories of the unit and bind their lifetime to the
- daemon runtime. The specified directory names must be
- relative, and may not include a <literal>/</literal>, i.e.
- must refer to simple directories to create or remove. 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 directory is
- cleaned up automatically after use. For runtime directories
- that require more complex or different configuration or
- lifetime guarantees, please consider using
- <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+ <varlistentry>
+ <term><varname>RuntimeDirectoryPreserve=</varname></term>
+
+ <listitem><para>Takes a boolean argument or <option>restart</option>.
+ If set to <option>no</option> (the default), the directories specified in <varname>RuntimeDirectory=</varname>
+ are always removed when the service stops. If set to <option>restart</option> the directories are preserved
+ when the service is both automatically and manually restarted. Here, the automatic restart means the operation
+ specified in <varname>Restart=</varname>, and manual restart means the one triggered by
+ <command>systemctl restart foo.service</command>. If set to <option>yes</option>, then the directories are not
+ removed when the service is stopped. Note that since the runtime directory <filename>/run</filename> is a mount
+ point of <literal>tmpfs</literal>, then for system services the directories specified in
+ <varname>RuntimeDirectory=</varname> are removed when the system is rebooted.
+ </para></listitem>
</varlistentry>
<varlistentry>
<term><varname>MemoryDenyWriteExecute=</varname></term>
<listitem><para>Takes a boolean argument. If set, attempts to create memory mappings that are writable and
- executable at the same time, or to change existing memory mappings to become executable, or mapping shared memory
- segments as executable are prohibited.
- Specifically, a system call filter is added that rejects
- <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- system calls with both <constant>PROT_EXEC</constant> and <constant>PROT_WRITE</constant> set,
- <citerefentry><refentrytitle>mprotect</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- system calls with <constant>PROT_EXEC</constant> set and
- <citerefentry><refentrytitle>shmat</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- system calls with <constant>SHM_EXEC</constant> set. Note that this option is incompatible with programs
- that generate program code dynamically at runtime, such as JIT execution engines, or programs compiled making
- use of the code "trampoline" feature of various C compilers. This option improves service security, as it makes
- harder for software exploits to change running code dynamically.
- 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>
+ executable at the same time, or to change existing memory mappings to become executable, or mapping shared
+ memory segments as executable are prohibited. Specifically, a system call filter is added that rejects
+ <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> system calls with both
+ <constant>PROT_EXEC</constant> and <constant>PROT_WRITE</constant> set,
+ <citerefentry><refentrytitle>mprotect</refentrytitle><manvolnum>2</manvolnum></citerefentry> system calls with
+ <constant>PROT_EXEC</constant> set and
+ <citerefentry><refentrytitle>shmat</refentrytitle><manvolnum>2</manvolnum></citerefentry> system calls with
+ <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>
</varlistentry>
<varlistentry>
projects / thirdparty / systemd.git / blobdiff