their activated <filename>.socket</filename> units via an
automatic <varname>After=</varname> dependency.</para>
- <para>Unless <varname>DefaultDependencies=</varname> is set to
- <option>false</option>, service units will implicitly have
- dependencies of type <varname>Requires=</varname> and
- <varname>After=</varname> on <filename>sysinit.target</filename>,
- a dependency of type <varname>After=</varname> on
- <filename>basic.target</filename> as well as dependencies of
- type <varname>Conflicts=</varname> and <varname>Before=</varname>
- on <filename>shutdown.target</filename>. These ensure that normal
- service units pull in basic system initialization, and are
- terminated cleanly prior to system shutdown. Only services
- involved with early boot or late system shutdown should disable
- this option.</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
+ <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <varname>After=</varname> on
+ <filename>basic.target</filename> as well as dependencies of type <varname>Conflicts=</varname> and
+ <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure that normal service units pull in
+ basic system initialization, and are terminated cleanly prior to system shutdown. Only services involved with early
+ boot or late system shutdown should disable this option.</para>
<para>Instanced service units (i.e. service units with an <literal>@</literal> in their name) are assigned by
default a per-template slice unit (see
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 not set, it will be
- implicitly set to <option>main</option>. Note that currently
+ <varname>NotifyAccess=</varname> is missing or set to
+ <option>none</option>, it will be forcibly set to
+ <option>main</option>. Note that currently
<varname>Type=</varname><option>notify</option> will not work
if used in combination with
<varname>PrivateNetwork=</varname><option>yes</option>.</para>
</listitem>
</varlistentry>
- <varlistentry>
- <term><varname>BusPolicy=</varname></term>
-
- <listitem><para>If specified, a custom kdbus
- endpoint will be created and installed as the default bus node
- for the service. Such a custom endpoint can hold an own set of
- policy rules that are enforced on top of the bus-wide ones.
- The custom endpoint is named after the service it was created
- for, and its node will be bind-mounted over the default bus
- node location, so the service can only access the bus through
- its own endpoint. Note that custom bus endpoints default to a
- "deny all" policy. Hence, if at least one
- <varname>BusPolicy=</varname> directive is given, you have to
- make sure to add explicit rules for everything the service
- should be able to do.</para>
- <para>The value of this directive is comprised
- of two parts; the bus name, and a verb to
- specify to granted access, which is one of
- <option>see</option>,
- <option>talk</option>, or
- <option>own</option>.
- <option>talk</option> implies
- <option>see</option>, and <option>own</option>
- implies both <option>talk</option> and
- <option>see</option>.
- If multiple access levels are specified for the
- same bus name, the most powerful one takes
- effect.
- </para>
- <para>Examples:</para>
- <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting>
- <programlisting>BusPolicy=org.foo.bar see</programlisting>
- <para>This option is only available on kdbus enabled systems.</para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><varname>ExecStart=</varname></term>
<listitem><para>Commands with their arguments that are
<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 both
- <literal>-</literal> and <literal>@</literal> are used, they
- can appear in either order.</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
with a <literal>-</literal> exit successfully.</para>
<para><varname>ExecStartPost=</varname> commands are only run after
- the service has started, as determined by <varname>Type=</varname>
+ the service has started successfully, as determined by <varname>Type=</varname>
(i.e. the process has been started for <varname>Type=simple</varname>
or <varname>Type=idle</varname>, the process exits successfully for
<varname>Type=oneshot</varname>, the initial process exits successfully
used to start long-running processes. All processes forked
off by processes invoked via <varname>ExecStartPre=</varname> will
be killed before the next service process is run.</para>
+
+ <para>Note that if any of the commands specified in <varname>ExecStartPre=</varname>,
+ <varname>ExecStart=</varname>, or <varname>ExecStartPost=</varname> fail (and are not prefixed with
+ <literal>-</literal>, see above) or time out before the service is fully up, execution continues with commands
+ specified in <varname>ExecStopPost=</varname>, the commands in <varname>ExecStop=</varname> are skipped.</para>
</listitem>
</varlistentry>
<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></listitem>
+ 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
+ start-up failed, for example because any of the commands specified in <varname>ExecStart=</varname>,
+ <varname>ExecStartPre=</varname> or <varname>ExecStartPost=</varname> failed (and weren't prefixed with
+ <literal>-</literal>, see above) or timed out. Use <varname>ExecStopPost=</varname> to invoke commands when a
+ service failed to start up correctly and is shut down again.</para>
+
+ <para>It is recommended to use this setting for commands that communicate with the service requesting clean
+ termination. When the commands specified with this option are executed it should be assumed that the service is
+ still fully up and is able to react correctly to all commands. For post-mortem clean-up steps use
+ <varname>ExecStopPost=</varname> instead.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>ExecStopPost=</varname></term>
- <listitem><para>Additional commands that are executed after
- the service was stopped. This includes cases where the
- commands configured in <varname>ExecStop=</varname> were used,
- where the service does not have any
- <varname>ExecStop=</varname> defined, or where the service
- exited unexpectedly. This argument takes multiple command
- lines, following the same scheme as described for
- <varname>ExecStart=</varname>. Use of these settings is
- optional. Specifier and environment variable substitution is
- supported.</para></listitem>
+ <listitem><para>Additional commands that are executed after the service is stopped. This includes cases where
+ the commands configured in <varname>ExecStop=</varname> were used, where the service does not have any
+ <varname>ExecStop=</varname> defined, or where the service exited unexpectedly. This argument takes multiple
+ command lines, following the same scheme as described for <varname>ExecStart=</varname>. Use of these settings
+ is optional. Specifier and environment variable substitution is supported. Note that – unlike
+ <varname>ExecStop=</varname> – commands specified with this setting are invoked when a service failed to start
+ up correctly and is shut down again.</para>
+
+ <para>It is recommended to use this setting for clean-up operations that shall be executed even when the
+ 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>
</varlistentry>
<varlistentry>
effect.</para></listitem>
</varlistentry>
- <varlistentry>
- <term><varname>StartLimitInterval=</varname></term>
- <term><varname>StartLimitBurst=</varname></term>
-
- <listitem><para>Configure service start rate limiting. By
- default, services which are started more than 5 times within
- 10 seconds are not permitted to start any more times until the
- 10 second interval ends. With these two options, this rate
- limiting may be modified. Use
- <varname>StartLimitInterval=</varname> to configure the
- checking interval (defaults to
- <varname>DefaultStartLimitInterval=</varname> in manager
- configuration file, set to 0 to disable any kind of rate
- limiting). Use <varname>StartLimitBurst=</varname> to
- configure how many starts per interval are allowed (defaults
- to <varname>DefaultStartLimitBurst=</varname> in manager
- configuration file). These configuration options are
- particularly useful in conjunction with
- <varname>Restart=</varname>; however, they apply to all kinds
- of starts (including manual), not just those triggered by the
- <varname>Restart=</varname> logic. Note that units which are
- configured for <varname>Restart=</varname> and which reach the
- start limit are not attempted to be restarted anymore;
- however, they may still be restarted manually at a later
- point, from which point on, the restart logic is again
- activated. Note that <command>systemctl reset-failed</command>
- will cause the restart rate counter for a service to be
- flushed, which is useful if the administrator wants to
- manually start a service and the start limit interferes with
- that.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>StartLimitAction=</varname></term>
-
- <listitem><para>Configure the action to take if the rate limit
- configured with <varname>StartLimitInterval=</varname> and
- <varname>StartLimitBurst=</varname> is hit. Takes one of
- <option>none</option>,
- <option>reboot</option>,
- <option>reboot-force</option>,
- <option>reboot-immediate</option>,
- <option>poweroff</option>,
- <option>poweroff-force</option> or
- <option>poweroff-immediate</option>. If
- <option>none</option> is set, hitting the rate limit will
- trigger no action besides that the start will not be
- permitted. <option>reboot</option> causes a reboot following
- the normal shutdown procedure (i.e. equivalent to
- <command>systemctl reboot</command>).
- <option>reboot-force</option> causes a forced reboot which
- will terminate all processes forcibly but should cause no
- dirty file systems on reboot (i.e. equivalent to
- <command>systemctl reboot -f</command>) and
- <option>reboot-immediate</option> causes immediate execution
- of the
- <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- system call, which might result in data loss. Similarly,
- <option>poweroff</option>, <option>poweroff-force</option>,
- <option>poweroff-immediate</option> have the effect of
- powering down the system with similar semantics. Defaults to
- <option>none</option>.</para></listitem>
- </varlistentry>
-
<varlistentry>
<term><varname>FailureAction=</varname></term>
- <listitem><para>Configure the action to take when the service
- enters a failed state. Takes the same values as
- <varname>StartLimitAction=</varname> and executes the same
- actions. Defaults to <option>none</option>. </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>RebootArgument=</varname></term>
- <listitem><para>Configure the optional argument for the
- <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- system call if <varname>StartLimitAction=</varname> or
- <varname>FailureAction=</varname> is a reboot action. This
- works just like the optional argument to <command>systemctl
- reboot</command> command.</para></listitem>
+ <listitem><para>Configure the action to take when the service enters a failed state. Takes the same values as
+ the unit setting <varname>StartLimitAction=</varname> and executes the same actions (see
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Defaults to
+ <option>none</option>. </para></listitem>
</varlistentry>
<varlistentry>
projects / thirdparty / systemd.git / blobdiff