HALF ECHO LEARN / REFERENCE COLLECTION
v262.2man/systemd.exec.xml
Git blob: 151cff518a70dc4761d7305857f83b6888834572
Lines 1–1000 of 5,316
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="systemd.exec" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd.exec</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>systemd.exec</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd.exec</refname>
<refpurpose>Execution environment configuration</refpurpose>
</refnamediv>
<refsynopsisdiv>
<para><filename><replaceable>service</replaceable>.service</filename>,
<filename><replaceable>socket</replaceable>.socket</filename>,
<filename><replaceable>mount</replaceable>.mount</filename>,
<filename><replaceable>swap</replaceable>.swap</filename></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>Unit configuration files for services, sockets, mount points, and swap devices share a subset of
configuration options which define the execution environment of spawned processes.</para>
<para>This man page lists the configuration options shared by these four unit types. See
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for the common
options of all unit configuration files, and
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, and
<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
information on the specific unit configuration files. The execution specific configuration options are configured
in the [Service], [Socket], [Mount], or [Swap] sections, depending on the unit type.</para>
<para>In addition, options which control resources through Linux Control Groups (cgroups) are listed in
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Those options complement options listed here.</para>
</refsect1>
<refsect1>
<title>Implicit Dependencies</title>
<para>A few execution parameters result in additional, automatic dependencies to be added:</para>
<itemizedlist>
<listitem><para>Units with <varname>WorkingDirectory=</varname>, <varname>RootDirectory=</varname>,
<varname>RootImage=</varname>, <varname>RuntimeDirectory=</varname>, <varname>StateDirectory=</varname>,
<varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname> or
<varname>ConfigurationDirectory=</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></listitem>
<listitem><para>Units with <varname>PrivateTmp=yes</varname> automatically gain dependencies of type
<varname>Wants=</varname> and <varname>After=</varname> on all mounts required to access
<filename>/tmp/</filename> and <filename>/var/tmp/</filename> and an automatic
<varname>After=</varname> dependency on
<citerefentry><refentrytitle>systemd-tmpfiles-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
unless <varname>DefaultDependencies=no</varname> is specified. If
<varname>DefaultDependencies=no</varname> is specified, and a
<varname>RequiresMountsFor=/tmp/</varname>, <varname>WantsMountsFor=/tmp/</varname>,
<varname>After=tmp.mount</varname>, or <varname>RootDirectory=</varname>/<varname>RootImage=</varname>
are not specified, <varname>PrivateTmp=yes</varname> is converted to
<varname>PrivateTmp=disconnected</varname>.</para></listitem>
<listitem><para>Units with <varname>PrivateTmp=disconnected</varname> automatically gain dependencies
of type <varname>Wants=</varname> and <varname>After=</varname> on the mount required to access
<filename>/var/</filename>, unless <varname>DefaultDependencies=no</varname> and/or
<varname>RootDirectory=</varname>/<varname>RootImage=</varname> are specified. If
<varname>DefaultDependencies=no</varname> is specified, and a
<varname>RequiresMountsFor=/var/</varname>, <varname>WantsMountsFor=/var/</varname>,
<varname>After=var.mount</varname>, <varname>RootDirectory=</varname>/<varname>RootImage=</varname> are
not specified, the private mount on <filename>/tmp/</filename> is reused for
<filename>/var/tmp/</filename> by setting <varname>$TMPDIR</varname> appropriately.</para>
</listitem>
<listitem><para>Units whose standard output or error output is connected to <option>journal</option> or
<option>kmsg</option> (or their combinations with console output, see below) automatically acquire
dependencies of type <varname>After=</varname> on
<filename>systemd-journald.socket</filename>.</para></listitem>
<listitem><para>Units using <varname>LogNamespace=</varname> will automatically gain ordering and
requirement dependencies on the two socket units associated with
<filename>systemd-journald@.service</filename> instances.</para></listitem>
</itemizedlist>
</refsect1>
<!-- We do not have any default dependency here. -->
<refsect1>
<title>Paths</title>
<para>The following settings may be used to change a service's view of the filesystem. Please note that the paths
must be absolute and must not contain a <literal>..</literal> path component.</para>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>ExecSearchPath=</varname></term>
<listitem><para>Takes a colon separated list of absolute paths relative to which the executable
used by the <varname>Exec*=</varname> (e.g. <varname>ExecStart=</varname>,
<varname>ExecStop=</varname>, etc.) properties can be found. <varname>ExecSearchPath=</varname>
overrides <varname>$PATH</varname> if <varname>$PATH</varname> is not supplied by the user through
<varname>Environment=</varname>, <varname>EnvironmentFile=</varname> or
<varname>PassEnvironment=</varname>. Assigning an empty string removes previous assignments
and setting <varname>ExecSearchPath=</varname> to a value multiple times will append
to the previous setting.
</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>WorkingDirectory=</varname></term>
<listitem><para>Takes a directory path relative to the service's root directory specified by
<varname>RootDirectory=</varname>, or the special value <literal>~</literal>. Sets the working directory for
executed processes. If set to <literal>~</literal>, the home directory of the user specified in
<varname>User=</varname> is used. If not set, defaults to the root directory when systemd is running as a
system instance and the respective user's home directory if run as user. If the setting is prefixed with the
<literal>-</literal> character, a missing working directory is not considered fatal. If
<varname>RootDirectory=</varname>/<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>
<term><varname>RootDirectory=</varname></term>
<listitem><para>Takes a directory path relative to the host's root directory (i.e. the root of the system
running the service manager). Sets the root directory for executed processes, with the <citerefentry
project='man-pages'><refentrytitle>pivot_root</refentrytitle><manvolnum>2</manvolnum></citerefentry>
or <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
system call. If this is used, it must be ensured that the process binary and all its auxiliary files
are available in the new root. Note that setting this parameter might result in additional
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>
<para>If <varname>RootDirectory=</varname>/<varname>RootImage=</varname> are used together with
<varname>NotifyAccess=</varname> the notification socket is automatically mounted from the host into
the root environment, to ensure the notification interface can work correctly.</para>
<para>Note that services using <varname>RootDirectory=</varname>/<varname>RootImage=</varname> will
not be able to log via the syslog or journal protocols to the host logging infrastructure, unless the
relevant sockets are mounted from the host, specifically:</para>
<para>The host's
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>
file will be made available for the service (read-only) as
<filename>/run/host/os-release</filename>.
It will be updated automatically on soft reboot (see:
<citerefentry><refentrytitle>systemd-soft-reboot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
in case the service is configured to survive it.</para>
<example>
<title>Mounting logging sockets into root environment</title>
<programlisting>BindReadOnlyPaths=/dev/log /run/systemd/journal/socket /run/systemd/journal/stdout</programlisting>
</example>
<xi:include href="vpick.xml" xpointer="directory"/>
<xi:include href="system-or-user-ns.xml" xpointer="singular"/></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://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2
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
<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>
<para>Units making use of <varname>RootImage=</varname> automatically gain an
<varname>After=</varname> dependency on <filename>systemd-udevd.service</filename>.</para>
<para>The host's
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>
file will be made available for the service (read-only) as
<filename>/run/host/os-release</filename>.
It will be updated automatically on soft reboot (see:
<citerefentry><refentrytitle>systemd-soft-reboot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
in case the service is configured to survive it.</para>
<xi:include href="vpick.xml" xpointer="image"/>
<xi:include href="system-or-user-ns-mountfsd.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>RootImageOptions=</varname></term>
<listitem><para>Takes a comma-separated list of mount options that will be used on disk images specified by
<varname>RootImage=</varname>. Optionally a partition name can be prefixed, followed by colon, in
case the image has multiple partitions, otherwise partition name <literal>root</literal> is implied.
Options for multiple partitions can be specified in a single line with space separators. Assigning an empty
string removes previous assignments. For a list of valid mount options, please refer to
<citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
<para>Valid partition names follow the
<ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">
Discoverable Partitions Specification</ulink>:
<constant>root</constant>, <constant>usr</constant>, <constant>home</constant>, <constant>srv</constant>,
<constant>esp</constant>, <constant>xbootldr</constant>, <constant>tmp</constant>,
<constant>var</constant>.</para>
<xi:include href="system-only.xml" xpointer="singular"/>
<xi:include href="system-or-user-ns-mountfsd-mount-options.xml" xpointer="plural"/>
<xi:include href="system-or-user-ns-mountfsd-mount-options.xml" xpointer="example"/>
<xi:include href="version-info.xml" xpointer="v247"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>RootEphemeral=</varname></term>
<listitem><para>Takes a boolean argument. If enabled, executed processes will run in an ephemeral
copy of the root directory or root image. The ephemeral copy is placed in
<filename>/var/lib/systemd/ephemeral-trees/</filename> while the service is active and is cleaned up
when the service is stopped or restarted. If <varname>RootDirectory=</varname> is used and the root
directory is a subvolume, the ephemeral copy will be created by making a snapshot of the subvolume.
</para>
<para>To make sure making ephemeral copies can be made efficiently, the root directory or root image
should be located on the same filesystem as <filename>/var/lib/systemd/ephemeral-trees/</filename>.
When using <varname>RootEphemeral=</varname> with root directories,
<citerefentry project='url'><refentrytitle url='https://btrfs.readthedocs.io/en/latest/btrfs-man5.html'>btrfs</refentrytitle><manvolnum>5</manvolnum></citerefentry>
should be used as the filesystem and the root directory should ideally be a subvolume which
<command>systemd</command> can snapshot to make the ephemeral copy. For root images, a filesystem
with support for reflinks should be used to ensure an efficient ephemeral copy.</para>
<xi:include href="system-only.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>RootHash=</varname></term>
<listitem><para>Takes a data integrity (dm-verity) root hash specified in hexadecimal, or the path to a file
containing a root hash in ASCII hexadecimal format. This option enables data integrity checks using dm-verity,
if the used image contains the appropriate integrity data (see above) or if <varname>RootVerity=</varname> is used.
The specified hash must match the root hash of integrity data, and is usually at least 256 bits (and hence 64
formatted hexadecimal characters) long (in case of SHA256 for example). If this option is not specified, but
the image file carries the <literal>user.verity.roothash</literal> extended file attribute (see <citerefentry
project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry>), then the root
hash is read from it, also as formatted hexadecimal characters. If the extended file attribute is not found (or
is not supported by the underlying file system), but a file with the <filename>.roothash</filename> suffix is
found next to the image file, bearing otherwise the same name (except if the image has the
<filename>.raw</filename> suffix, in which case the root hash file must not have it in its name), the root hash
is read from it and automatically used, also as formatted hexadecimal characters.</para>
<para>If the disk image contains a separate <filename>/usr/</filename> partition it may also be
Verity protected, in which case the root hash may configured via an extended attribute
<literal>user.verity.usrhash</literal> or a <filename>.usrhash</filename> file adjacent to the disk
image. There's currently no option to configure the root hash for the <filename>/usr/</filename> file
system via the unit file directly.</para>
<xi:include href="system-or-user-ns-mountfsd.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v246"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>RootHashSignature=</varname></term>
<listitem><para>Takes a PKCS7 signature of the <varname>RootHash=</varname> option as a path to a
DER-encoded signature file, or as an ASCII base64 string encoding of a DER-encoded signature prefixed
by <literal>base64:</literal>. The dm-verity volume will only be opened if the signature of the root
hash is valid and signed by a public key present in the kernel keyring. If this option is not
specified, but a file with the <filename>.roothash.p7s</filename> suffix is found next to the image
file, bearing otherwise the same name (except if the image has the <filename>.raw</filename> suffix,
in which case the signature file must not have it in its name), the signature is read from it and
automatically used.</para>
<para>If the disk image contains a separate <filename>/usr/</filename> partition it may also be
Verity protected, in which case the signature for the root hash may configured via a
<filename>.usrhash.p7s</filename> file adjacent to the disk image. There's currently no option to
configure the root hash signature for the <filename>/usr/</filename> via the unit file
directly.</para>
<xi:include href="system-or-user-ns-mountfsd.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v246"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>RootVerity=</varname></term>
<listitem><para>Takes the path to a data integrity (dm-verity) file. This option enables data integrity checks
using dm-verity, if <varname>RootImage=</varname> is used and a root-hash is passed and if the used image itself
does not contain the integrity data. The integrity data must be matched by the root hash. If this option is not
specified, but a file with the <filename>.verity</filename> suffix is found next to the image file, bearing otherwise
the same name (except if the image has the <filename>.raw</filename> suffix, in which case the verity data file must
not have it in its name), the verity data is read from it and automatically used.</para>
<para>This option is supported only for disk images that contain a single file system, without an
enveloping partition table. Images that contain a GPT partition table should instead include both
root file system and matching Verity data in the same image, implementing the
<ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">
Discoverable Partitions Specification</ulink>.</para>
<xi:include href="system-or-user-ns-mountfsd.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v246"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>RootImagePolicy=</varname></term>
<term><varname>MountImagePolicy=</varname></term>
<term><varname>ExtensionImagePolicy=</varname></term>
<listitem><para>Takes an image policy string as per
<citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>
to use when mounting the disk images (DDI) specified in <varname>RootImage=</varname>,
<varname>MountImage=</varname>, <varname>ExtensionImage=</varname>, respectively. If not specified
the following policy string is the default for <varname>RootImagePolicy=</varname> and <varname>MountImagePolicy</varname>:</para>
<programlisting>root=verity+signed+encrypted+unprotected+absent: \
usr=verity+signed+encrypted+unprotected+absent: \
home=encrypted+unprotected+absent: \
srv=encrypted+unprotected+absent: \
tmp=encrypted+unprotected+absent: \
var=encrypted+unprotected+absent</programlisting>
<para>The default policy for <varname>ExtensionImagePolicy=</varname> is:</para>
<programlisting>root=verity+signed+encrypted+unprotected+absent: \
usr=verity+signed+encrypted+unprotected+absent</programlisting>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>RootMStack=</varname></term>
<listitem><para>Takes a path to a
<citerefentry><refentrytitle>systemd.mstack</refentrytitle><manvolnum>7</manvolnum></citerefentry>
directory encapsulating a mount stack consisting of layers and bind mounts. Similar to
<varname>RootDirectory=</varname> and <varname>RootImage=</varname> this runs the service off a
distinct root file system, in this case set up via <literal>overlayfs</literal>.</para>
<para>Since <filename>.mstack/</filename> directories may reference disk images (DDIs) similar device
policy extensions and dependencies are in effect when <varname>RootMStack=</varname> is used as are
if <varname>RootImage=</varname> is used.</para>
<xi:include href="vpick.xml" xpointer="image"/>
<xi:include href="system-or-user-ns-mountfsd.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v260"/></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>, <filename>/dev/</filename> and
<filename>/run/</filename> (as an empty <literal>tmpfs</literal>) 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 four 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 four 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>
<para>In order to allow propagating mounts at runtime in a safe manner, <filename>/run/systemd/propagate/</filename>
on the host will be used to set up new mounts, and <filename>/run/host/incoming/</filename> in the private namespace
will be used as an intermediate step to store them before being moved to the final mount point.</para>
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>BindLogSockets=</varname></term>
<listitem><para>Takes a boolean argument. If true, sockets from <citerefentry>
<refentrytitle>systemd-journald.socket</refentrytitle><manvolnum>8</manvolnum></citerefentry>
will be bind mounted into the mount namespace. This is particularly useful when a different instance
of <filename>/run/</filename> is employed, to make sure processes running in the namespace
can still make use of <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
<para>This option is implied when <varname>LogNamespace=</varname> is used,
when <varname>MountAPIVFS=yes</varname>, or when <varname>PrivateDevices=yes</varname> is used
in conjunction with either <varname>RootDirectory=</varname> or <varname>RootImage=</varname>.</para>
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>ProtectProc=</varname></term>
<listitem><para>Takes one of <literal>noaccess</literal>, <literal>invisible</literal>,
<literal>ptraceable</literal> or <literal>default</literal> (which it defaults to). When set, this
controls the <literal>hidepid=</literal> mount option of the <literal>procfs</literal> instance for
the unit that controls which directories with process metainformation
(<filename>/proc/<replaceable>PID</replaceable></filename>) are visible and accessible: when set to
<literal>noaccess</literal> the ability to access most of other users' process metadata in
<filename>/proc/</filename> is taken away for processes of the service. When set to
<literal>invisible</literal> processes owned by other users are hidden from
<filename>/proc/</filename>. If <literal>ptraceable</literal> all processes that cannot be
<function>ptrace()</function>'ed by a process are hidden to it. If <literal>default</literal> no
restrictions on <filename>/proc/</filename> access or visibility are made. For further details see
<ulink url="https://docs.kernel.org/filesystems/proc.html#mount-options">The /proc
Filesystem</ulink>. It is generally recommended to run most system services with this option set to
<literal>invisible</literal>. This option is implemented via file system namespacing, and thus cannot
be used with services that shall be able to install mount points in the host file system
hierarchy. Note that the root user is unaffected by this option, so to be effective it has to be used
together with <varname>User=</varname> or <varname>DynamicUser=yes</varname>, and also without the
<literal>CAP_SYS_PTRACE</literal> capability, which also allows a process to bypass this feature. It
cannot be used for services that need to access metainformation about other users' processes. This
option implies <varname>MountAPIVFS=</varname>.</para>
<para>If the kernel does not support per-mount point <option>hidepid=</option> mount options this
setting remains without effect, and the unit's processes will be able to access and see other process
as if the option was not used.</para>
<xi:include href="system-only.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v247"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>ProcSubset=</varname></term>
<listitem><para>Takes one of <literal>all</literal> (the default) and <literal>pid</literal>. If
<literal>pid</literal>, all files and directories not directly associated with process management and
introspection are made invisible in the <filename>/proc/</filename> file system configured for the
unit's processes. This controls the <literal>subset=</literal> mount option of the
<literal>procfs</literal> instance for the unit. For further details see <ulink
url="https://docs.kernel.org/filesystems/proc.html#mount-options">The /proc
Filesystem</ulink>. Note that Linux exposes various kernel APIs via <filename>/proc/</filename>,
which are made unavailable with this setting. Since these APIs are used frequently this option is
useful only in a few, specific cases, and is not suitable for most non-trivial programs.</para>
<para>Much like <varname>ProtectProc=</varname> above, this is implemented via file system mount
namespacing, and hence the same restrictions apply: it is only available to system services, it
disables mount propagation to the host mount table, and it implies
<varname>MountAPIVFS=</varname>. Also, like <varname>ProtectProc=</varname> this setting is gracefully
disabled if the used kernel does not support the <literal>subset=</literal> mount option of
<literal>procfs</literal>.</para>
<xi:include href="version-info.xml" xpointer="v247"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>BindPaths=</varname></term>
<term><varname>BindReadOnlyPaths=</varname></term>
<listitem><para>Configures unit-specific bind mounts. A bind mount makes a particular file or
directory available at an additional place in the unit's view of the file system. Any bind mounts
created with this option are specific to the unit, and are not visible in the host's mount
table. This option expects a whitespace separated list of bind mount definitions. Each definition
consists of a colon-separated triple of 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 path is omitted, the option
string must be omitted too. Each bind mount definition may be prefixed with <literal>-</literal>, in
which case it will be ignored when its source path does not exist or is not accessible.</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
settings may be used more than once, each usage appends to the unit's list of bind mounts. If the empty string
is assigned to either of these two options the entire list of bind mounts defined prior to this is reset. Note
that, in this case, both read-only and regular bind mounts are reset, regardless which of the two settings is
used.</para>
<para>Using this option implies that a mount namespace is allocated for the unit, i.e. it implies the
effect of <varname>PrivateMounts=</varname> (see below).</para>
<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>
<para>Note that the destination directory must exist or systemd must be able to create it. Thus, it
is not possible to use those options for mount points nested underneath paths specified in
<varname>InaccessiblePaths=</varname>, or under <filename>/home/</filename> and other protected
directories if <varname>ProtectHome=yes</varname> is
specified. <varname>TemporaryFileSystem=</varname> with <literal>:ro</literal> or
<varname>ProtectHome=tmpfs</varname> should be used instead.</para>
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>MountImages=</varname></term>
<listitem><para>This setting is similar to <varname>RootImage=</varname> in that it mounts a file
system hierarchy from a block device node or loopback file, but the destination directory can be
specified as well as mount options. This option expects a whitespace separated list of mount
definitions. Each definition consists of a colon-separated tuple of source path and destination
definitions, optionally followed by another colon and a list of mount options.</para>
<para>Mount options may be defined as a single comma-separated list of options, in which case they
will be implicitly applied to the root partition on the image, or a series of colon-separated tuples
of partition name and mount options. Valid partition names and mount options are the same as for
<varname>RootImageOptions=</varname> setting described above.</para>
<para>Each mount definition may be prefixed with <literal>-</literal>, in which case it will be
ignored when its source path does not exist. The source argument is a path to a block device node or
regular file. If source or destination contain a <literal>:</literal>, it needs to be escaped as
<literal>\:</literal>. The device node or file system image file needs to follow the same rules as
specified for <varname>RootImage=</varname>. Any mounts created with this option are specific to the
unit, and are not visible in the host's mount table.</para>
<para>These settings may be used more than once, each usage appends to the unit's list of mount
paths. If the empty string is assigned, the entire list of mount paths defined prior to this is
reset.</para>
<para>Note that the destination directory must exist or systemd must be able to create it. Thus, it
is not possible to use those options for mount points nested underneath paths specified in
<varname>InaccessiblePaths=</varname>, or under <filename>/home/</filename> and other protected
directories if <varname>ProtectHome=yes</varname> is specified.</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
<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>
<xi:include href="system-or-user-ns-mountfsd.xml" xpointer="singular"/>
<xi:include href="system-or-user-ns-mountfsd-mount-options.xml" xpointer="plural"/>
<xi:include href="system-or-user-ns-mountfsd-mount-options.xml" xpointer="example"/>
<xi:include href="version-info.xml" xpointer="v247"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>ExtensionImages=</varname></term>
<listitem><para>This setting is similar to <varname>MountImages=</varname> in that it mounts a file
system hierarchy from a block device node or loopback file, but instead of providing a destination
path, an overlay will be set up. This option expects a whitespace separated list of mount
definitions. Each definition consists of a source path, optionally followed by a colon and a list of
mount options.</para>
<para>A read-only OverlayFS will be set up on top of <filename>/usr/</filename> and
<filename>/opt/</filename> hierarchies for sysext images and <filename>/etc/</filename>
hierarchy for confext images. The order in which the images are listed will determine the
order in which the overlay is laid down: images specified first to last will result in overlayfs
layers bottom to top.</para>
<para>Mount options may be defined as a single comma-separated list of options, in which case they
will be implicitly applied to the root partition on the image, or a series of colon-separated tuples
of partition name and mount options. Valid partition names and mount options are the same as for
<varname>RootImageOptions=</varname> setting described above.</para>
<para>Each mount definition may be prefixed with <literal>-</literal>, in which case it will be
ignored when its source path does not exist. The source argument is a path to a block device node or
regular file. If the source path contains a <literal>:</literal>, it needs to be escaped as
<literal>\:</literal>. The device node or file system image file needs to follow the same rules as
specified for <varname>RootImage=</varname>. Any mounts created with this option are specific to the
unit, and are not visible in the host's mount table.</para>
<para>These settings may be used more than once, each usage appends to the unit's list of image
paths. If the empty string is assigned, the entire list of mount paths defined prior to this is
reset.</para>
<para>Each sysext image must carry a <filename>/usr/lib/extension-release.d/extension-release.IMAGE</filename>
file while each confext image must carry a <filename>/etc/extension-release.d/extension-release.IMAGE</filename>
file, with the appropriate metadata which matches <varname>RootImage=</varname>/<varname>RootDirectory=</varname>
or the host. See:
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
To disable the safety check that the extension-release file name matches the image file name, the
<varname>x-systemd.relax-extension-release-check</varname> mount option may be appended.</para>
<para>If a service employs this option with
<citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
and has <option>RefreshOnReload=extensions</option> enabled (the default), the confexts will
be refreshed to pick up any changes on service reload. This only applies to confext extensions.
Note that in case a service has this configuration enabled at first, and then it is subsequently
removed in an update followed by a daemon-reload operation, reloading the confexts will be a no-op,
and a full service restart is required instead. See
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
also for details.</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
<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>
<xi:include href="vpick.xml" xpointer="image"/>
<xi:include href="system-or-user-ns-mountfsd.xml" xpointer="singular"/>
<xi:include href="system-or-user-ns-mountfsd-mount-options.xml" xpointer="plural"/>
<xi:include href="system-or-user-ns-mountfsd-mount-options.xml" xpointer="example"/>
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>ExtensionDirectories=</varname></term>
<listitem><para>This setting is similar to <varname>BindReadOnlyPaths=</varname> in that it mounts a file
system hierarchy from a directory, but instead of providing a destination path, an overlay will be set
up. This option expects a whitespace separated list of source directories.</para>
<para>A read-only OverlayFS will be set up on top of <filename>/usr/</filename> and
<filename>/opt/</filename> hierarchies for sysext images and <filename>/etc/</filename>
hierarchy for confext images. The order in which the directories are listed will determine
the order in which the overlay is laid down: directories specified first to last will result in overlayfs
layers bottom to top.</para>
<para>Each directory listed in <varname>ExtensionDirectories=</varname> may be prefixed with <literal>-</literal>,
in which case it will be ignored when its source path does not exist. Any mounts created with this option are
specific to the unit, and are not visible in the host's mount table.</para>
<para>These settings may be used more than once, each usage appends to the unit's list of directories
paths. If the empty string is assigned, the entire list of mount paths defined prior to this is
reset.</para>
<para>Each sysext directory must contain a <filename>/usr/lib/extension-release.d/extension-release.IMAGE</filename>
file while each confext directory must carry a <filename>/etc/extension-release.d/extension-release.IMAGE</filename>
file, with the appropriate metadata which matches <varname>RootImage=</varname>/<varname>RootDirectory=</varname>
or the host. See:
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<para>If a service employs this option with
<citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
and has <option>RefreshOnReload=extensions</option> enabled (the default), the confexts will
be refreshed to pick up any changes on service reload. This only applies to confext extensions.
Note that in case a service has this configuration enabled at first, and then it is subsequently
removed in an update followed by a daemon-reload operation, reloading the confexts will be a no-op,
and a full service restart is required instead. See
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
also for details.</para>
<para>Note that usage from user units requires overlayfs support in unprivileged user namespaces,
which was first introduced in kernel v5.11.</para>
<xi:include href="vpick.xml" xpointer="directory"/>
<xi:include href="system-or-user-ns.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>User/Group Identity</title>
<xi:include href="system-only.xml" xpointer="plural"/>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>User=</varname></term>
<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 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>
<para>Note that this enforces only weak restrictions on the user/group name syntax, but will generate
warnings in many cases where user/group names do not adhere to the following rules: the specified
name should 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 and
<literal>_</literal> (i.e. digits 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 made in
order to avoid ambiguities and to ensure user/group names and unit files remain portable among Linux
systems. For further details on the names accepted and the names warned about see <ulink
url="https://systemd.io/USER_NAMES">User/Group Name Syntax</ulink>.</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. If the user does not exist by then
program invocation will fail.</para>
<para>If the <varname>User=</varname> setting is used the supplementary group list is initialized
from the specified user's default group list, as defined in the system's user and group
database. Additional groups may be configured through the <varname>SupplementaryGroups=</varname>
setting (see below).</para></listitem>
</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
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> is implied (and cannot be turned off). 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, unless
<varname>PrivateTmp=</varname> is manually set to <literal>true</literal>, <literal>disconnected</literal>
would be implied. This ensures that a unit making use of dynamic user/group allocation cannot
leave files around after unit termination. Furthermore
<varname>NoNewPrivileges=</varname> and <varname>RestrictSUIDSGID=</varname> are implicitly enabled
(and cannot be disabled), to ensure that processes invoked cannot take benefit or create SUID/SGID
files or directories. 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 allow-listed using <varname>ReadWritePaths=</varname>, but care must be taken so that
UID/GID recycling does not 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. Note that this option is currently incompatible with D-Bus policies, thus a service using
this option may currently not allocate a D-Bus service name (note that this does not affect calling
into other D-Bus services). Defaults to off.</para>
<xi:include href="version-info.xml" xpointer="v232"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>SupplementaryGroups=</varname></term>
<listitem><para>Sets the supplementary Unix groups the processes are executed as. This takes a space-separated
list of group names or IDs. This option may be specified more than once, in which case all listed groups are
set as supplementary groups. When the empty string is assigned, the list of supplementary groups is reset, and
all assignments prior to this one will have no effect. In any way, this option does not override, but extends
the list of supplementary groups configured in the system group database for the user. This does not affect
commands prefixed with <literal>+</literal>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>SetLoginEnvironment=</varname></term>
<listitem><para>Takes a boolean parameter that controls whether to set the <varname>$HOME</varname>,
<varname>$LOGNAME</varname>, and <varname>$SHELL</varname> environment variables. If not set, this
defaults to true if <varname>User=</varname>, <varname>DynamicUser=</varname> or
<varname>PAMName=</varname> are set, false otherwise. If set to true, the variables will always be
set for system services, i.e. even when the default user <literal>root</literal> is used. If set to
false, the mentioned variables are not set by the service manager, no matter whether
<varname>User=</varname>, <varname>DynamicUser=</varname>, or <varname>PAMName=</varname> are used or
not. This option normally has no effect on services of the per-user service manager, since in that
case these variables are typically inherited from user manager's own environment anyway.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>PAMName=</varname></term>
<listitem><para>Sets the PAM service name to set up a session as. If set, the executed process will be
registered as a PAM session under the specified service name. This is only useful in conjunction with the
<varname>User=</varname> setting, and is otherwise ignored. If not set, no PAM session will be opened for the
executed processes. See <citerefentry
project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
details.</para>
<para>Note that for each unit making use of this option a PAM session handler process will be maintained as
part of the unit and stays around as long as the unit is active, to ensure that appropriate actions can be
taken when the unit and hence the PAM session terminates. This process is named <literal>(sd-pam)</literal> and
is an immediate child process of the unit's main process.</para>
<para>Note that when this option is used for a unit it is very likely (depending on PAM configuration) that the
main unit process will be migrated to its own session scope unit when it is activated. This process will hence
be associated with two units: the unit it was originally started from (and for which
<varname>PAMName=</varname> was configured), and the session scope unit. Any child processes of that process
will however be associated with the session scope unit only. This has implications when used in combination
with <varname>NotifyAccess=</varname><option>all</option>, as these child processes will not be able to affect
changes in the original unit through notification messages. These messages will be considered belonging to the
session scope unit and not the original unit. It is hence not recommended to use <varname>PAMName=</varname> in
combination with <varname>NotifyAccess=</varname><option>all</option>.</para>
<para>If a PAM module interactively requests input (a password or suchlike) it will be attempted to
be read from a service credential (as configured via <varname>SetCredential=</varname>,
<varname>ImportCredential=</varname> and related calls) under the name
<varname>pam.authtok.<replaceable>pamservice</replaceable></varname>, where
<replaceable>pamservice</replaceable> is replaced by the PAM service name as configured with
<varname>PAMName=</varname>. (Note that the credential remains accessible for the runtime of the
service!) If no matching credential is set, the user is prompted for it interactively via the <ulink
url="https://systemd.io/PASSWORD_AGENTS">Password Agent</ulink> logic.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Capabilities</title>
<xi:include href="system-or-user-ns.xml" xpointer="plural"/>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>CapabilityBoundingSet=</varname></term>
<listitem><para>Controls which capabilities to include in the capability bounding set for the
executed process. See <citerefentry
project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for details. Takes a whitespace-separated list of capability names,
e.g. <constant>CAP_SYS_ADMIN</constant>, <constant>CAP_DAC_OVERRIDE</constant>,
<constant>CAP_SYS_PTRACE</constant>. Capabilities listed will be included in the bounding set, all
others are removed. If the list of capabilities is prefixed with <literal>~</literal>, all but the
listed capabilities will be included, the effect of the assignment inverted. Note that this option
also affects the respective capabilities in the effective, permitted and inheritable capability
sets. If this option is not used, the capability bounding set is not modified on process execution,
hence no limits on the capabilities of the process are enforced. This option may appear more than
once, in which case the bounding sets are merged by <constant>OR</constant>, or by
<constant>AND</constant> if the lines are prefixed with <literal>~</literal> (see below). If the
empty string is assigned to this option, the bounding set is reset to the empty capability set, and
all prior settings have no effect. If set to <literal>~</literal> (without any further argument),
the bounding set is reset to the full set of available capabilities, also undoing any previous
settings. This does not affect commands prefixed with <literal>+</literal>.</para>
<para>Use
<citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
<command>capability</command> command to retrieve a list of capabilities defined on the local
system.</para>
<para>Example: if a unit has the following,
<programlisting>CapabilityBoundingSet=CAP_A CAP_B
CapabilityBoundingSet=CAP_B CAP_C</programlisting>
then <constant index='false'>CAP_A</constant>, <constant index='false'>CAP_B</constant>, and
<constant index='false'>CAP_C</constant> are set. If the second line is prefixed with
<literal>~</literal>, e.g.,
<programlisting>CapabilityBoundingSet=CAP_A CAP_B
CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
then, only <constant index='false'>CAP_A</constant> is set.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>AmbientCapabilities=</varname></term>
<listitem><para>Controls which capabilities to include in the ambient capability set for the executed
process. Takes a whitespace-separated list of capability names, e.g. <constant>CAP_SYS_ADMIN</constant>,
<constant>CAP_DAC_OVERRIDE</constant>, <constant>CAP_SYS_PTRACE</constant>. This option may appear more than
once, in which case the ambient capability sets are merged (see the above examples in
<varname>CapabilityBoundingSet=</varname>). If the list of capabilities is prefixed with <literal>~</literal>,
all but the listed capabilities will be included, the effect of the assignment inverted. If the empty string is
assigned to this option, the ambient capability set is reset to the empty capability set, and all prior
settings have no effect. If set to <literal>~</literal> (without any further argument), the ambient capability
set is reset to the full set of available capabilities, also undoing any previous settings. Note that adding
capabilities to the ambient capability set adds them to the process's inherited capability set.</para>
<para>Ambient capability sets are useful if you want to execute a process as a non-privileged user but
still want to give it some capabilities. Note that, in this case, option <constant>keep-caps</constant>
is automatically added to <varname>SecureBits=</varname> to retain the capabilities over the user
change. <varname>AmbientCapabilities=</varname> does not affect commands prefixed with
<literal>+</literal>.</para>
<xi:include href="version-info.xml" xpointer="v229"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Security</title>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>NoNewPrivileges=</varname></term>
<listitem><para>Takes a boolean argument. If true, ensures that the service process and all its
children can never gain new privileges through <function>execve()</function> (e.g. via setuid or
setgid bits, or filesystem capabilities). This is the simplest and most effective way to ensure that
a process and its children can never elevate privileges again. Defaults to false. In case the service
will be run in a new mount namespace anyway and SELinux is disabled, all file systems are mounted with
<constant>MS_NOSUID</constant> flag. Also see <ulink
url="https://docs.kernel.org/userspace-api/no_new_privs.html">No New Privileges Flag</ulink>.
</para>
<para>Note that this setting only has an effect on the unit's processes themselves (or any processes
directly or indirectly forked off them). It has no effect on processes potentially invoked on request
of them through tools such as <citerefentry
project='man-pages'><refentrytitle>at</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry
project='man-pages'><refentrytitle>crontab</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>, or
arbitrary IPC services.</para>
<xi:include href="version-info.xml" xpointer="v187"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>SecureBits=</varname></term>
<listitem><para>Controls the secure bits set for the executed process. Takes a space-separated combination of
options from the following list: <option>keep-caps</option>, <option>keep-caps-locked</option>,
<option>no-setuid-fixup</option>, <option>no-setuid-fixup-locked</option>, <option>noroot</option>,
<option>noroot-locked</option>, <option>no-cap-ambient-raise</option>, <option>no-cap-ambient-raise-locked</option>,
<option>exec-restrict-file</option>, <option>exec-restrict-file-locked</option>,
<option>exec-deny-interactive</option>, and <option>exec-deny-interactive-locked</option>.
This option may appear more than once, in which case the secure bits are
ORed. If the empty string is assigned to this option, the bits are reset to 0. This does not affect commands
prefixed with <literal>+</literal>. See <citerefentry
project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
and <ulink url="https://docs.kernel.org/userspace-api/check_exec.html">Executability check</ulink> for
details.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Mandatory Access Control</title>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>SELinuxContext=</varname></term>
<listitem><para>Set the SELinux security context of the executed process. If set, this will override the
automated domain transition. However, the policy still needs to authorize the transition. This directive is
ignored if SELinux is disabled. If prefixed by <literal>-</literal>, failing to set the SELinux
security context will be ignored, but it is still possible that the subsequent
<function>execve()</function> may fail if the policy does not allow the transition for the
non-overridden context. This does not affect commands prefixed with <literal>+</literal>. See
<citerefentry
project='die-net'><refentrytitle>setexeccon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for details.</para>
<xi:include href="version-info.xml" xpointer="v209"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>AppArmorProfile=</varname></term>
<listitem><para>Takes a profile name as argument. The process executed by the unit will switch to
this profile when started. Profiles must already be loaded in the kernel, or the unit will fail. If
prefixed by <literal>-</literal>, all errors will be ignored. This setting has no effect if AppArmor
is not enabled. This setting does not affect commands prefixed with <literal>+</literal>.</para>
<xi:include href="system-only.xml" xpointer="singular"/>