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>
+ is applied at boot or package install time.</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>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>
<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>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