<para><literallayout><filename>/etc/systemd/system/*</filename>
<filename>/run/systemd/system/*</filename>
<filename>/usr/lib/systemd/system/*</filename>
-<filename>...</filename>
+<filename>…</filename>
</literallayout></para>
- <para><literallayout><filename>$XDG_CONFIG_HOME/systemd/user/*</filename>
-<filename>$HOME/.config/systemd/user/*</filename>
+ <para><literallayout><filename>~/.config/systemd/user/*</filename>
<filename>/etc/systemd/user/*</filename>
<filename>$XDG_RUNTIME_DIR/systemd/user/*</filename>
<filename>/run/systemd/user/*</filename>
-<filename>$XDG_DATA_HOME/systemd/user/*</filename>
-<filename>$HOME/.local/share/systemd/user/*</filename>
+<filename>~/.local/share/systemd/user/*</filename>
<filename>/usr/lib/systemd/user/*</filename>
-<filename>...</filename>
+<filename>…</filename>
</literallayout></para>
</refsynopsisdiv>
directory suffix is <filename>.requires/</filename> in this
case.</para>
- <para>Along with a unit file <filename>foo.service</filename>, a
- directory <filename>foo.service.d/</filename> may exist. All files
- with the suffix <literal>.conf</literal> from this directory will
- be parsed after the file itself is parsed. This is useful to alter
- or add configuration settings to a unit, without having to modify
- their unit files. Make sure that the file that is included has the
- appropriate section headers before any directive. Note that, for
- instanced units, this logic will first look for the instance
- <literal>.d/</literal> subdirectory and read its
- <literal>.conf</literal> files, followed by the template
- <literal>.d/</literal> subdirectory and reads its
- <literal>.conf</literal> files.</para>
-
+ <para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory
+ <filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this
+ directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings for
+ a unit, without having to modify unit files. Each drop-in file must have appropriate section headers. Note that for
+ instantiated units, this logic will first look for the instance <literal>.d/</literal> subdirectory and read its
+ <literal>.conf</literal> files, followed by the template <literal>.d/</literal> subdirectory and the
+ <literal>.conf</literal> files there. Also note that settings from the <literal>[Install]</literal> section are not
+ honoured in drop-in unit files, and have no effect.</para>
+
+ <para>In addition to <filename>/etc/systemd/system</filename>,
+ the drop-in <literal>.conf</literal> files for system services
+ can be placed in <filename>/usr/lib/systemd/system</filename> or
+ <filename>/run/systemd/system</filename> directories. Drop-in
+ files in <filename>/etc</filename> take precedence over those in
+ <filename>/run</filename> which in turn take precedence over
+ those in <filename>/usr/lib</filename>. Drop-in files under any of
+ these directories take precedence over unit files wherever located.
+ (Of course, since <filename>/run</filename> is temporary and
+ <filename>/usr/lib</filename> is for vendors, it is unlikely
+ drop-ins should be used in either of those places.)</para>
<!-- Note that we do not document .include here, as we
consider it mostly obsolete, and want people to
use .d/ drop-ins instead. -->
between them are shut down, the inverse of the start-up order
is applied. i.e. if a unit is configured with
<varname>After=</varname> on another unit, the former is
- stopped before the latter if both are shut down. If one unit
- with an ordering dependency on another unit is shut down while
- the latter is started up, the shut down is ordered before the
- start-up regardless of whether the ordering dependency is
- actually of type <varname>After=</varname> or
- <varname>Before=</varname>. If two units have no ordering
- dependencies between them, they are shut down or started up
- simultaneously, and no ordering takes place.
+ stopped before the latter if both are shut down. Given two units
+ with any ordering dependency between them, if one unit is shut
+ down and the other is started up, the shutdown is ordered
+ before the start-up. It doesn't matter if the ordering
+ dependency is <varname>After=</varname> or
+ <varname>Before=</varname>. It also doesn't matter which of the
+ two is shut down, as long as one is shut down and the other is
+ started up. The shutdown is ordered before the start-up in all
+ cases. If two units have no ordering dependencies between them,
+ they are shut down or started up simultaneously, and no ordering
+ takes place.
</para></listitem>
</varlistentry>
<term><varname>JobTimeoutAction=</varname></term>
<term><varname>JobTimeoutRebootArgument=</varname></term>
- <listitem><para>When a job for this unit is queued, a time-out
- may be configured. If this time limit is reached, the job will
- be cancelled, the unit however will not change state or even
- enter the <literal>failed</literal> mode. This value defaults
- to 0 (job timeouts disabled), except for device units. NB:
- this timeout is independent from any unit-specific timeout
- (for example, the timeout set with
- <varname>TimeoutStartSec=</varname> in service units) as the
- job timeout has no effect on the unit itself, only on the job
- that might be pending for it. Or in other words: unit-specific
- timeouts are useful to abort unit state changes, and revert
- them. The job timeout set with this option however is useful
- to abort only the job waiting for the unit state to
- change.</para>
+ <listitem><para>When a job for this unit is queued, a time-out may be configured. If this time limit is
+ reached, the job will be cancelled, the unit however will not change state or even enter the
+ <literal>failed</literal> mode. This value defaults to <literal>infinity</literal> (job timeouts disabled),
+ except for device units. NB: this timeout is independent from any unit-specific timeout (for example, the
+ timeout set with <varname>TimeoutStartSec=</varname> in service units) as the job timeout has no effect on the
+ unit itself, only on the job that might be pending for it. Or in other words: unit-specific timeouts are useful
+ to abort unit state changes, and revert them. The job timeout set with this option however is useful to abort
+ only the job waiting for the unit state to change.</para>
<para><varname>JobTimeoutAction=</varname>
optionally configures an additional
system call.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>StartLimitInterval=</varname></term>
+ <term><varname>StartLimitBurst=</varname></term>
+
+ <listitem><para>Configure unit start rate limiting. By default, units 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 the service
+ setting <varname>Restart=</varname> (see
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>); 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 unit 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>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 a service's <varname>FailureAction=</varname> is a reboot action. This
+ works just like the optional argument to <command>systemctl reboot</command> command.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>ConditionArchitecture=</varname></term>
<term><varname>ConditionVirtualization=</varname></term>
useful and probably just
confusing. -->
- <listitem><para>Before starting a unit verify that the
- specified condition is true. If it is not true, the starting
- of the unit will be skipped, however all ordering dependencies
- of it are still respected. A failing condition will not result
- in the unit being moved into a failure state. The condition is
- checked at the time the queued start job is to be
- executed.</para>
+ <listitem><para>Before starting a unit, verify that the specified condition is true. If it is not true, the
+ starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still
+ respected. A failing condition will not result in the unit being moved into a failure state. The condition is
+ checked at the time the queued start job is to be executed. Use condition expressions in order to silently skip
+ units that do not apply to the local running system, for example because the kernel or runtime environment
+ doesn't require its functionality. Use the various <varname>AssertArchitecture=</varname>,
+ <varname>AssertVirtualization=</varname>, … options for a similar mechanism that puts the unit in a failure
+ state and logs about the failed check (see below).</para>
<para><varname>ConditionArchitecture=</varname> may be used to
check whether the system is running on a specific
<term><varname>AssertFileNotEmpty=</varname></term>
<term><varname>AssertFileIsExecutable=</varname></term>
- <listitem><para>Similar to the
- <varname>ConditionArchitecture=</varname>,
- <varname>ConditionVirtualization=</varname>, etc., condition
- settings described above, these settings add assertion checks
- to the start-up of the unit. However, unlike the conditions
- settings, any assertion setting that is not met results in
- failure of the start job it was triggered
- by.</para></listitem>
+ <listitem><para>Similar to the <varname>ConditionArchitecture=</varname>,
+ <varname>ConditionVirtualization=</varname>, …, condition settings described above, these settings add
+ assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting
+ that is not met results in failure of the start job (which means this is logged loudly). Use assertion
+ expressions for units that cannot operate when specific requirements are not met, and when this is something
+ the administrator or user should look into.</para></listitem>
</varlistentry>
<varlistentry>
<refsect1>
<title>[Install] Section Options</title>
- <para>Unit file may include an <literal>[Install]</literal>
- section, which carries installation information for the unit. This
- section is not interpreted by
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- during runtime. It is used exclusively by the
- <command>enable</command> and <command>disable</command> commands
- of the
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- tool during installation of a unit:</para>
+ <para>Unit files may include an <literal>[Install]</literal> section, which carries installation information for
+ the unit. This section is not interpreted by
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> during runtime; it is
+ used by the <command>enable</command> and <command>disable</command> commands of the
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool during
+ installation of a unit. Note that settings in the <literal>[Install]</literal> section may not appear in
+ <filename>.d/*.conf</filename> unit file drop-ins (see above).</para>
<variablelist class='unit-directives'>
<varlistentry>
cannot be reset to an empty list, so dependencies can only be
added in drop-ins. If you want to remove dependencies, you have
to override the entire unit.</para>
+
</example>
</refsect1>
projects / thirdparty / systemd.git / blobdiff