<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
Linux systems.</para>
<para>When used in conjunction with <varname>DynamicUser=</varname> the user/group name specified is
- dynamically allocated at the time the service is started, and released at the time the service is stopped —
- unless it is already allocated statically (see below). If <varname>DynamicUser=</varname> is not used the
- specified user and group must have been created statically in the user database no later than the moment the
- service is started, for example using the
- <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> facility, which
- is applied at boot or package install time.</para></listitem>
+ 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>
<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
+ <varname>ProtectKernelModules=</varname>, <varname>ProtectKernelLogs=</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>
<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'>
<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>
<varname>RuntimeDirectory=</varname> are removed when the system is rebooted.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>TimeoutCleanSec=</varname></term>
+ <listitem><para>Configures a timeout on the clean-up operation requested through <command>systemctl
+ 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>
+ </varlistentry>
+
<varlistentry>
<term><varname>ReadWritePaths=</varname></term>
<term><varname>ReadOnlyPaths=</varname></term>
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>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>
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>ReadOnlyPaths=</varname>,
+ <varname>InaccessiblePaths=</varname> and <varname>ReadWritePaths=</varname>.</para></listitem>
</varlistentry>
<varlistentry>
variable definitions. The parser strips leading and trailing whitespace from the values of assignments, unless
you use double quotes (").</para>
+ <para><ulink url="https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences">C escapes</ulink>
+ are supported, but not
+ <ulink url="https://en.wikipedia.org/wiki/Control_character#In_ASCII">most control characters</ulink>.
+ <literal>\t</literal> and <literal>\n</literal> can be used to insert tabs and newlines within
+ <varname>EnvironmentFile=</varname>.</para>
+
<para>The argument passed should be an absolute filename or wildcard expression, optionally prefixed with
<literal>-</literal>, which indicates that if the file does not exist, it will not be read and no error or
warning message is logged. This option may be specified more than once in which case all specified files are
<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
<para>Variables set for invoked processes due to this setting are subject to being overridden by those
configured with <varname>Environment=</varname> or <varname>EnvironmentFile=</varname>.</para>
+ <para><ulink url="https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences">C escapes</ulink>
+ are supported, but not
+ <ulink url="https://en.wikipedia.org/wiki/Control_character#In_ASCII">most control characters</ulink>.
+ <literal>\t</literal> and <literal>\n</literal> can be used to insert tabs and newlines within
+ <varname>EnvironmentFile=</varname>.</para>
+
<para>Example:
<programlisting>PassEnvironment=VAR1 VAR2 VAR3</programlisting>
passes three variables <literal>VAR1</literal>,
<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>,
<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
<varlistentry>
<term><varname>LogExtraFields=</varname></term>
- <listitem><para>Configures additional log metadata fields to include in all log records generated by processes
- associated with this unit. This setting takes one or more journal field assignments in the format
- <literal>FIELD=VALUE</literal> separated by whitespace. See
- <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
- details on the journal field concept. Even though the underlying journal implementation permits binary field
- values, this setting accepts only valid UTF-8 values. To include space characters in a journal field value,
- enclose the assignment in double quotes ("). The usual specifiers are expanded in all assignments (see
- below). Note that this setting is not only useful for attaching additional metadata to log records of a unit,
- but given that all fields and values are indexed may also be used to implement cross-unit log record
- matching. Assign an empty string to reset the list.</para></listitem>
+ <listitem><para>Configures additional log metadata fields to include in all log records generated by
+ processes associated with this unit. This setting takes one or more journal field assignments in the
+ format <literal>FIELD=VALUE</literal> separated by whitespace. See
+ <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for details on the journal field concept. Even though the underlying journal implementation permits
+ binary field values, this setting accepts only valid UTF-8 values. To include space characters in a
+ journal field value, enclose the assignment in double quotes ("). <!-- " fake closing quote for emacs-->
+ The usual specifiers are expanded in all assignments (see below). Note that this setting is not only
+ useful for attaching additional metadata to log records of a unit, but given that all fields and
+ values are indexed may also be used to implement cross-unit log record matching. Assign an empty
+ string to reset the list.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>$PATH</varname></term>
- <listitem><para>Colon-separated list of directories to use
- when launching executables. systemd uses a fixed value of
- <filename>/usr/local/sbin</filename>:<filename>/usr/local/bin</filename>:<filename>/usr/sbin</filename>:<filename>/usr/bin</filename>:<filename>/sbin</filename>:<filename>/bin</filename>.
- </para></listitem>
+ <listitem><para>Colon-separated list of directories to use when launching
+ executables. <command>systemd</command> uses a fixed value of
+ <literal><filename>/usr/local/sbin</filename>:<filename>/usr/local/bin</filename>:<filename>/usr/sbin</filename>:<filename>/usr/bin</filename></literal>
+ in the system manager. When compiled for systems with "unmerged /usr" (<filename>/bin</filename> is
+ not a symlink to <filename>/usr/bin</filename>),
+ <literal>:<filename>/sbin</filename>:<filename>/bin</filename></literal> is appended. In case of the
+ the user manager, a different path may be configured by the distribution. It is recommended to not
+ rely on the order of entries, and have only one program with a given name in
+ <varname>$PATH</varname>.</para></listitem>
</varlistentry>
<varlistentry>
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>Contains and 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>
<tbody>
<row>
- <entry valign="top"><literal>success</literal></entry>
+ <entry morerows="1" valign="top"><literal>success</literal></entry>
+ <entry valign="top"><literal>killed</literal></entry>
+ <entry><literal>HUP</literal>, <literal>INT</literal>, <literal>TERM</literal>, <literal>PIPE</literal></entry>
+ </row>
+ <row>
<entry valign="top"><literal>exited</literal></entry>
<entry><literal>0</literal></entry>
</row>
<entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal
>3</literal>, …, <literal>255</literal></entry>
</row>
+ <row>
+ <entry valign="top"><literal>exec-condition</literal></entry>
+ <entry><literal>exited</literal></entry>
+ <entry><literal>1</literal>, <literal>2</literal>, <literal>3</literal>, <literal
+ >4</literal>, …, <literal>254</literal></entry>
+ </row>
+ <row>
+ <entry valign="top"><literal>oom-kill</literal></entry>
+ <entry valign="top"><literal>killed</literal></entry>
+ <entry><literal>TERM</literal>, <literal>KILL</literal></entry>
+ </row>
<row>
<entry><literal>start-limit-hit</literal></entry>
<entry>not set</entry>
</table>
<para>The following service exit codes are defined by the <ulink
- url="https://refspecs.linuxbase.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB specification
- </ulink>.
+ url="https://refspecs.linuxbase.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB specification</ulink>.
</para>
<table>
projects / thirdparty / systemd.git / blobdiff