will also gain an automatic <varname>After=</varname> dependency on
<citerefentry><refentrytitle>systemd-tmpfiles-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
- <listitem><para>Units whose standard output or error output is connected to <option>journal</option>,
- <option>syslog</option> or <option>kmsg</option> (or their combinations with console output, see below)
- automatically acquire dependencies of type <varname>After=</varname> on
+ <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>
<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
+ <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://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions
Specification</ulink>.</para>
<para>When <varname>DevicePolicy=</varname> is set to <literal>closed</literal> or
<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>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></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 number can be prefixed, followed by colon, in
+ case the image has multiple partitions, otherwise partition number 0 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><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></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>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RootHashSignature=</varname></term>
+
+ <listitem><para>Takes a PKCS7 formatted binary signature of the <varname>RootHash=</varname> option as a path
+ to a DER encoded signature file or as an ASCII base64 string encoding of the DER encoded signature, prefixed
+ by <literal>base64:</literal>. The dm-verity volume will only be opened if the signature of the root hash
+ signature is valid and created 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>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></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 contains 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://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partition Specification</ulink>.</para>
+
<xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
<xi:include href="system-only.xml" xpointer="singular"/></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
+ directory. 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-only.xml" xpointer="singular"/></listitem>
+ </varlistentry>
</variablelist>
</refsect1>
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 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>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.</para>
+ 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
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 whitelisted using <varname>ReadWritePaths=</varname>, but care must be taken so that
+ have to be allow-listed 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
<para>Example: if a unit has the following,
<programlisting>CapabilityBoundingSet=CAP_A CAP_B
CapabilityBoundingSet=CAP_B CAP_C</programlisting>
- then <constant>CAP_A</constant>, <constant>CAP_B</constant>, and <constant>CAP_C</constant> are set.
- If the second line is prefixed with <literal>~</literal>, e.g.,
+ 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>CAP_A</constant> is set.</para></listitem>
+ then, only <constant index='false'>CAP_A</constant> is set.</para></listitem>
</varlistentry>
<varlistentry>
<varname>SystemCallFilter=</varname>, <varname>SystemCallArchitectures=</varname>,
<varname>RestrictAddressFamilies=</varname>, <varname>RestrictNamespaces=</varname>,
<varname>PrivateDevices=</varname>, <varname>ProtectKernelTunables=</varname>,
- <varname>ProtectKernelModules=</varname>, <varname>MemoryDenyWriteExecute=</varname>,
- <varname>RestrictRealtime=</varname>, <varname>RestrictSUIDSGID=</varname>,
- <varname>DynamicUser=</varname> or <varname>LockPersonality=</varname> are specified. Note that even
- if this setting is overridden by them, <command>systemctl show</command> shows the original value of
- this setting. Also see <ulink
- url="https://www.kernel.org/doc/html/latest/userspace-api/no_new_privs.html">No New Privileges
+ <varname>ProtectKernelModules=</varname>, <varname>ProtectKernelLogs=</varname>,
+ <varname>ProtectClock=</varname>, <varname>MemoryDenyWriteExecute=</varname>,
+ <varname>RestrictRealtime=</varname>, <varname>RestrictSUIDSGID=</varname>, <varname>DynamicUser=</varname>
+ or <varname>LockPersonality=</varname> are specified. Note that even if this setting is overridden by them,
+ <command>systemctl show</command> shows the original value of this setting.
+ Also see <ulink url="https://www.kernel.org/doc/html/latest/userspace-api/no_new_privs.html">No New Privileges
Flag</ulink>.</para></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. This result in a non
- operation if AppArmor is not enabled. If prefixed by <literal>-</literal>, all errors will be ignored. This
- does not affect commands prefixed with <literal>+</literal>.</para></listitem>
+ <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 not affect commands prefixed with <literal>+</literal>.</para>
+ </listitem>
</varlistentry>
<varlistentry>
<term><varname>LimitRTTIME=</varname></term>
<listitem><para>Set soft and hard limits on various resources for executed processes. See
- <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details on
- the resource limit concept. Resource limits may be specified in two formats: either as single value to set a
- specific soft and hard limit to the same value, or as colon-separated pair <option>soft:hard</option> to set
- both limits individually (e.g. <literal>LimitAS=4G:16G</literal>). Use the string <option>infinity</option> to
- configure no limit on a specific resource. The multiplicative suffixes K, M, G, T, P and E (to the base 1024)
- may be used for resource limits measured in bytes (e.g. LimitAS=16G). For the limits referring to time values,
- the usual time units ms, s, min, h and so on may be used (see
+ <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
+ details on the resource limit concept. Resource limits may be specified in two formats: either as
+ single value to set a specific soft and hard limit to the same value, or as colon-separated pair
+ <option>soft:hard</option> to set both limits individually (e.g. <literal>LimitAS=4G:16G</literal>).
+ Use the string <option>infinity</option> to configure no limit on a specific resource. The
+ multiplicative suffixes K, M, G, T, P and E (to the base 1024) may be used for resource limits
+ measured in bytes (e.g. <literal>LimitAS=16G</literal>). For the limits referring to time values, the
+ usual time units ms, s, min, h and so on may be used (see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
- details). Note that if no time unit is specified for <varname>LimitCPU=</varname> the default unit of seconds
- is implied, while for <varname>LimitRTTIME=</varname> the default unit of microseconds is implied. Also, note
- that the effective granularity of the limits might influence their enforcement. For example, time limits
- specified for <varname>LimitCPU=</varname> will be rounded up implicitly to multiples of 1s. For
- <varname>LimitNICE=</varname> the value may be specified in two syntaxes: if prefixed with <literal>+</literal>
- or <literal>-</literal>, the value is understood as regular Linux nice value in the range -20..19. If not
- prefixed like this the value is understood as raw resource limit parameter in the range 0..40 (with 0 being
- equivalent to 1).</para>
-
- <para>Note that most process resource limits configured with these options are per-process, and processes may
- fork in order to acquire a new set of resources that are accounted independently of the original process, and
- may thus escape limits set. Also note that <varname>LimitRSS=</varname> is not implemented on Linux, and
- setting it has no effect. Often it is advisable to prefer the resource controls listed in
+ details). Note that if no time unit is specified for <varname>LimitCPU=</varname> the default unit of
+ seconds is implied, while for <varname>LimitRTTIME=</varname> the default unit of microseconds is
+ implied. Also, note that the effective granularity of the limits might influence their
+ enforcement. For example, time limits specified for <varname>LimitCPU=</varname> will be rounded up
+ implicitly to multiples of 1s. For <varname>LimitNICE=</varname> the value may be specified in two
+ syntaxes: if prefixed with <literal>+</literal> or <literal>-</literal>, the value is understood as
+ regular Linux nice value in the range -20..19. If not prefixed like this the value is understood as
+ raw resource limit parameter in the range 0..40 (with 0 being equivalent to 1).</para>
+
+ <para>Note that most process resource limits configured with these options are per-process, and
+ processes may fork in order to acquire a new set of resources that are accounted independently of the
+ original process, and may thus escape limits set. Also note that <varname>LimitRSS=</varname> is not
+ implemented on Linux, and setting it has no effect. Often it is advisable to prefer the resource
+ controls listed in
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- over these per-process limits, as they apply to services as a whole, may be altered dynamically at runtime, and
- are generally more expressive. For example, <varname>MemoryLimit=</varname> is a more powerful (and working)
- replacement for <varname>LimitRSS=</varname>.</para>
-
- <para>For system units these resource limits may be chosen freely. For user units however (i.e. units run by a
- per-user instance of
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>), these limits are
- bound by (possibly more restrictive) per-user limits enforced by the OS.</para>
+ over these per-process limits, as they apply to services as a whole, may be altered dynamically at
+ runtime, and are generally more expressive. For example, <varname>MemoryMax=</varname> is a more
+ powerful (and working) replacement for <varname>LimitRSS=</varname>.</para>
<para>Resource limits not configured explicitly for a unit default to the value configured in the various
<varname>DefaultLimitCPU=</varname>, <varname>DefaultLimitFSIZE=</varname>, … options available in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, and –
if not configured there – the kernel or per-user defaults, as defined by the OS (the latter only for user
- services, see above).</para>
+ services, see below).</para>
+
+ <para>For system units these resource limits may be chosen freely. When these settings are configured
+ in a user service (i.e. a service run by the per-user instance of the service manager) they cannot be
+ used to raise the limits above those set for the user manager itself when it was first invoked, as
+ the user's service manager generally lacks the privileges to do so. In user context these
+ configuration options are hence only useful to lower the limits passed in or to raise the soft limit
+ to the maximum of the hard limit as configured for the user. To raise the user's limits further, the
+ available configuration mechanisms differ between operating systems, but typically require
+ privileges. In most cases it is possible to configure higher per-user resource limits via PAM or by
+ setting limits on the system service encapsulating the user's service manager, i.e. the user's
+ instance of <filename>user@.service</filename>. After making such changes, make sure to restart the
+ user's service manager.</para>
<table>
<title>Resource limit directives, their equivalent <command>ulimit</command> shell commands and the unit used</title>
<term><varname>UMask=</varname></term>
<listitem><para>Controls the file mode creation mask. Takes an access mode in octal notation. See
- <citerefentry><refentrytitle>umask</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details. Defaults
- to 0022.</para></listitem>
+ <citerefentry><refentrytitle>umask</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
+ details. Defaults to 0022 for system units. For units of the user service manager the default value
+ is inherited from the user instance (whose default is inherited from the system service manager, and
+ thus also is 0022). Hence changing the default value of a user instance, either via
+ <varname>UMask=</varname> or via a PAM module, will affect the user instance itself and all user
+ units started by the user instance unless a user unit has specified its own
+ <varname>UMask=</varname>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>CoredumpFilter=</varname></term>
+
+ <listitem><para>Controls which types of memory mappings will be saved if the process dumps core
+ (using the <filename>/proc/<replaceable>pid</replaceable>/coredump_filter</filename> file). Takes a
+ whitespace-separated combination of mapping type names or numbers (with the default base 16). Mapping
+ type names are <constant>private-anonymous</constant>, <constant>shared-anonymous</constant>,
+ <constant>private-file-backed</constant>, <constant>shared-file-backed</constant>,
+ <constant>elf-headers</constant>, <constant>private-huge</constant>,
+ <constant>shared-huge</constant>, <constant>private-dax</constant>, <constant>shared-dax</constant>,
+ and the special values <constant>all</constant> (all types) and <constant>default</constant> (the
+ kernel default of <literal><constant>private-anonymous</constant>
+ <constant>shared-anonymous</constant> <constant>elf-headers</constant>
+ <constant>private-huge</constant></literal>). See
+ <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for the meaning of the mapping types. When specified multiple times, all specified masks are
+ ORed. When not set, or if the empty value is assigned, the inherited value is not changed.</para>
+
+ <example>
+ <title>Add DAX pages to the dump filter</title>
+
+ <programlisting>CoredumpFilter=default private-dax shared-dax</programlisting>
+ </example>
+ </listitem>
</varlistentry>
<varlistentry>
<term><varname>CPUAffinity=</varname></term>
<listitem><para>Controls the CPU affinity of the executed processes. Takes a list of CPU indices or ranges
- separated by either whitespace or commas. CPU ranges are specified by the lower and upper CPU indices separated
- by a dash. This option may be specified more than once, in which case the specified CPU affinity masks are
- merged. If the empty string is assigned, the mask is reset, all assignments prior to this will have no
- effect. See
+ separated by either whitespace or commas. Alternatively, takes a special "numa" value in which case systemd
+ automatically derives allowed CPU range based on the value of <varname>NUMAMask=</varname> option. CPU ranges
+ are specified by the lower and upper CPU indices separated by a dash. This option may be specified more than
+ once, in which case the specified CPU affinity masks are merged. If the empty string is assigned, the mask
+ is reset, all assignments prior to this will have no effect. See
<citerefentry><refentrytitle>sched_setaffinity</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
details.</para></listitem>
</varlistentry>
in <varname>NUMAMask=</varname>. For more details on each policy please see,
<citerefentry><refentrytitle>set_mempolicy</refentrytitle><manvolnum>2</manvolnum></citerefentry>. For overall
overview of NUMA support in Linux see,
- <citerefentry><refentrytitle>numa</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ <citerefentry project='man-pages'><refentrytitle>numa</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
<para>Also note that some sandboxing functionality is generally not available in user services (i.e. services run
by the per-user service manager). Specifically, the various settings requiring file system namespacing support
(such as <varname>ProtectSystem=</varname>) are not available, as the underlying kernel functionality is only
- accessible to privileged processes.</para>
+ accessible to privileged processes. However, most namespacing settings, that will not work on their own in user
+ services, will work when used in conjunction with <varname>PrivateUsers=</varname><option>true</option>.</para>
<variablelist class='unit-directives'>
<term><varname>ProtectSystem=</varname></term>
<listitem><para>Takes a boolean argument or the special values <literal>full</literal> or
- <literal>strict</literal>. If true, mounts the <filename>/usr</filename> and <filename>/boot</filename>
- directories read-only for processes invoked by this unit. If set to <literal>full</literal>, the
- <filename>/etc</filename> directory is mounted read-only, too. If set to <literal>strict</literal> the entire
- file system hierarchy is mounted read-only, except for the API file system subtrees <filename>/dev</filename>,
+ <literal>strict</literal>. If true, mounts the <filename>/usr</filename> and the boot loader
+ directories (<filename>/boot</filename> and <filename>/efi</filename>) read-only for processes
+ invoked by this unit. If set to <literal>full</literal>, the <filename>/etc</filename> directory is
+ mounted read-only, too. If set to <literal>strict</literal> the entire file system hierarchy is
+ mounted read-only, except for the API file system subtrees <filename>/dev</filename>,
<filename>/proc</filename> and <filename>/sys</filename> (protect these directories using
<varname>PrivateDevices=</varname>, <varname>ProtectKernelTunables=</varname>,
<varname>ProtectControlGroups=</varname>). This setting ensures that any modification of the vendor-supplied
<varname>RootDirectory=</varname> or <varname>RootImage=</varname> these paths always reside on the host and
are mounted from there into the unit's file system namespace.</para>
- <para>If <varname>DynamicUser=</varname> is used in conjunction with <varname>StateDirectory=</varname>,
- <varname>CacheDirectory=</varname> and <varname>LogsDirectory=</varname> is slightly altered: the directories
- are created below <filename>/var/lib/private</filename>, <filename>/var/cache/private</filename> and
+ <para>If <varname>DynamicUser=</varname> is used in conjunction with
+ <varname>StateDirectory=</varname>, the logic for <varname>CacheDirectory=</varname> and
+ <varname>LogsDirectory=</varname> is slightly altered: the directories are created below
+ <filename>/var/lib/private</filename>, <filename>/var/cache/private</filename> and
<filename>/var/log/private</filename>, respectively, which are host directories made inaccessible to
- unprivileged users, which ensures that access to these directories cannot be gained through dynamic user ID
- recycling. Symbolic links are created to hide this difference in behaviour. Both from perspective of the host
- and from inside the unit, the relevant directories hence always appear directly below
- <filename>/var/lib</filename>, <filename>/var/cache</filename> and <filename>/var/log</filename>.</para>
+ unprivileged users, which ensures that access to these directories cannot be gained through dynamic
+ user ID recycling. Symbolic links are created to hide this difference in behaviour. Both from
+ perspective of the host and from inside the unit, the relevant directories hence always appear
+ directly below <filename>/var/lib</filename>, <filename>/var/cache</filename> and
+ <filename>/var/log</filename>.</para>
<para>Use <varname>RuntimeDirectory=</varname> to manage one or more runtime directories for the unit and bind
their lifetime to the daemon runtime. This is particularly useful for unprivileged daemons that cannot create
<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
+
+ <filename index='false'>/run/foo/bar</filename>, and <filename index='false'>/run/baz</filename>. The
+ directories <filename index='false'>/run/foo/bar</filename> and
+ <filename index='false'>/run/baz</filename> except <filename index='false'>/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>
clean …</command>, see
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
details. Takes the usual time values and defaults to <constant>infinity</constant>, i.e. by default
- no time-out is applied. If a time-out is configured the clean operation will be aborted forcibly when
- the time-out is reached, potentially leaving resources on disk.</para></listitem>
+ no timeout is applied. If a timeout is configured the clean operation will be aborted forcibly when
+ the timeout is reached, potentially leaving resources on disk.</para></listitem>
</varlistentry>
<varlistentry>
contain symlinks, they are resolved relative to the root directory set with
<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
- reading only, writing will be refused even if the usual file access controls would permit this. Nest
- <varname>ReadWritePaths=</varname> inside of <varname>ReadOnlyPaths=</varname> in order to provide writable
- subdirectories within read-only directories. Use <varname>ReadWritePaths=</varname> in order to whitelist
- specific paths for write access if <varname>ProtectSystem=strict</varname> is used.</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 reading only, writing will be refused even if the usual file access controls would
+ permit this. Nest <varname>ReadWritePaths=</varname> inside of <varname>ReadOnlyPaths=</varname> in
+ order to provide writable subdirectories within read-only directories. Use
+ <varname>ReadWritePaths=</varname> in order to allow-list specific paths for write access if
+ <varname>ProtectSystem=strict</varname> is used.</para>
<para>Paths listed in <varname>InaccessiblePaths=</varname> will be made inaccessible for processes inside
the namespace along with everything below them in the file system hierarchy. This may be more restrictive than
<term><varname>PrivateTmp=</varname></term>
<listitem><para>Takes a boolean argument. If true, sets up a new file system namespace for the executed
- processes and mounts private <filename>/tmp</filename> and <filename>/var/tmp</filename> directories inside it
- that is not shared by processes outside of the namespace. This is useful to secure access to temporary files of
+ processes and mounts private <filename>/tmp/</filename> and <filename>/var/tmp/</filename> directories inside it
+ that are not shared by processes outside of the namespace. This is useful to secure access to temporary files of
the process, but makes sharing between processes via <filename>/tmp</filename> or <filename>/var/tmp</filename>
impossible. If this is enabled, all temporary files created by a service in these directories will be removed
after the service is stopped. Defaults to false. It is possible to run two or more units within the same
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>When this setting is set up by a per-user instance of the service manager, the mapping of the
+ <literal>root</literal> user and group to itself is omitted (unless the user manager is root).
+ Additionally, in the per-user instance manager case, the
+ user namespace will be set up before most other namespaces. This means that combining
+ <varname>PrivateUsers=</varname><option>true</option> with other namespaces will enable use of features not
+ normally supported by the per-user instances of the service manager.</para>
+
<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
<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>
-
- <xi:include href="system-only.xml" xpointer="singular"/></listitem>
+ security.</para></listitem>
</varlistentry>
<varlistentry>
<xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>ProtectClock=</varname></term>
+
+ <listitem><para>Takes a boolean argument. If set, writes to the hardware clock or system clock will be denied.
+ It is recommended to turn this on for most services that do not need modify the clock. Defaults to off. Enabling
+ this option removes <constant>CAP_SYS_TIME</constant> and <constant>CAP_WAKE_ALARM</constant> from the
+ capability bounding set for this unit, installs a system call filter to block calls that can set the
+ clock, and <varname>DeviceAllow=char-rtc r</varname> is implied. This ensures <filename>/dev/rtc0</filename>,
+ <filename>/dev/rtc1</filename>, etc. are made read-only to the service. See
+ <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for the details about <varname>DeviceAllow=</varname>.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>ProtectKernelTunables=</varname></term>
<xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>ProtectKernelLogs=</varname></term>
+
+ <listitem><para>Takes a boolean argument. If true, access to the kernel log ring buffer will be denied. It is
+ recommended to turn this on for most services that do not need to read from or write to the kernel log ring
+ buffer. Enabling this option removes <constant>CAP_SYSLOG</constant> from the capability bounding set for this
+ unit, and installs a system call filter to block the
+ <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ system call (not to be confused with the libc API
+ <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for userspace logging). The kernel exposes its log buffer to userspace via <filename>/dev/kmsg</filename> and
+ <filename>/proc/kmsg</filename>. If enabled, these are made inaccessible to all the processes in the unit.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>ProtectControlGroups=</varname></term>
<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, 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 family restriction changes are undone. This setting does not affect commands prefixed with
- <literal>+</literal>.</para>
+ <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 allow-list, 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 deny list,
+ otherwise as allow list. 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, ppc64, 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 family 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
+ <constant>AF_UNIX</constant> address family should be included in the configured allow list as it is frequently
used for local communication, including for
<citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry>
logging.</para></listitem>
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 tilde character (<literal>~</literal>) the
+ prohibited (allow-listing). 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,
+ permitted (deny-listing). If the empty string is assigned, the default namespace restrictions are applied,
which is equivalent to false. This option may appear more than once, in which case the namespace types are
merged by <constant>OR</constant>, or by <constant>AND</constant> if the lines are prefixed with
<literal>~</literal> (see examples below). Internally, this setting limits access to the
points of the file system namespace created for each process of this unit. Other file system namespacing unit
settings (see the discussion in <varname>PrivateMounts=</varname> above) will implicitly disable mount and
unmount propagation from the unit's processes towards the host by changing the propagation setting of all mount
- points in the unit's file system namepace to <option>slave</option> first. Setting this option to
+ points in the unit's file system namespace to <option>slave</option> first. Setting this option to
<option>shared</option> does not reestablish propagation in that case.</para>
<para>If not set – but file system namespaces are enabled through another file system namespace unit setting –
<option>shared</option> mount propagation is used, but — as mentioned — as <option>slave</option> is applied
first, propagation from the unit's processes to the host is still turned off.</para>
- <para>It is not recommended to to use <option>private</option> mount propagation for units, as this means
+ <para>It is not recommended to use <option>private</option> mount propagation for units, as this means
temporary mounts (such as removable media) of the host will stay mounted and thus indefinitely busy in forked
off processes, as unmount propagation events won't be received by the file system namespace of the unit.</para>
<listitem><para>Takes a space-separated list of system call names. If this setting is used, all
system calls executed by the unit processes except for the listed ones will result in immediate
- process termination with the <constant>SIGSYS</constant> signal (whitelisting). (See
+ process termination with the <constant>SIGSYS</constant> signal (allow-listing). (See
<varname>SystemCallErrorNumber=</varname> below for changing the default action). If the first
character of the list is <literal>~</literal>, the effect is inverted: only the listed system calls
- will result in immediate process termination (blacklisting). Blacklisted system calls and system call
+ will result in immediate process termination (deny-listing). Deny-listed system calls and system call
groups may optionally be suffixed with a colon (<literal>:</literal>) and <literal>errno</literal>
error number (between 0 and 4095) or errno name such as <constant>EPERM</constant>,
<constant>EACCES</constant> or <constant>EUCLEAN</constant> (see <citerefentry
project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> for a
- full list). This value will be returned when a blacklisted system call is triggered, instead of
+ full list). This value will be returned when a deny-listed system call is triggered, instead of
terminating the processes immediately. This value takes precedence over the one given in
<varname>SystemCallErrorNumber=</varname>, see below. If running in user mode, or in system mode,
but without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting
for enforcing a minimal sandboxing environment. Note that the <function>execve</function>,
<function>exit</function>, <function>exit_group</function>, <function>getrlimit</function>,
<function>rt_sigreturn</function>, <function>sigreturn</function> system calls and the system calls
- for querying time and sleeping are implicitly whitelisted and do not need to be listed
+ for querying time and sleeping are implicitly allow-listed and do not need to be listed
explicitly. This option may be specified more than once, in which case the filter masks are
merged. If the empty string is assigned, the filter is reset, all prior assignments will have no
effect. This does not affect commands prefixed with <literal>+</literal>.</para>
might be necessary to temporarily disable system call filters in order to simplify debugging of such
failures.</para>
- <para>If you specify both types of this option (i.e. whitelisting and blacklisting), the first encountered
- will take precedence and will dictate the default action (termination or approval of a system call). Then the
- next occurrences of this option will add or delete the listed system calls from the set of the filtered system
- calls, depending of its type and the default action. (For example, if you have started with a whitelisting of
- <function>read</function> and <function>write</function>, and right after it add a blacklisting of
- <function>write</function>, then <function>write</function> will be removed from the set.)</para>
+ <para>If you specify both types of this option (i.e. allow-listing and deny-listing), the first
+ encountered will take precedence and will dictate the default action (termination or approval of a
+ system call). Then the next occurrences of this option will add or delete the listed system calls
+ from the set of the filtered system calls, depending of its type and the default action. (For
+ example, if you have started with an allow list rule for <function>read</function> and
+ <function>write</function>, and right after it add a deny list rule for <function>write</function>,
+ then <function>write</function> will be removed from the set.)</para>
<para>As the number of possible system calls is large, predefined sets of system calls are provided. A set
starts with <literal>@</literal> character, followed by name of the set.
</row>
<row>
<entry>@file-system</entry>
- <entry>File system operations: opening, creating files and directories for read and write, renaming and removing them, reading file properties, or creating hard and symbolic links.</entry>
+ <entry>File system operations: opening, creating files and directories for read and write, renaming and removing them, reading file properties, or creating hard and symbolic links</entry>
</row>
<row>
<entry>@io-event</entry>
</row>
<row>
<entry>@memlock</entry>
- <entry>Locking of memory into RAM (<citerefentry project='man-pages'><refentrytitle>mlock</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>mlockall</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry>
+ <entry>Locking of memory in RAM (<citerefentry project='man-pages'><refentrytitle>mlock</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>mlockall</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry>
</row>
<row>
<entry>@module</entry>
</row>
<row>
<entry>@process</entry>
- <entry>Process control, execution, namespaceing operations (<citerefentry project='man-pages'><refentrytitle>clone</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>, …</entry>
+ <entry>Process control, execution, namespaceing operations (<citerefentry project='man-pages'><refentrytitle>clone</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>, …)</entry>
</row>
<row>
<entry>@raw-io</entry>
</row>
<row>
<entry>@sync</entry>
- <entry>Synchronizing files and memory to disk: (<citerefentry project='man-pages'><refentrytitle>fsync</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>msync</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry>
+ <entry>Synchronizing files and memory to disk (<citerefentry project='man-pages'><refentrytitle>fsync</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>msync</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry>
</row>
<row>
<entry>@system-service</entry>
- <entry>A reasonable set of system calls used by common system services, excluding any special purpose calls. This is the recommended starting point for whitelisting system calls for system services, as it contains what is typically needed by system services, but excludes overly specific interfaces. For example, the following APIs are excluded: <literal>@clock</literal>, <literal>@mount</literal>, <literal>@swap</literal>, <literal>@reboot</literal>.</entry>
+ <entry>A reasonable set of system calls used by common system services, excluding any special purpose calls. This is the recommended starting point for allow-listing system calls for system services, as it contains what is typically needed by system services, but excludes overly specific interfaces. For example, the following APIs are excluded: <literal>@clock</literal>, <literal>@mount</literal>, <literal>@swap</literal>, <literal>@reboot</literal>.</entry>
</row>
<row>
<entry>@timer</entry>
<command>systemd-analyze syscall-filter</command> to list the actual list of system calls in each
filter.</para>
- <para>Generally, whitelisting system calls (rather than blacklisting) is the safer mode of operation. It is
- recommended to enforce system call whitelists for all long-running system services. Specifically, the
- following lines are a relatively safe basic choice for the majority of system services:</para>
+ <para>Generally, allow-listing system calls (rather than deny-listing) is the safer mode of
+ operation. It is recommended to enforce system call allow lists for all long-running system
+ services. Specifically, the following lines are a relatively safe basic choice for the majority of
+ system services:</para>
<programlisting>[Service]
SystemCallFilter=@system-service
call may be used to execute operations similar to what can be done with the older
<function>kill()</function> system call, hence blocking the latter without the former only provides
weak protection. Since new system calls are added regularly to the kernel as development progresses,
- keeping system call blacklists comprehensive requires constant work. It is thus recommended to use
- whitelisting instead, which offers the benefit that new system calls are by default implicitly
- blocked until the whitelist is updated.</para>
+ keeping system call deny lists comprehensive requires constant work. It is thus recommended to use
+ allow-listing instead, which offers the benefit that new system calls are by default implicitly
+ blocked until the allow list is updated.</para>
<para>Also note that a number of system calls are required to be accessible for the dynamic linker to
work. The dynamic linker is required for running most regular programs (specifically: all dynamic ELF
mappings. Specifically these are the options <varname>PrivateTmp=</varname>,
<varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, <varname>ProtectHome=</varname>,
<varname>ProtectKernelTunables=</varname>, <varname>ProtectControlGroups=</varname>,
- <varname>ReadOnlyPaths=</varname>, <varname>InaccessiblePaths=</varname> and
- <varname>ReadWritePaths=</varname>.</para></listitem>
+ <varname>ProtectKernelLogs=</varname>, <varname>ProtectClock=</varname>, <varname>ReadOnlyPaths=</varname>,
+ <varname>InaccessiblePaths=</varname> and <varname>ReadWritePaths=</varname>.</para></listitem>
</varlistentry>
<varlistentry>
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. By default, this option is set to the empty list, i.e. no
- system call architecture filtering is applied.</para>
+ filtering is applied.</para>
<para>If this setting is used, processes of this unit will only be permitted to call native system calls, and
system calls of the specified architectures. For the purposes of this option, the x32 architecture is treated
<para>The files listed with this directive will be read shortly before the process is executed (more
specifically, after all processes from a previous unit state terminated. This means you can generate these
- files in one unit state, and read it with this option in the next).</para>
+ files in one unit state, and read it with this option in the next. The files are read from the file
+ system of the service manager, before any file system changes like bind mounts take place).</para>
<para>Settings from these files override settings made with <varname>Environment=</varname>. If the same
variable is set twice from these files, the files will be read in the order they are specified and the later
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
details about named file descriptors and their ordering.</para>
- <para>This setting defaults to <option>null</option>.</para>
-
- <para>Note that services which specify <option>DefaultDependencies=no</option> and use
- <varname>StandardInput=</varname> or <varname>StandardOutput=</varname> with
- <option>tty</option>/<option>tty-force</option>/<option>tty-fail</option>, should specify
- <option>After=systemd-vconsole-setup.service</option>, to make sure that the tty initialization is
- finished before they start.</para></listitem>
+ <para>This setting defaults to <option>null</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>StandardOutput=</varname></term>
- <listitem><para>Controls where file descriptor 1 (STDOUT) of the executed processes is connected
+ <listitem><para>Controls where file descriptor 1 (stdout) of the executed processes is connected
to. Takes one of <option>inherit</option>, <option>null</option>, <option>tty</option>,
<option>journal</option>, <option>kmsg</option>, <option>journal+console</option>,
<option>kmsg+console</option>, <option>file:<replaceable>path</replaceable></option>,
<constant>AF_UNIX</constant> socket in the file system, as in that case only a
single stream connection is created for both input and output.</para>
- <para><option>append:<replaceable>path</replaceable></option> is similar to <option>file:<replaceable>path
- </replaceable></option> above, but it opens the file in append mode.</para>
+ <para><option>append:<replaceable>path</replaceable></option> is similar to
+ <option>file:<replaceable>path</replaceable></option> above, but it opens the file in append mode.
+ </para>
<para><option>socket</option> connects standard output to a socket acquired via socket activation. The
semantics are similar to the same option of <varname>StandardInput=</varname>, see above.</para>
<varlistentry>
<term><varname>StandardError=</varname></term>
- <listitem><para>Controls where file descriptor 2 (STDERR) of the executed processes is connected to. The
+ <listitem><para>Controls where file descriptor 2 (stderr) of the executed processes is connected to. The
available options are identical to those of <varname>StandardOutput=</varname>, with some exceptions: if set to
<option>inherit</option> the file descriptor used for standard output is duplicated for standard error, while
<option>fd:<replaceable>name</replaceable></option> will use a default file descriptor name of
</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>LogNamespace=</varname></term>
+
+ <listitem><para>Run the unit's processes in the specified journal namespace. Expects a short
+ user-defined string identifying the namespace. If not used the processes of the service are run in
+ the default journal namespace, i.e. their log stream is collected and processed by
+ <filename>systemd-journald.service</filename>. If this option is used any log data generated by
+ processes of this unit (regardless if via the <function>syslog()</function>, journal native logging
+ or stdout/stderr logging) is collected and processed by an instance of the
+ <filename>systemd-journald@.service</filename> template unit, which manages the specified
+ namespace. The log data is stored in a data store independent from the default log namespace's data
+ store. See
+ <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ for details about journal namespaces.</para>
+
+ <para>Internally, journal namespaces are implemented through Linux mount namespacing and
+ over-mounting the directory that contains the relevant <constant>AF_UNIX</constant> sockets used for
+ logging in the unit's mount namespace. Since mount namespaces are used this setting disconnects
+ propagation of mounts from the unit's processes to the host, similar to how
+ <varname>ReadOnlyPaths=</varname> and similar settings (see above) work. Journal namespaces may hence
+ not be used for services that need to establish mount points on the host.</para>
+
+ <para>When this option is used the unit will automatically gain ordering and requirement dependencies
+ on the two socket units associated with the <filename>systemd-journald@.service</filename> instance
+ so that they are automatically established prior to the unit starting up. Note that when this option
+ is used log output of this service does not appear in the regular
+ <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ output, unless the <option>--namespace=</option> option is used.</para>
+
+ <xi:include href="system-only.xml" xpointer="singular"/></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>SyslogIdentifier=</varname></term>
<varname>UnsetEnvironment=</varname> are removed again from the compiled environment variable list, immediately
before it is passed to the executed process.</para>
- <para>The following select environment variables are set or propagated by the service manager for each invoked
+ <para>The following environment variables are set or propagated by the service manager for each invoked
process:</para>
<variablelist class='environment-variables'>
information.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>$RUNTIME_DIRECTORY</varname></term>
+ <term><varname>$STATE_DIRECTORY</varname></term>
+ <term><varname>$CACHE_DIRECTORY</varname></term>
+ <term><varname>$LOGS_DIRECTORY</varname></term>
+ <term><varname>$CONFIGURATION_DIRECTORY</varname></term>
+
+ <listitem><para>Absolute paths to the directories defined with
+ <varname>RuntimeDirectory=</varname>, <varname>StateDirectory=</varname>,
+ <varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname>, and
+ <varname>ConfigurationDirectory=</varname> when those settings are used.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>$MAINPID</varname></term>
</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>$LOG_NAMESPACE</varname></term>
+
+ <listitem><para>If the <varname>LogNamespace=</varname> service setting is used, contains name of the
+ selected logging namespace.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>$JOURNAL_STREAM</varname></term>
<row>
<entry>242</entry>
<entry><constant>EXIT_NUMA_POLICY</constant></entry>
- <entry>Failed to set up unit's NUMA memory policy. See <varname>NUMAPolicy=</varname> and <varname>NUMAMask=</varname>above.</entry>
+ <entry>Failed to set up unit's NUMA memory policy. See <varname>NUMAPolicy=</varname> and <varname>NUMAMask=</varname> above.</entry>
</row>
</tbody>
projects / thirdparty / systemd.git / blobdiff