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>
configuration or lifetime guarantees, please consider using
<citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+ <para>The directories defined by these options are always created under the standard paths used by systemd
+ (<filename>/var</filename>, <filename>/run</filename>, <filename>/etc</filename>, …). If the service needs
+ directories in a different location, a different mechanism has to be used to create them.</para>
+
+ <para><citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> provides
+ functionality that overlaps with these options. Using these options is recommended, because the lifetime of
+ the directories is tied directly to the lifetime of the unit, and it is not necessary to ensure that the
+ <filename>tmpfiles.d</filename> configuration is executed before the unit is started.</para>
+
+ <para>To remove any of the directories created by these settings, use the <command>systemctl clean
+ …</command> command on the relevant units, see
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
+ details.</para>
+
<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),
<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>
<varlistentry>
<term><varname>SystemCallFilter=</varname></term>
- <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). 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 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>. This value will be
- returned when a blacklisted system call is triggered, instead of terminating the processes immediately. This
- value takes precedence over the one given in <varname>SystemCallErrorNumber=</varname>. 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. This feature makes use of
- the Secure Computing Mode 2 interfaces of the kernel ('seccomp filtering') and is useful 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 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>
+ <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
+ <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
+ 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
+ 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
+ <varname>User=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is implied. This feature
+ makes use of the Secure Computing Mode 2 interfaces of the kernel ('seccomp filtering') and is useful
+ 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
+ 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>
<para>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
SystemCallFilter=@system-service
SystemCallErrorNumber=EPERM</programlisting>
+ <para>Note that various kernel system calls are defined redundantly: there are multiple system calls
+ for executing the same operation. For example, the <function>pidfd_send_signal()</function> system
+ 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>
+
+ <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
+ binaries, which is how most distributions build packaged programs). This means that blocking these
+ system calls (which include <function>open()</function>, <function>openat()</function> or
+ <function>mmap()</function>) will make most programs typically shipped with generic distributions
+ unusable.</para>
+
<para>It is recommended to combine the file system namespacing related options with
<varname>SystemCallFilter=~@mount</varname>, in order to prohibit the unit's processes to undo the
mappings. Specifically these are the options <varname>PrivateTmp=</varname>,
<varlistentry>
<term><varname>SystemCallErrorNumber=</varname></term>
- <listitem><para>Takes an <literal>errno</literal> error number (between 1 and 4095) or errno name such as
- <constant>EPERM</constant>, <constant>EACCES</constant> or <constant>EUCLEAN</constant>, to return when the
- system call filter configured with <varname>SystemCallFilter=</varname> is triggered, instead of terminating
- the process immediately. When this setting is not used, or when the empty string is assigned, the process will
- be terminated immediately when the filter is triggered.</para></listitem>
+ <listitem><para>Takes an <literal>errno</literal> error number (between 1 and 4095) or errno name
+ such as <constant>EPERM</constant>, <constant>EACCES</constant> or <constant>EUCLEAN</constant>, to
+ return when the system call filter configured with <varname>SystemCallFilter=</varname> is triggered,
+ instead of terminating the process immediately. See <citerefentry
+ project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> for a
+ full list of error codes. When this setting is not used, or when the empty string is assigned, the
+ process will be terminated immediately when the filter is triggered.</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>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, each <filename>bin/</filename> and <filename>sbin/</filename> pair is switched, so
+ that programs from <filename>/usr/bin</filename> have higher priority than programs from
+ <filename>/usr/sbin</filename>, etc. It is recommended to not rely on this in any way, and have only
+ one program with a given name in <varname>$PATH</varname>.</para></listitem>
</varlistentry>
<varlistentry>
<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