is used. In this case the source path refers to a path on the host file system, while the destination path
refers to a path below the root directory of the unit.</para>
+ <para>Note that the destination directory must exist or systemd must be able to create it. Thus, it
+ is not possible to use those options for mount points nested underneath paths specified in
+ <varname>InaccessiblePaths=</varname>, or under <filename>/home/</filename> and other protected
+ directories if <varname>ProtectHome=yes</varname> is
+ specified. <varname>TemporaryFileSystem=</varname> with <literal>:ro</literal> or
+ <varname>ProtectHome=tmpfs</varname> should be used instead.</para>
+
<xi:include href="system-only.xml" xpointer="singular"/></listitem>
</varlistentry>
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>
part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by
these users/groups around, as a different unit might get the same UID/GID assigned later on, and thus
gain access to these files or directories. If <varname>DynamicUser=</varname> is enabled,
- <varname>RemoveIPC=</varname>, <varname>PrivateTmp=</varname> are implied. This ensures that the
- lifetime of IPC objects and temporary files created by the executed processes is bound to the runtime
- of the service, and hence the lifetime of the dynamic user/group. Since <filename>/tmp</filename> and
- <filename>/var/tmp</filename> are usually the only world-writable directories on a system this
- ensures that a unit making use of dynamic user/group allocation cannot leave files around after unit
- termination. Furthermore <varname>NoNewPrivileges=</varname> and <varname>RestrictSUIDSGID=</varname>
- are implicitly enabled to ensure that processes invoked cannot take benefit or create SUID/SGID files
- or directories. Moreover <varname>ProtectSystem=strict</varname> and
+ <varname>RemoveIPC=</varname> and <varname>PrivateTmp=</varname> are implied (and cannot be turned
+ off). This ensures that the lifetime of IPC objects and temporary files created by the executed
+ processes is bound to the runtime of the service, and hence the lifetime of the dynamic
+ user/group. Since <filename>/tmp/</filename> and <filename>/var/tmp/</filename> are usually the only
+ world-writable directories on a system this ensures that a unit making use of dynamic user/group
+ allocation cannot leave files around after unit termination. Furthermore
+ <varname>NoNewPrivileges=</varname> and <varname>RestrictSUIDSGID=</varname> are implicitly enabled
+ (and cannot be disabled), to ensure that processes invoked cannot take benefit or create SUID/SGID
+ files or directories. Moreover <varname>ProtectSystem=strict</varname> and
<varname>ProtectHome=read-only</varname> are implied, thus prohibiting the service to write to
arbitrary file system locations. In order to allow the service to write to certain directories, they
have to be whitelisted using <varname>ReadWritePaths=</varname>, but care must be taken so that
<varlistentry>
<term><varname>OOMScoreAdjust=</varname></term>
- <listitem><para>Sets the adjustment level for the Out-Of-Memory killer for executed processes. Takes an integer
- between -1000 (to disable OOM killing for this process) and 1000 (to make killing of this process under memory
- pressure very likely). See <ulink
- url="https://www.kernel.org/doc/Documentation/filesystems/proc.txt">proc.txt</ulink> for
- details.</para></listitem>
+ <listitem><para>Sets the adjustment value for the Linux kernel's Out-Of-Memory (OOM) killer score for
+ executed processes. Takes an integer between -1000 (to disable OOM killing of processes of this unit)
+ and 1000 (to make killing of processes of this unit under memory pressure very likely). See <ulink
+ url="https://www.kernel.org/doc/Documentation/filesystems/proc.txt">proc.txt</ulink> for details. If
+ not specified defaults to the OOM score adjustment level of the service manager itself, which is
+ normally at 0.</para>
+
+ <para>Use the <varname>OOMPolicy=</varname> setting of service units to configure how the service
+ manager shall react to the kernel OOM killer terminating a process of the service. See
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details.</para></listitem>
</varlistentry>
<varlistentry>
<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
+ 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>
+ <varlistentry>
+ <term><varname>NUMAPolicy=</varname></term>
+
+ <listitem><para>Controls the NUMA memory policy of the executed processes. Takes a policy type, one of:
+ <option>default</option>, <option>preferred</option>, <option>bind</option>, <option>interleave</option> and
+ <option>local</option>. A list of NUMA nodes that should be associated with the policy must be specified
+ 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>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>NUMAMask=</varname></term>
+
+ <listitem><para>Controls the NUMA node list which will be applied alongside with selected NUMA policy.
+ Takes a list of NUMA nodes and has the same syntax as a list of CPUs for <varname>CPUAffinity=</varname>
+ option. Note that the list of NUMA nodes is not required for <option>default</option> and <option>local</option>
+ policies and for <option>preferred</option> policy we expect a single NUMA node.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>IOSchedulingClass=</varname></term>
<term><varname>ProtectHome=</varname></term>
<listitem><para>Takes a boolean argument or the special values <literal>read-only</literal> or
- <literal>tmpfs</literal>. If true, the directories <filename>/home</filename>, <filename>/root</filename> and
- <filename>/run/user</filename> are made inaccessible and empty for processes invoked by this unit. If set to
- <literal>read-only</literal>, the three directories are made read-only instead. If set to <literal>tmpfs</literal>,
- temporary file systems are mounted on the three directories in read-only mode. The value <literal>tmpfs</literal>
- is useful to hide home directories not relevant to the processes invoked by the unit, while necessary directories
- are still visible by combining with <varname>BindPaths=</varname> or <varname>BindReadOnlyPaths=</varname>.</para>
+ <literal>tmpfs</literal>. If true, the directories <filename>/home</filename>,
+ <filename>/root</filename>, and <filename>/run/user</filename> are made inaccessible and empty for
+ processes invoked by this unit. If set to <literal>read-only</literal>, the three directories are
+ made read-only instead. If set to <literal>tmpfs</literal>, temporary file systems are mounted on the
+ three directories in read-only mode. The value <literal>tmpfs</literal> is useful to hide home
+ directories not relevant to the processes invoked by the unit, while still allowing necessary
+ directories to be made visible when listed in <varname>BindPaths=</varname> or
+ <varname>BindReadOnlyPaths=</varname>.</para>
<para>Setting this to <literal>yes</literal> is mostly equivalent to set the three directories in
<varname>InaccessiblePaths=</varname>. Similarly, <literal>read-only</literal> is mostly equivalent to
<varname>ReadOnlyPaths=</varname>, and <literal>tmpfs</literal> is mostly equivalent to
- <varname>TemporaryFileSystem=</varname>.</para>
+ <varname>TemporaryFileSystem=</varname> with <literal>:ro</literal>.</para>
- <para> It is recommended to enable this setting for all long-running services (in particular network-facing
- ones), to ensure they cannot get access to private user data, unless the services actually require access to
- the user's private data. This setting is implied if <varname>DynamicUser=</varname> is set. This setting cannot
- ensure protection in all cases. In general it has the same limitations as <varname>ReadOnlyPaths=</varname>,
- see below.</para>
+ <para>It is recommended to enable this setting for all long-running services (in particular
+ network-facing ones), to ensure they cannot get access to private user data, unless the services
+ actually require access to the user's private data. This setting is implied if
+ <varname>DynamicUser=</varname> is set. This setting cannot ensure protection in all cases. In
+ general it has the same limitations as <varname>ReadOnlyPaths=</varname>, see below.</para>
<xi:include href="system-only.xml" xpointer="singular"/></listitem>
</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>
<para>This is useful to hide files or directories not relevant to the processes invoked by the unit, while necessary
files or directories can be still accessed by combining with <varname>BindPaths=</varname> or
- <varname>BindReadOnlyPaths=</varname>. See the example below.</para>
+ <varname>BindReadOnlyPaths=</varname>:</para>
<para>Example: if a unit has the following,
<programlisting>TemporaryFileSystem=/var:ro
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 familiy restriction changes are undone. This setting does not affect commands prefixed with
+ 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
<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>,
<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 intialization is
+ <option>After=systemd-vconsole-setup.service</option>, to make sure that the tty initialization is
finished before they start.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>StandardOutput=</varname></term>
- <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>syslog</option>, <option>kmsg</option>, <option>journal+console</option>,
- <option>syslog+console</option>, <option>kmsg+console</option>,
- <option>file:<replaceable>path</replaceable></option>, <option>append:<replaceable>path</replaceable></option>,
- <option>socket</option> or <option>fd:<replaceable>name</replaceable></option>.</para>
+ <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>,
+ <option>append:<replaceable>path</replaceable></option>, <option>socket</option> or
+ <option>fd:<replaceable>name</replaceable></option>.</para>
<para><option>inherit</option> duplicates the file descriptor of standard input for standard output.</para>
see below). If the TTY is used for output only, the executed process will not become the controlling process of
the terminal, and will not fail or wait for other processes to release the terminal.</para>
- <para><option>journal</option> connects standard output with the journal which is accessible via
- <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Note that
- everything that is written to syslog or kmsg (see below) is implicitly stored in the journal as well, the
- specific two options listed below are hence supersets of this one.</para>
-
- <para><option>syslog</option> connects standard output to the <citerefentry
- project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> system syslog
- service, in addition to the journal. Note that the journal daemon is usually configured to forward everything
- it receives to syslog anyway, in which case this option is no different from <option>journal</option>.</para>
+ <para><option>journal</option> connects standard output with the journal, which is accessible via
+ <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Note
+ that everything that is written to kmsg (see below) is implicitly stored in the journal as well, the
+ specific option listed below is hence a superset of this one. (Also note that any external,
+ additional syslog daemons receive their log data from the journal, too, hence this is the option to
+ use when logging shall be processed with such a daemon.)</para>
<para><option>kmsg</option> connects standard output with the kernel log buffer which is accessible via
<citerefentry project='man-pages'><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
in addition to the journal. The journal daemon might be configured to send all logs to kmsg anyway, in which
case this option is no different from <option>journal</option>.</para>
- <para><option>journal+console</option>, <option>syslog+console</option> and <option>kmsg+console</option> work
- in a similar way as the three options above but copy the output to the system console as well.</para>
+ <para><option>journal+console</option> and <option>kmsg+console</option> work in a similar way as the
+ two options above but copy the output to the system console as well.</para>
<para>The <option>file:<replaceable>path</replaceable></option> option may be used to connect a specific file
system object to standard output. The semantics are similar to the same option of
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
details about named descriptors and their ordering.</para>
- <para>If the standard output (or error output, see below) of a unit is connected to the journal, syslog or the
- kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname> on
- <filename>systemd-journald.socket</filename> (also see the "Implicit Dependencies" section above). Also note
- that in this case stdout (or stderr, see below) will be an <constant>AF_UNIX</constant> stream socket, and not
- a pipe or FIFO that can be re-opened. This means when executing shell scripts the construct <command>echo
- "hello" > /dev/stderr</command> for writing text to stderr will not work. To mitigate this use the construct
- <command>echo "hello" >&2</command> instead, which is mostly equivalent and avoids this pitfall.</para>
+ <para>If the standard output (or error output, see below) of a unit is connected to the journal or
+ the kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname>
+ on <filename>systemd-journald.socket</filename> (also see the "Implicit Dependencies" section
+ above). Also note that in this case stdout (or stderr, see below) will be an
+ <constant>AF_UNIX</constant> stream socket, and not a pipe or FIFO that can be re-opened. This means
+ when executing shell scripts the construct <command>echo "hello" > /dev/stderr</command> for
+ writing text to stderr will not work. To mitigate this use the construct <command>echo "hello"
+ >&2</command> instead, which is mostly equivalent and avoids this pitfall.</para>
<para>This setting defaults to the value set with <varname>DefaultStandardOutput=</varname> in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, which
<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>SyslogIdentifier=</varname></term>
- <listitem><para>Sets the process name ("<command>syslog</command> tag") to prefix log lines sent to the logging
- system or the kernel log buffer with. If not set, defaults to the process name of the executed process. This
- option is only useful when <varname>StandardOutput=</varname> or <varname>StandardError=</varname> are set to
- <option>journal</option>, <option>syslog</option> or <option>kmsg</option> (or to the same settings in
- combination with <option>+console</option>) and only applies to log messages written to stdout or
- stderr.</para></listitem>
+ <listitem><para>Sets the process name ("<command>syslog</command> tag") to prefix log lines sent to
+ the logging system or the kernel log buffer with. If not set, defaults to the process name of the
+ executed process. This option is only useful when <varname>StandardOutput=</varname> or
+ <varname>StandardError=</varname> are set to <option>journal</option> or <option>kmsg</option> (or to
+ the same settings in combination with <option>+console</option>) and only applies to log messages
+ written to stdout or stderr.</para></listitem>
</varlistentry>
<varlistentry>
<option>auth</option>, <option>syslog</option>, <option>lpr</option>, <option>news</option>,
<option>uucp</option>, <option>cron</option>, <option>authpriv</option>, <option>ftp</option>,
<option>local0</option>, <option>local1</option>, <option>local2</option>, <option>local3</option>,
- <option>local4</option>, <option>local5</option>, <option>local6</option> or <option>local7</option>. See
- <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- for details. This option is only useful when <varname>StandardOutput=</varname> or
- <varname>StandardError=</varname> are set to <option>journal</option>, <option>syslog</option> or
- <option>kmsg</option> (or to the same settings in combination with <option>+console</option>), and only applies
- to log messages written to stdout or stderr. Defaults to <option>daemon</option>.</para></listitem>
+ <option>local4</option>, <option>local5</option>, <option>local6</option> or
+ <option>local7</option>. See <citerefentry
+ project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
+ details. This option is only useful when <varname>StandardOutput=</varname> or
+ <varname>StandardError=</varname> are set to <option>journal</option> or <option>kmsg</option> (or to
+ the same settings in combination with <option>+console</option>), and only applies to log messages
+ written to stdout or stderr. Defaults to <option>daemon</option>.</para></listitem>
</varlistentry>
<varlistentry>
<option>debug</option>. See <citerefentry
project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
details. This option is only useful when <varname>StandardOutput=</varname> or
- <varname>StandardError=</varname> are set to <option>journal</option>, <option>syslog</option> or
+ <varname>StandardError=</varname> are set to <option>journal</option> or
<option>kmsg</option> (or to the same settings in combination with <option>+console</option>), and only applies
to log messages written to stdout or stderr. Note that individual lines output by executed processes may be
prefixed with a different log level which can be used to override the default log level specified here. The
<term><varname>SyslogLevelPrefix=</varname></term>
<listitem><para>Takes a boolean argument. If true and <varname>StandardOutput=</varname> or
- <varname>StandardError=</varname> are set to <option>journal</option>, <option>syslog</option> or
- <option>kmsg</option> (or to the same settings in combination with <option>+console</option>), log lines
- written by the executed process that are prefixed with a log level will be processed with this log level set
- but the prefix removed. If set to false, the interpretation of these prefixes is disabled and the logged lines
- are passed on as-is. This only applies to log messages written to stdout or stderr. For details about this
- prefixing see <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+ <varname>StandardError=</varname> are set to <option>journal</option> or <option>kmsg</option> (or to
+ the same settings in combination with <option>+console</option>), log lines written by the executed
+ process that are prefixed with a log level will be processed with this log level set but the prefix
+ removed. If set to false, the interpretation of these prefixes is disabled and the logged lines are
+ passed on as-is. This only applies to log messages written to stdout or stderr. For details about
+ this prefixing see
+ <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
Defaults to true.</para></listitem>
</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>
<entry><constant>EXIT_CONFIGURATION_DIRECTORY</constant></entry>
<entry>Failed to set up unit's configuration directory. See <varname>ConfigurationDirectory=</varname> above.</entry>
</row>
+ <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>
+ </row>
+
</tbody>
</tgroup>
</table>
projects / thirdparty / systemd.git / blobdiff