"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
-<refentry id="systemd.service">
+<refentry id="systemd.service" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd.service</title>
<productname>systemd</productname>
<term><varname>Type=</varname></term>
<listitem>
- <para>Configures the process start-up type for this service unit. One of <option>simple</option>,
- <option>exec</option>, <option>forking</option>, <option>oneshot</option>, <option>dbus</option>,
- <option>notify</option>, <option>notify-reload</option> or <option>idle</option>:</para>
+ <para>Configures the mechanism via which the service notifies the manager that the service start-up
+ has finished. One of <option>simple</option>, <option>exec</option>, <option>forking</option>,
+ <option>oneshot</option>, <option>dbus</option>, <option>notify</option>,
+ <option>notify-reload</option>, or <option>idle</option>:</para>
<itemizedlist>
- <listitem><para>If set to <option>simple</option> (the default if <varname>ExecStart=</varname> is
- specified but neither <varname>Type=</varname> nor <varname>BusName=</varname> are), the service manager
- will consider the unit started immediately after the main service process has been forked off. It is
- expected that the process configured with <varname>ExecStart=</varname> is the main process of the
- service. In this mode, if the process offers functionality to other processes on the system, its
- communication channels should be installed before the service is started up (e.g. sockets set up by
- systemd, via socket activation), as the service manager will immediately proceed starting follow-up units,
- right after creating the main service process, and before executing the service's binary. Note that this
- means <command>systemctl start</command> command lines for <option>simple</option> services will report
- success even if the service's binary cannot be invoked successfully (for example because the selected
- <varname>User=</varname> doesn't exist, or the service binary is missing).</para></listitem>
-
- <listitem><para>The <option>exec</option> type is similar to <option>simple</option>, but the service
- manager will consider the unit started immediately after the main service binary has been executed. The service
- manager will delay starting of follow-up units until that point. (Or in other words:
- <option>simple</option> proceeds with further jobs right after <function>fork()</function> returns, while
- <option>exec</option> will not proceed before both <function>fork()</function> and
- <function>execve()</function> in the service process succeeded.) Note that this means <command>systemctl
- start</command> command lines for <option>exec</option> services will report failure when the service's
- binary cannot be invoked successfully (for example because the selected <varname>User=</varname> doesn't
+ <listitem><para>If set to <option>simple</option> (the default if <varname>ExecStart=</varname>
+ is specified but neither <varname>Type=</varname> nor <varname>BusName=</varname> are), the
+ service manager will consider the unit started immediately after the main service process has
+ been forked off (i.e. immediately after <function>fork()</function>, and before various process
+ attributes have been configured and in particular before the new process has called
+ <function>execve()</function> to invoke the actual service binary). Typically,
+ <varname>Type=</varname><option>exec</option> is the better choice, see below.</para>
+
+ <para>It is expected that the process configured with <varname>ExecStart=</varname> is the main
+ process of the service. In this mode, if the process offers functionality to other processes on
+ the system, its communication channels should be installed before the service is started up
+ (e.g. sockets set up by systemd, via socket activation), as the service manager will immediately
+ proceed starting follow-up units, right after creating the main service process, and before
+ executing the service's binary. Note that this means <command>systemctl start</command> command
+ lines for <option>simple</option> services will report success even if the service's binary
+ cannot be invoked successfully (for example because the selected <varname>User=</varname> doesn't
exist, or the service binary is missing).</para></listitem>
- <listitem><para>If set to <option>forking</option>, it is expected that the process configured with
- <varname>ExecStart=</varname> will call <function>fork()</function> as part of its start-up. The parent
- process is expected to exit when start-up is complete and all communication channels are set up. The child
- continues to run as the main service process, and the service manager will consider the unit started when
- the parent process exits. This is the behavior of traditional UNIX services. If this setting is used, it is
- recommended to also use the <varname>PIDFile=</varname> option, so that systemd can reliably identify the
- main process of the service. systemd will proceed with starting follow-up units as soon as the parent
- process exits.</para></listitem>
+ <listitem><para>The <option>exec</option> type is similar to <option>simple</option>, but the
+ service manager will consider the unit started immediately after the main service binary has been
+ executed. The service manager will delay starting of follow-up units until that point. (Or in
+ other words: <option>simple</option> proceeds with further jobs right after
+ <function>fork()</function> returns, while <option>exec</option> will not proceed before both
+ <function>fork()</function> and <function>execve()</function> in the service process succeeded.)
+ Note that this means <command>systemctl start</command> command lines for <option>exec</option>
+ services will report failure when the service's binary cannot be invoked successfully (for
+ example because the selected <varname>User=</varname> doesn't exist, or the service binary is
+ missing).</para></listitem>
+
+ <listitem><para>If set to <option>forking</option>, the manager will consider the unit started
+ immediately after the binary that forked off by the manager exits. <emphasis>The use of this type
+ is discouraged, use <option>notify</option>, <option>notify-reload</option>, or
+ <option>dbus</option> instead.</emphasis></para>
+
+ <para>It is expected that the process configured with <varname>ExecStart=</varname> will call
+ <function>fork()</function> as part of its start-up. The parent process is expected to exit when
+ start-up is complete and all communication channels are set up. The child continues to run as the
+ main service process, and the service manager will consider the unit started when the parent
+ process exits. This is the behavior of traditional UNIX services. If this setting is used, it is
+ recommended to also use the <varname>PIDFile=</varname> option, so that systemd can reliably
+ identify the main process of the service. The manager will proceed with starting follow-up units
+ after the parent process exits.</para></listitem>
<listitem><para>Behavior of <option>oneshot</option> is similar to <option>simple</option>;
however, the service manager will consider the unit up after the main process exits. It will then
of service. <varname>Type=</varname><option>oneshot</option> is the implied default if neither
<varname>Type=</varname> nor <varname>ExecStart=</varname> are specified. Note that if this
option is used without <varname>RemainAfterExit=</varname> the service will never enter
- <literal>active</literal> unit state, but directly transition from <literal>activating</literal>
- to <literal>deactivating</literal> or <literal>dead</literal> since no process is configured that
- shall run continuously. In particular this means that after a service of this type ran (and which
- has <varname>RemainAfterExit=</varname> not set) it will not show up as started afterwards, but
- as dead.</para></listitem>
+ <literal>active</literal> unit state, but will directly transition from
+ <literal>activating</literal> to <literal>deactivating</literal> or <literal>dead</literal>,
+ since no process is configured that shall run continuously. In particular this means that after a
+ service of this type ran (and which has <varname>RemainAfterExit=</varname> not set) it will not
+ show up as started afterwards, but as dead.</para></listitem>
<listitem><para>Behavior of <option>dbus</option> is similar to <option>simple</option>; however,
- it is expected that the service acquires a name on the D-Bus bus, as configured by
- <varname>BusName=</varname>. systemd will proceed with starting follow-up units after the D-Bus
- bus name has been acquired. Service units with this option configured implicitly gain
- dependencies on the <filename>dbus.socket</filename> unit. This type is the default if
- <varname>BusName=</varname> is specified. A service unit of this type is considered to be in the
+ units of this type must have the <varname>BusName=</varname> specified and the service manager
+ will consider the unit up when the specified bus name has been acquired. This type is the default
+ if <varname>BusName=</varname> is specified.</para>
+
+ <para>Service units with this option configured implicitly gain dependencies on the
+ <filename>dbus.socket</filename> unit. A service unit of this type is considered to be in the
activating state until the specified bus name is acquired. It is considered activated while the
bus name is taken. Once the bus name is released the service is considered being no longer
functional which has the effect that the service manager attempts to terminate any remaining
units after this notification message has been sent. If this option is used,
<varname>NotifyAccess=</varname> (see below) should be set to open access to the notification
socket provided by systemd. If <varname>NotifyAccess=</varname> is missing or set to
- <option>none</option>, it will be forcibly set to <option>main</option>.</para></listitem>
-
- <listitem><para>Behavior of <option>notify-reload</option> is identical to
- <option>notify</option>. However, it extends the logic in one way: the
- <constant>SIGHUP</constant> UNIX process signal is sent to the service's main process when the
- service is asked to reload. (The signal to send can be tweaked via
- <varname>ReloadSignal=</varname>, see below.) When
- initiating the reload process the service is then expected to reply with a notification message
- via <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ <option>none</option>, it will be forcibly set to <option>main</option>.</para>
+
+ <para>If the service supports reloading, and uses a signal to start the reload, using
+ <option>notify-reload</option> instead is recommended.</para></listitem>
+
+ <listitem><para>Behavior of <option>notify-reload</option> is similar to <option>notify</option>,
+ with one difference: the <constant>SIGHUP</constant> UNIX process signal is sent to the service's
+ main process when the service is asked to reload and the manager will wait for a notification
+ about the reload being finished.</para>
+
+ <para>When initiating the reload process the service is expected to reply with a notification
+ message via
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
that contains the <literal>RELOADING=1</literal> field in combination with
<literal>MONOTONIC_USEC=</literal> set to the current monotonic time
(i.e. <constant>CLOCK_MONOTONIC</constant> in
in μs, formatted as decimal string. Once reloading is complete another notification message must
be sent, containing <literal>READY=1</literal>. Using this service type and implementing this
reload protocol is an efficient alternative to providing an <varname>ExecReload=</varname>
- command for reloading of the service's configuration.</para></listitem>
+ command for reloading of the service's configuration.</para>
+
+ <para>The signal to send can be tweaked via <varname>ReloadSignal=</varname>, see below.</para>
+ </listitem>
<listitem><para>Behavior of <option>idle</option> is very similar to <option>simple</option>; however,
actual execution of the service program is delayed until all active jobs are dispatched. This may be used
anyway.</para></listitem>
</itemizedlist>
- <para>It is generally recommended to use <varname>Type=</varname><option>simple</option> for
- long-running services whenever possible, as it is the simplest and fastest option. However, as this
- service type won't propagate service start-up failures and doesn't allow ordering of other units
- against completion of initialization of the service (which for example is useful if clients need to
- connect to the service through some form of IPC, and the IPC channel is only established by the
- service itself — in contrast to doing this ahead of time through socket or bus activation or
- similar), it might not be sufficient for many cases. If so, <option>notify</option>,
- <option>notify-reload</option> or <option>dbus</option> (the latter only in case the service
+ <para>It is recommended to use <varname>Type=</varname><option>exec</option> for long-running
+ services, as it ensures that process setup errors (e.g. errors such as a missing service
+ executable, or missing user) are properly tracked. However, as this service type won't propagate
+ the failures in the service's own startup code (as opposed to failures in the preparatory steps the
+ service manager executes before <function>execve()</function>) and doesn't allow ordering of other
+ units against completion of initialization of the service code itself (which for example is useful
+ if clients need to connect to the service through some form of IPC, and the IPC channel is only
+ established by the service itself — in contrast to doing this ahead of time through socket or bus
+ activation or similar), it might not be sufficient for many cases. If so, <option>notify</option>,
+ <option>notify-reload</option>, or <option>dbus</option> (the latter only in case the service
provides a D-Bus interface) are the preferred options as they allow service program code to
precisely schedule when to consider the service started up successfully and when to proceed with
follow-up units. The <option>notify</option>/<option>notify-reload</option> service types require
explicit support in the service codebase (as <function>sd_notify()</function> or an equivalent API
needs to be invoked by the service at the appropriate time) — if it's not supported, then
- <option>forking</option> is an alternative: it supports the traditional UNIX service start-up
- protocol. Finally, <option>exec</option> might be an option for cases where it is enough to ensure
- the service binary is invoked, and where the service binary itself executes no or little
- initialization on its own (and its initialization is unlikely to fail). Note that using any type
- other than <option>simple</option> possibly delays the boot process, as the service manager needs
- to wait for service initialization to complete. It is hence recommended not to needlessly use any
- types other than <option>simple</option>. (Also note it is generally not recommended to use
- <option>idle</option> or <option>oneshot</option> for long-running services.)</para>
- </listitem>
+ <option>forking</option> is an alternative: it supports the traditional heavy-weight UNIX service
+ start-up protocol. Note that using any type other than <option>simple</option> possibly delays the
+ boot process, as the service manager needs to wait for at least some service initialization to
+ complete. (Also note it is generally not recommended to use <option>idle</option> or
+ <option>oneshot</option> for long-running services.)</para>
+
+ <para>Note that various service settings (e.g. <varname>User=</varname>, <varname>Group=</varname>
+ through libc NSS) might result in "hidden" blocking IPC calls to other services when
+ used. Sometimes it might be advisable to use the <option>simple</option> service type to ensure
+ that the service manager's transaction logic is not affected by such potentially slow operations
+ and hidden dependencies, as this is the only service type where the service manager will not wait
+ for such service execution setup operations to complete before proceeding.</para></listitem>
</varlistentry>
<varlistentry>
<option>cgroup</option> is meant for applications whose forking model is not known ahead of time and which
might not have a specific main process. It is well suited for transient or automatically generated services,
such as graphical applications inside of a desktop environment.</para>
+
+ <xi:include href="version-info.xml" xpointer="v250"/>
</listitem>
</varlistentry>
also applies to <varname>ExecCondition=</varname>. <varname>ExecCondition=</varname> will also run the commands
in <varname>ExecStopPost=</varname>, as part of stopping the service, in the case of any non-zero or abnormal
exits, like the ones described above.</para>
+
+ <xi:include href="version-info.xml" xpointer="v243"/>
</listitem>
</varlistentry>
of auto-restarts from <varname>RestartSec=</varname> to <varname>RestartMaxDelaySec=</varname>.
Takes a positive integer or 0 to disable it. Defaults to 0.</para>
- <para>This setting is effective only if <varname>RestartMaxDelaySec=</varname> is also set.</para></listitem>
+ <para>This setting is effective only if <varname>RestartMaxDelaySec=</varname> is also set.</para>
+
+ <xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
<varlistentry>
in the same format as <varname>RestartSec=</varname>, or <literal>infinity</literal>
to disable the setting. Defaults to <literal>infinity</literal>.</para>
- <para>This setting is effective only if <varname>RestartSteps=</varname> is also set.</para></listitem>
+ <para>This setting is effective only if <varname>RestartSteps=</varname> is also set.</para>
+
+ <xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
<varlistentry>
provided the service repeats <literal>EXTEND_TIMEOUT_USEC=…</literal> within the interval specified
until the service startup status is finished by <literal>READY=1</literal>. (see
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v188"/></listitem>
</varlistentry>
<varlistentry>
provided the service repeats <literal>EXTEND_TIMEOUT_USEC=…</literal> within the interval specified,
or terminates itself (see
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v188"/></listitem>
</varlistentry>
<varlistentry>
provided the service repeats <literal>EXTEND_TIMEOUT_USEC=…</literal> within the interval specified,
or terminates itself (see
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v243"/></listitem>
</varlistentry>
<varlistentry>
By using <option>kill</option> the service is immediately terminated by sending
<varname>FinalKillSignal=</varname> without any further timeout. This setting can be used to expedite the
shutdown of failing services.
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v246"/></listitem>
</varlistentry>
<varlistentry>
provided the service repeats <literal>EXTEND_TIMEOUT_USEC=…</literal> within the interval specified
until the service shutdown is achieved by <literal>STOPPING=1</literal> (or termination). (see
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v229"/></listitem>
</varlistentry>
<varlistentry>
<listitem><para>This option modifies <varname>RuntimeMaxSec=</varname> by increasing the maximum runtime by an
evenly distributed duration between 0 and the specified value (in seconds). If <varname>RuntimeMaxSec=</varname> is
unspecified, then this feature will be disabled.
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v250"/></listitem>
</varlistentry>
<varlistentry>
<para>This option is useful in cases where a dependency can fail temporarily
but we don't want these temporary failures to make the dependent units fail.
When this option is set to <option>direct</option>, dependent units are not notified of these temporary failures.</para>
+
+ <xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
</varlistentry>
</example>
<para>Note: <command>systemd-analyze exit-status</command> may be used to list exit statuses and
- translate between numerical status values and names.</para></listitem>
+ translate between numerical status values and names.</para>
+
+ <xi:include href="version-info.xml" xpointer="v189"/></listitem>
</varlistentry>
<varlistentry>
<varname>ExecStopPost=</varname> or <varname>ExecReload=</varname>, but only on the main service
process, i.e. either the one invoked by <varname>ExecStart=</varname> or (depending on
<varname>Type=</varname>, <varname>PIDFile=</varname>, …) the otherwise configured main
- process.</para></listitem>
+ process.</para>
+
+ <xi:include href="version-info.xml" xpointer="v189"/></listitem>
</varlistentry>
<varlistentry>
service restarts, regardless of the restart setting configured
with <varname>Restart=</varname>. The argument format is
similar to
- <varname>RestartPreventExitStatus=</varname>.</para></listitem>
+ <varname>RestartPreventExitStatus=</varname>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v215"/></listitem>
</varlistentry>
<varlistentry>
<para>If this option is set to a non-zero value the <varname>$FDSTORE</varname> environment variable
will be set for processes invoked for this service. See
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
- details.</para></listitem>
+ details.</para>
+
+ <para>For further information on the file descriptor store see the <ulink
+ url="https://systemd.io/FILE_DESCRIPTOR_STORE">File Descriptor Store</ulink> overview.</para>
+
+ <xi:include href="version-info.xml" xpointer="v219"/></listitem>
</varlistentry>
<varlistentry>
file descriptor store pinned until the service manager exits.</para>
<para>Use <command>systemctl clean --what=fdstore …</command> to release the file descriptor store
- explicitly.</para></listitem>
+ explicitly.</para>
+
+ <xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
<varlistentry>
socket unit with <varname>ListenUSBFunction=</varname>
configured. The contents of this file are written to the
<filename>ep0</filename> file after it is
- opened.</para></listitem>
+ opened.</para>
+
+ <xi:include href="version-info.xml" xpointer="v227"/></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Configure the location of a file containing
USB FunctionFS strings. Behavior is similar to
<varname>USBFunctionDescriptors=</varname>
- above.</para></listitem>
+ above.</para>
+
+ <xi:include href="version-info.xml" xpointer="v227"/></listitem>
</varlistentry>
<varlistentry id='oom-policy'>
<constant>stop</constant> the event is logged but the unit is terminated cleanly by the service
manager. If set to <constant>kill</constant> and one of the unit's processes is killed by the OOM
killer the kernel is instructed to kill all remaining processes of the unit too, by setting the
- <filename>memory.oom.group</filename> attribute to <constant>1</constant>; also see <ulink
- url="https://docs.kernel.org/admin-guide/cgroup-v2.html">kernel documentation</ulink>.</para>
+ <filename>memory.oom.group</filename> attribute to <constant>1</constant>; also see kernel
+ page <ulink url="https://docs.kernel.org/admin-guide/cgroup-v2.html">Control Group v2</ulink>.
+ </para>
<para>Defaults to the setting <varname>DefaultOOMPolicy=</varname> in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
<para>This setting also applies to
<citerefentry><refentrytitle>systemd-oomd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
Similarly to the kernel OOM kills performed by the kernel, this setting determines the state of the
- unit after <command>systemd-oomd</command> kills a cgroup associated with it.</para></listitem>
+ unit after <command>systemd-oomd</command> kills a cgroup associated with it.</para>
+
+ <xi:include href="version-info.xml" xpointer="v243"/></listitem>
</varlistentry>
<varlistentry>
(due to running in a separate mount namespace, not having privileges, ...).</para>
<para>This setting can be specified multiple times, in which case all the specified paths are opened and the file descriptors passed to the service.
- If the empty string is assigned, the entire list of open files defined prior to this is reset.</para></listitem>
+ If the empty string is assigned, the entire list of open files defined prior to this is reset.</para>
+
+ <xi:include href="version-info.xml" xpointer="v253"/></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Configures the UNIX process signal to send to the service's main process when asked
to reload the service's configuration. Defaults to <constant>SIGHUP</constant>. This option has no
effect unless <varname>Type=</varname><option>notify-reload</option> is used, see
- above.</para></listitem>
+ above.</para>
+
+ <xi:include href="version-info.xml" xpointer="v253"/></listitem>
</varlistentry>
</variablelist>
projects / thirdparty / systemd.git / blobdiff