<?xml version='1.0'?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
-<!--
- SPDX-License-Identifier: LGPL-2.1+
--->
-
-<refentry id="systemd.exec">
+<refentry id="systemd.exec" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd.exec</title>
<productname>systemd</productname>
dependencies to be added to the unit (see above).</para>
<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>
+ in conjunction with <varname>RootDirectory=</varname>. For details, see below.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
url="https://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable Partitions
Specification</ulink>.</para>
- <para>When <varname>DevicePolicy=</varname> is set to <literal>closed</literal> or <literal>strict</literal>,
- or set to <literal>auto</literal> and <varname>DeviceAllow=</varname> is set, then this setting adds
- <filename>/dev/loop-control</filename> with <constant>rw</constant> mode, <literal>block-loop</literal> and
- <literal>block-blkext</literal> with <constant>rwm</constant> mode to <varname>DeviceAllow=</varname>. See
+ <para>When <varname>DevicePolicy=</varname> is set to <literal>closed</literal> or
+ <literal>strict</literal>, or set to <literal>auto</literal> and <varname>DeviceAllow=</varname> is
+ set, then this setting adds <filename>/dev/loop-control</filename> with <constant>rw</constant> mode,
+ <literal>block-loop</literal> and <literal>block-blkext</literal> with <constant>rwm</constant> mode
+ to <varname>DeviceAllow=</varname>. See
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for the details about <varname>DevicePolicy=</varname> or <varname>DeviceAllow=</varname>. Also, see
- <varname>PrivateDevices=</varname> below, as it may change the setting of <varname>DevicePolicy=</varname>.
- </para></listitem>
+ <varname>PrivateDevices=</varname> below, as it may change the setting of
+ <varname>DevicePolicy=</varname>.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
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>
+ <varname>PrivateDevices=</varname>.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
<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>
+ refers to a path below the root directory of the unit.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
</variablelist>
<refsect1>
<title>Credentials</title>
+ <xi:include href="system-only.xml" xpointer="plural"/>
+
<variablelist class='unit-directives'>
<varlistentry>
<varlistentry>
<term><varname>DynamicUser=</varname></term>
- <listitem><para>Takes a boolean parameter. If set, a UNIX user and group pair is allocated dynamically when the
- unit is started, and released as soon as it is stopped. The user and group will not be added to
- <filename>/etc/passwd</filename> or <filename>/etc/group</filename>, but are managed transiently during
- runtime. The <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- glibc NSS module provides integration of these dynamic users/groups into the system's user and group
+ <listitem><para>Takes a boolean parameter. If set, a UNIX user and group pair is allocated
+ dynamically when the unit is started, and released as soon as it is stopped. The user and group will
+ not be added to <filename>/etc/passwd</filename> or <filename>/etc/group</filename>, but are managed
+ transiently during runtime. The
+ <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> glibc
+ NSS module provides integration of these dynamic users/groups into the system's user and group
databases. The user and group name to use may be configured via <varname>User=</varname> and
- <varname>Group=</varname> (see above). If these options are not used and dynamic user/group allocation is
- enabled for a unit, the name of the dynamic user/group is implicitly derived from the unit name. If the unit
- name without the type suffix qualifies as valid user name it is used directly, otherwise a name incorporating a
- hash of it is used. If a statically allocated user or group of the configured name already exists, it is used
- and no dynamic user/group is allocated. Note that if <varname>User=</varname> is specified and the static group
- with the name exists, then it is required that the static user with the name already exists. Similarly, if
- <varname>Group=</varname> is specified and the static user with the name exists, then it is required that the
- static group with the name already exists. Dynamic users/groups are allocated from the UID/GID range
- 61184…65519. It is recommended to avoid this range for regular system or login users. At any point in time
- each UID/GID from this range is only assigned to zero or one dynamically allocated users/groups in
- use. However, UID/GIDs are recycled after a unit is terminated. Care should be taken that any processes running
- as part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by these
- users/groups around, as a different unit might get the same UID/GID assigned later on, and thus gain access to
- these files or directories. If <varname>DynamicUser=</varname> is enabled, <varname>RemoveIPC=</varname>,
- <varname>PrivateTmp=</varname> are implied. This ensures that the lifetime of IPC objects and temporary files
- created by the executed processes is bound to the runtime of the service, and hence the lifetime of the dynamic
- user/group. Since <filename>/tmp</filename> and <filename>/var/tmp</filename> are usually the only
- world-writable directories on a system this ensures that a unit making use of dynamic user/group allocation
- 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
- 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 create
- security issues involving files created by the service. Use <varname>RuntimeDirectory=</varname> (see below) in
- order to assign a writable runtime directory to a service, owned by the dynamic user/group and removed
- 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>
+ <varname>Group=</varname> (see above). If these options are not used and dynamic user/group
+ allocation is enabled for a unit, the name of the dynamic user/group is implicitly derived from the
+ unit name. If the unit name without the type suffix qualifies as valid user name it is used directly,
+ otherwise a name incorporating a hash of it is used. If a statically allocated user or group of the
+ configured name already exists, it is used and no dynamic user/group is allocated. Note that if
+ <varname>User=</varname> is specified and the static group with the name exists, then it is required
+ that the static user with the name already exists. Similarly, if <varname>Group=</varname> is
+ specified and the static user with the name exists, then it is required that the static group with
+ the name already exists. Dynamic users/groups are allocated from the UID/GID range 61184…65519. It is
+ recommended to avoid this range for regular system or login users. At any point in time each UID/GID
+ from this range is only assigned to zero or one dynamically allocated users/groups in use. However,
+ UID/GIDs are recycled after a unit is terminated. Care should be taken that any processes running as
+ part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by
+ these users/groups around, as a different unit might get the same UID/GID assigned later on, and thus
+ gain access to these files or directories. If <varname>DynamicUser=</varname> is enabled,
+ <varname>RemoveIPC=</varname>, <varname>PrivateTmp=</varname> are implied. This ensures that the
+ lifetime of IPC objects and temporary files created by the executed processes is bound to the runtime
+ of the service, and hence the lifetime of the dynamic user/group. Since <filename>/tmp</filename> and
+ <filename>/var/tmp</filename> are usually the only world-writable directories on a system this
+ ensures that a unit making use of dynamic user/group allocation 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 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 create security issues involving files created by the service. Use
+ <varname>RuntimeDirectory=</varname> (see below) in order to assign a writable runtime directory to a
+ service, owned by the dynamic user/group and removed 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). If this option is enabled, care should be taken that the unit's processes do not get access
+ to directories outside of these explicitly configured and managed ones. Specifically, do not use
+ <varname>BindPaths=</varname> and be careful with <constant>AF_UNIX</constant> file descriptor
+ passing for directory file descriptors, as this would permit processes to create files or directories
+ owned by the dynamic user/group that are not subject to the lifecycle and access guarantees of the
+ service. Defaults to off.</para></listitem>
</varlistentry>
<varlistentry>
<refsect1>
<title>Capabilities</title>
+ <xi:include href="system-only.xml" xpointer="plural"/>
+
<variablelist class='unit-directives'>
<varlistentry>
<refsect1>
<title>Mandatory Access Control</title>
+
+ <xi:include href="system-only.xml" xpointer="plural"/>
+
<variablelist class='unit-directives'>
<varlistentry>
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>
+ see below.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
<tgroup cols='4'>
<thead>
<row>
- <entry>Locations</entry>
- <entry>for system</entry>
- <entry>for users</entry>
- <entry>Environment variable</entry>
+ <entry>Directory</entry>
+ <entry>Below path for system units</entry>
+ <entry>Below path for user units</entry>
+ <entry>Environment variable set</entry>
</row>
</thead>
<tbody>
<row>
<entry><varname>RuntimeDirectory=</varname></entry>
- <entry><filename>/run</filename></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><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><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><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><filename>/etc/</filename></entry>
<entry><varname>$XDG_CONFIG_HOME</varname></entry>
<entry><varname>$CONFIGURATION_DIRECTORY</varname></entry>
</row>
</tgroup>
</table>
- <para>In case of <varname>RuntimeDirectory=</varname> the lowest subdirectories are removed when the unit is
- stopped. It is possible to preserve the specified directories in this case if
- <varname>RuntimeDirectoryPreserve=</varname> is configured to <option>restart</option> or <option>yes</option>
- (see below). The directories specified with <varname>StateDirectory=</varname>,
+ <para>In case of <varname>RuntimeDirectory=</varname> the innermost subdirectories are removed when
+ the unit is stopped. It is possible to preserve the specified directories in this case if
+ <varname>RuntimeDirectoryPreserve=</varname> is configured to <option>restart</option> or
+ <option>yes</option> (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>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>
+ <varname>SystemCallFilter=~@mount</varname>.</para>
+
+ <xi:include href="system-only.xml" xpointer="plural"/></listitem>
</varlistentry>
<varlistentry>
<programlisting>TemporaryFileSystem=/var:ro
BindReadOnlyPaths=/var/lib/systemd</programlisting>
then the invoked processes by the unit cannot see any files or directories under <filename>/var</filename> except for
- <filename>/var/lib/systemd</filename> or its contents.</para></listitem>
+ <filename>/var/lib/systemd</filename> or its contents.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
<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>
+ security.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
<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>
+ security.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
<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>
+ security.</para>
+
+ <para>When this option is used on a socket unit any sockets bound on behalf of this unit will be
+ bound within a private network namespace. This may be combined with
+ <varname>JoinsNamespaceOf=</varname> to listen on sockets inside of network namespaces of other
+ services.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>NetworkNamespacePath=</varname></term>
+
+ <listitem><para>Takes an absolute file system path refererring to a Linux network namespace
+ pseudo-file (i.e. a file like <filename>/proc/$PID/ns/net</filename> or a bind mount or symlink to
+ one). When set the invoked processes are added to the network namespace referenced by that path. The
+ path has to point to a valid namespace file at the moment the processes are forked off. If this
+ option is used <varname>PrivateNetwork=</varname> has no effect. If this option is used together with
+ <varname>JoinsNamespaceOf=</varname> then it only has an effect if this unit is started before any of
+ the listed units that have <varname>PrivateNetwork=</varname> or
+ <varname>NetworkNamespacePath=</varname> configured, as otherwise the network namespace of those
+ units is reused.</para>
+
+ <para>When this option is used on a socket unit any sockets bound on behalf of this unit will be
+ bound within the specified network namespace.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
<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>
+ security.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
<para>Note that when this option is enabled for a service hostname changes no longer propagate from
the system into the service, it is hence not suitable for services that need to take notice of system
- hostname changes dynamically.</para></listitem>
+ hostname changes dynamically.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
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>
+ implied.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
<constant>kernel.modules_disabled</constant> mechanism and
<filename>/proc/sys/kernel/modules_disabled</filename> documentation. 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>
+ <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is implied.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
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 <varname>ProtectControlGroups=</varname> is set, <varname>MountAPIVFS=yes</varname>
- is implied.</para></listitem>
+ is implied.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
<varname>DynamicUser=</varname> are used. It has no effect on IPC objects owned by the root user. Specifically,
this removes System V semaphores, as well as System V and POSIX shared memory segments and message queues. If
multiple units use the same user or group the IPC objects are removed when the last of these units is
- stopped. This setting is implied if <varname>DynamicUser=</varname> is set.</para></listitem>
+ stopped. This setting is implied if <varname>DynamicUser=</varname> is set.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
<varname>ProtectHome=</varname>, <varname>ReadOnlyPaths=</varname>, <varname>InaccessiblePaths=</varname>,
<varname>ReadWritePaths=</varname>, … — 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.</para></listitem>
+ used.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<varlistentry>
<para>Usually, it is best to leave this setting unmodified, and use higher level file system namespacing
options instead, in particular <varname>PrivateMounts=</varname>, see above.</para>
- </listitem>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
</variablelist>
projects / thirdparty / systemd.git / blobdiff