This is useful for compatibility with SysV. Note that this
compatibility is quite comprehensive but not 100%. For details
about the incompatibilities, see the <ulink
- url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
+ url="https://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
with SysV</ulink> document.</para>
</refsect1>
<varname>After=</varname> on
<filename>dbus.socket</filename>.</para>
- <para>Socket activated service are automatically ordered after
- their activated <filename>.socket</filename> units via an
- automatic <varname>After=</varname> dependency.</para>
+ <para>Socket activated services are automatically ordered after
+ their activating <filename>.socket</filename> units via an
+ automatic <varname>After=</varname> dependency.
+ Services also pull in all <filename>.socket</filename> units
+ listed in <varname>Sockets=</varname> via automatic
+ <varname>Wants=</varname> and <varname>After=</varname> dependencies.</para>
<para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> is set to
<option>false</option>, service units will implicitly have dependencies of type <varname>Requires=</varname> and
process it supervises. A number of options that may be used in
this section are shared with other unit types. These options are
documented in
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
and
- <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
The options specific to the <literal>[Service]</literal> section
of service units are the following:</para>
process has to exit before systemd starts follow-up units.
<varname>RemainAfterExit=</varname> is particularly useful for
this type of service. This is the implied default if neither
- <varname>Type=</varname> or <varname>ExecStart=</varname> are
+ <varname>Type=</varname> nor <varname>ExecStart=</varname> are
specified.</para>
<para>Behavior of <option>dbus</option> is similar to
if used in combination with
<varname>PrivateNetwork=</varname><option>yes</option>.</para>
- <para>Behavior of <option>idle</option> is very similar to
- <option>simple</option>; however, actual execution of the
- service binary is delayed until all jobs are dispatched. This
- may be used to avoid interleaving of output of shell services
- with the status output on the console.</para>
+ <para>Behavior of <option>idle</option> is very similar to <option>simple</option>; however, actual execution
+ of the service binary is delayed until all active jobs are dispatched. This may be used to avoid interleaving
+ of output of shell services with the status output on the console. Note that this type is useful only to
+ improve console output, it is not useful as a general unit ordering tool, and the effect of this service type
+ is subject to a 5s time-out, after which the service binary is invoked anyway.</para>
</listitem>
</varlistentry>
providing multiple command lines in the same directive, or alternatively, this directive may be specified more
than once with the same effect. If the empty string is assigned to this option, the list of commands to start
is reset, prior assignments of this option will have no effect. If no <varname>ExecStart=</varname> is
- specified, then the service must have <varname>RemainAfterExit=yes</varname> set.</para>
+ specified, then the service must have <varname>RemainAfterExit=yes</varname> and at least one
+ <varname>ExecStop=</varname> line set. (Services lacking both <varname>ExecStart=</varname> and
+ <varname>ExecStop=</varname> are not valid.)</para>
<para>For each of the specified commands, the first argument must be an absolute path to an
executable. Optionally, if this file name is prefixed with <literal>@</literal>, the second token will be
multiple command lines, following the same scheme as described
for <varname>ExecStart=</varname> above. Use of this setting
is optional. After the commands configured in this option are
- run, all processes remaining for a service are terminated
+ run, it is implied that the service is stopped, and any processes
+ remaining for it are terminated
according to the <varname>KillMode=</varname> setting (see
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
If this option is not specified, the process is terminated by
variable substitution is supported (including
<varname>$MAINPID</varname>, see above).</para>
- <para>Note that it is usually not sufficient to specify a
- command for this setting that only asks the service to
- terminate (for example, by queuing some form of termination
- signal for it), but does not wait for it to do so. Since the
- remaining processes of the services are killed using
- <constant>SIGKILL</constant> immediately after the command
- exited, this would not result in a clean stop. The specified
- command should hence be a synchronous operation, not an
- asynchronous one.</para>
+ <para>Note that it is usually not sufficient to specify a command for this setting that only asks the service
+ to terminate (for example, by queuing some form of termination signal for it), but does not wait for it to do
+ so. Since the remaining processes of the services are killed according to <varname>KillMode=</varname> and
+ <varname>KillSignal=</varname> as described above immediately after the command exited, this may not result in
+ a clean stop. The specified command should hence be a synchronous operation, not an asynchronous one.</para>
<para>Note that the commands specified in <varname>ExecStop=</varname> are only executed when the service
started successfully first. They are not invoked if the service was never started at all, or in case its
<para>As exceptions to the setting above, the service will not
be restarted if the exit code or signal is specified in
- <varname>RestartPreventExitStatus=</varname> (see below).
- Also, the services will always be restarted if the exit code
- or signal is specified in
+ <varname>RestartPreventExitStatus=</varname> (see below) or
+ the service is stopped with <command>systemctl stop</command>
+ or an equivalent operation. Also, the services will always be
+ restarted if the exit code or signal is specified in
<varname>RestartForceExitStatus=</varname> (see below).</para>
+ <para>Note that service restart is subject to unit start rate
+ limiting configured with <varname>StartLimitIntervalSec=</varname>
+ and <varname>StartLimitBurst=</varname>, see
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details.</para>
+
<para>Setting this to <option>on-failure</option> is the
recommended choice for long-running services, in order to
increase reliability by attempting automatic recovery from
<varlistentry>
<term><varname>NonBlocking=</varname></term>
- <listitem><para>Set the <constant>O_NONBLOCK</constant> flag
- for all file descriptors passed via socket-based activation.
- If true, all file descriptors >= 3 (i.e. all except stdin,
- stdout, and stderr) will have the
- <constant>O_NONBLOCK</constant> flag set and hence are in
- non-blocking mode. This option is only useful in conjunction
- with a socket unit, as described in
- <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
- Defaults to false.</para></listitem>
+ <listitem><para>Set the <constant>O_NONBLOCK</constant> flag for all file descriptors passed via socket-based
+ activation. If true, all file descriptors >= 3 (i.e. all except stdin, stdout, stderr), excluding those passed
+ in via the file descriptor storage logic (see <varname>FileDescriptorStoreMax=</varname> for details), will
+ have the <constant>O_NONBLOCK</constant> flag set and hence are in non-blocking mode. This option is only
+ useful in conjunction with a socket unit, as described in
+ <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> and has no
+ effect on file descriptors which were previously saved in the file-descriptor store for example. Defaults to
+ false.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>NotifyAccess=</varname></term>
- <listitem><para>Controls access to the service status
- notification socket, as accessible via the
- <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- call. Takes one of <option>none</option> (the default),
- <option>main</option> or <option>all</option>. If
- <option>none</option>, no daemon status updates are accepted
- from the service processes, all status update messages are
- ignored. If <option>main</option>, only service updates sent
- from the main process of the service are accepted. If
- <option>all</option>, all services updates from all members of
- the service's control group are accepted. This option should
- be set to open access to the notification socket when using
- <varname>Type=notify</varname> or
- <varname>WatchdogSec=</varname> (see above). If those options
- are used but <varname>NotifyAccess=</varname> is not
- configured, it will be implicitly set to
- <option>main</option>.</para></listitem>
+ <listitem><para>Controls access to the service status notification socket, as accessible via the
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> call. Takes one
+ of <option>none</option> (the default), <option>main</option>, <option>exec</option> or
+ <option>all</option>. If <option>none</option>, no daemon status updates are accepted from the service
+ processes, all status update messages are ignored. If <option>main</option>, only service updates sent from the
+ main process of the service are accepted. If <option>exec</option>, only service updates sent from any of the
+ main or control processes originating from one of the <varname>Exec*=</varname> commands are accepted. If
+ <option>all</option>, all services updates from all members of the service's control group are accepted. This
+ option should be set to open access to the notification socket when using <varname>Type=notify</varname> or
+ <varname>WatchdogSec=</varname> (see above). If those options are used but <varname>NotifyAccess=</varname> is
+ not configured, it will be implicitly set to <option>main</option>.</para>
+
+ <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if
+ either the sending process is still around at the time PID 1 processes the message, or if the sending process
+ is explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally
+ forked off the process, i.e. on all processes that match <option>main</option> or
+ <option>exec</option>. Conversely, if an auxiliary process of the unit sends an
+ <function>sd_notify()</function> message and immediately exits, the service manager might not be able to
+ properly attribute the message to the unit, and thus will ignore it, even if
+ <varname>NotifyAccess=</varname><option>all</option> is set for it.</para></listitem>
</varlistentry>
<varlistentry>
serialized to <filename>/run</filename> and the file
descriptors passed to the service manager, to allow restarts
without losing state. Defaults to 0, i.e. no file descriptors
- may be stored in the service manager by default. All file
+ may be stored in the service manager. All file
descriptors passed to the service manager from a specific
service are passed back to the service's main process on the
next service restart. Any file descriptors passed to the
service manager are automatically closed when POLLHUP or
POLLERR is seen on them, or when the service is fully stopped
- and no job queued or being executed for it.</para></listitem>
+ and no job is queued or being executed for it.</para></listitem>
</varlistentry>
<varlistentry>
must be passed as separate words). Lone semicolons may be escaped
as <literal>\;</literal>.</para>
- <para>Each command line is split on whitespace, with the first
- item being the command to execute, and the subsequent items being
- the arguments. Double quotes ("...") and single quotes ('...') may
- be used, in which case everything until the next matching quote
- becomes part of the same argument. C-style escapes are also
- supported. The table below contains the list of allowed escape
- patterns. Only patterns which match the syntax in the table are
- allowed; others will result in an error, and must be escaped by
- doubling the backslash. Quotes themselves are removed after
- parsing and escape sequences substituted. In addition, a trailing
- backslash (<literal>\</literal>) may be used to merge lines.
- </para>
+ <para>Each command line is split on whitespace, with the first item being the command to
+ execute, and the subsequent items being the arguments. Double quotes ("…") and single quotes
+ ('…') may be used, in which case everything until the next matching quote becomes part of the
+ same argument. Quotes themselves are removed. C-style escapes are also supported. The table
+ below contains the list of known escape patterns. Only escape patterns which match the syntax in
+ the table are allowed; other patterns may be added in the future and unknown patterns will
+ result in a warning. In particular, any backslashes should be doubled. Finally, a trailing
+ backslash (<literal>\</literal>) may be used to merge lines.</para>
<para>This syntax is intended to be very similar to shell syntax,
but only the meta-characters and expansions described in the
projects / thirdparty / systemd.git / blobdiff