<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
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>
below (see section "Command Lines" below).
</para>
- <para>When <varname>Type=</varname> is not
- <option>oneshot</option>, only one command may and must be
- given. When <varname>Type=oneshot</varname> is used, zero or
- more commands may be specified. This can be specified by
- 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>
-
- <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 passed as <literal>argv[0]</literal> to the
- executed process, followed by the further arguments specified.
- If the absolute filename is prefixed with
- <literal>-</literal>, an exit code of the command normally
- considered a failure (i.e. non-zero exit status or abnormal
- exit due to signal) is ignored and considered success.
- If the absolute path is prefixed with <literal>!</literal> then
- it is executed with full privileges. <literal>-</literal>, <literal>@</literal>, and <literal>!</literal>
- may be used together and they can appear in any order.</para>
+ <para>Unless <varname>Type=</varname> is <option>oneshot</option>, exactly one command must be given. When
+ <varname>Type=oneshot</varname> is used, zero or more commands may be specified. Commands may be specified by
+ 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> 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
+ passed as <literal>argv[0]</literal> to the executed process, followed by the further arguments specified. If
+ the absolute filename is prefixed with <literal>-</literal>, an exit code of the command normally considered a
+ failure (i.e. non-zero exit status or abnormal exit due to signal) is ignored and considered success. If the
+ absolute path is prefixed with <literal>+</literal> then it is executed with full
+ privileges. <literal>@</literal>, <literal>-</literal>, and <literal>+</literal> may be used together and they
+ can appear in any order.</para>
<para>If more than one command is specified, the commands are
invoked sequentially in the order they appear in the unit
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
service failed to start up correctly. Commands configured with this setting need to be able to operate even if
the service failed starting up half-way and left incompletely initialized data around. As the service's
processes have been terminated already when the commands specified with this setting are executed they should
- not attempt to communicate with them.</para></listitem>
+ not attempt to communicate with them.</para>
+
+ <para>Note that all commands that are configured with this setting are invoked with the result code of the
+ service, as well as the main process' exit code and status, set in the <varname>$SERVICE_RESULT</varname>,
+ <varname>$EXIT_CODE</varname> and <varname>$EXIT_STATUS</varname> environment variables, see
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+ details.</para></listitem>
</varlistentry>
<varlistentry>
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
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>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 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
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