<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.</para>
+ over unit files wherever located. Multiple drop-in files with different names are applied in
+ lexicographic order, regardless of which of the directories they reside in.</para>
<!-- Note that we do not document .include here, as we consider it mostly obsolete, and want
people to use .d/ drop-ins instead. -->
<para>The unit file format is covered by the
<ulink
- url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
+ url="https://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
Stability Promise</ulink>.</para>
</refsect1>
<varlistentry>
<term><varname>Requires=</varname></term>
- <listitem><para>Configures requirement dependencies on other
- units. If this unit gets activated, the units listed here will
- be activated as well. If one of the other units gets
- deactivated or its activation fails, this unit will be
- deactivated. This option may be specified more than once or
- multiple space-separated units may be specified in one option
- in which case requirement dependencies for all listed names
- will be created. Note that requirement dependencies do not
- influence the order in which services are started or stopped.
- This has to be configured independently with the
- <varname>After=</varname> or <varname>Before=</varname>
- options. If a unit <filename>foo.service</filename> requires a
- unit <filename>bar.service</filename> as configured with
- <varname>Requires=</varname> and no ordering is configured
- with <varname>After=</varname> or <varname>Before=</varname>,
- then both units will be started simultaneously and without any
- delay between them if <filename>foo.service</filename> is
- activated. Often, it is a better choice to use
- <varname>Wants=</varname> instead of
- <varname>Requires=</varname> in order to achieve a system that
- is more robust when dealing with failing services.</para>
-
- <para>Note that dependencies of this type may also be
- configured outside of the unit configuration file by adding a
- symlink to a <filename>.requires/</filename> directory
- accompanying the unit file. For details, see
+ <listitem><para>Configures requirement dependencies on other units. If this unit gets activated, the units
+ listed here will be activated as well. If one of the other units gets deactivated or its activation fails, this
+ unit will be deactivated. This option may be specified more than once or multiple space-separated units may be
+ specified in one option in which case requirement dependencies for all listed names will be created. Note that
+ requirement dependencies do not influence the order in which services are started or stopped. This has to be
+ configured independently with the <varname>After=</varname> or <varname>Before=</varname> options. If a unit
+ <filename>foo.service</filename> requires a unit <filename>bar.service</filename> as configured with
+ <varname>Requires=</varname> and no ordering is configured with <varname>After=</varname> or
+ <varname>Before=</varname>, then both units will be started simultaneously and without any delay between them
+ if <filename>foo.service</filename> is activated. Often, it is a better choice to use <varname>Wants=</varname>
+ instead of <varname>Requires=</varname> in order to achieve a system that is more robust when dealing with
+ failing services.</para>
+
+ <para>Note that this dependency type does not imply that the other unit always has to be in active state when
+ this unit is running. Specifically: failing condition checks (such as <varname>ConditionPathExists=</varname>,
+ <varname>ConditionPathExists=</varname>, … — see below) do not cause the start job of a unit with a
+ <varname>Requires=</varname> dependency on it to fail. Also, some unit types may deactivate on their own (for
+ example, a service process may decide to exit cleanly, or a device may be unplugged by the user), which is not
+ propagated to units having a <varname>Requires=</varname> dependency. Use the <varname>BindsTo=</varname>
+ dependency type together with <varname>After=</varname> to ensure that a unit may never be in active state
+ without a specific other unit also in active state (see below).</para>
+
+ <para>Note that dependencies of this type may also be configured outside of the unit configuration file by
+ adding a symlink to a <filename>.requires/</filename> directory accompanying the unit file. For details, see
above.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>BindsTo=</varname></term>
- <listitem><para>Configures requirement dependencies, very
- similar in style to <varname>Requires=</varname>, however in
- addition to this behavior, it also declares that this unit is
- stopped when any of the units listed suddenly disappears.
- Units can suddenly, unexpectedly disappear if a service
- terminates on its own choice, a device is unplugged or a mount
- point unmounted without involvement of
- systemd.</para></listitem>
+ <listitem><para>Configures requirement dependencies, very similar in style to
+ <varname>Requires=</varname>. However, this dependency type is stronger: in addition to the effect of
+ <varname>Requires=</varname> it declares that if the unit bound to is stopped, this unit will be stopped
+ too. This means a unit bound to another unit that suddenly enters inactive state will be stopped too.
+ Units can suddenly, unexpectedly enter inactive state for different reasons: the main process of a service unit
+ might terminate on its own choice, the backing device of a device unit might be unplugged or the mount point of
+ a mount unit might be unmounted without involvement of the system and service manager.</para>
+
+ <para>When used in conjunction with <varname>After=</varname> on the same unit the behaviour of
+ <varname>BindsTo=</varname> is even stronger. In this case, the unit bound to strictly has to be in active
+ state for this unit to also be in active state. This not only means a unit bound to another unit that suddenly
+ enters inactive state, but also one that is bound to another unit that gets skipped due to a failed condition
+ check (such as <varname>ConditionPathExists=</varname>, <varname>ConditionPathIsSymbolicLink=</varname>, … —
+ see below) will be stopped, should it be running. Hence, in many cases it is best to combine
+ <varname>BindsTo=</varname> with <varname>After=</varname>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Before=</varname></term>
<term><varname>After=</varname></term>
- <listitem><para>A space-separated list of unit names.
- Configures ordering dependencies between units. If a unit
- <filename>foo.service</filename> contains a setting
- <option>Before=bar.service</option> and both units are being
- started, <filename>bar.service</filename>'s start-up is
- delayed until <filename>foo.service</filename> is started up.
- Note that this setting is independent of and orthogonal to the
- requirement dependencies as configured by
- <varname>Requires=</varname>. It is a common pattern to
- include a unit name in both the <varname>After=</varname> and
- <varname>Requires=</varname> option, in which case the unit
- listed will be started before the unit that is configured with
- these options. This option may be specified more than once, in
- which case ordering dependencies for all listed names are
- created. <varname>After=</varname> is the inverse of
- <varname>Before=</varname>, i.e. while
- <varname>After=</varname> ensures that the configured unit is
- started after the listed unit finished starting up,
- <varname>Before=</varname> ensures the opposite, i.e. that the
- configured unit is fully started up before the listed unit is
- started. Note that when two units with an ordering dependency
- 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. 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>
+ <listitem><para>A space-separated list of unit names. Configures ordering dependencies between units. If a
+ unit <filename>foo.service</filename> contains a setting <option>Before=bar.service</option> and both units are
+ being started, <filename>bar.service</filename>'s start-up is delayed until <filename>foo.service</filename> is
+ started up. Note that this setting is independent of and orthogonal to the requirement dependencies as
+ configured by <varname>Requires=</varname>, <varname>Wants=</varname> or <varname>BindsTo=</varname>. It is a
+ common pattern to include a unit name in both the <varname>After=</varname> and <varname>Requires=</varname>
+ option, in which case the unit listed will be started before the unit that is configured with these
+ options. This option may be specified more than once, in which case ordering dependencies for all listed names
+ are created. <varname>After=</varname> is the inverse of <varname>Before=</varname>, i.e. while
+ <varname>After=</varname> ensures that the configured unit is started after the listed unit finished starting
+ up, <varname>Before=</varname> ensures the opposite, i.e. that the configured unit is fully started up before
+ the listed unit is started. Note that when two units with an ordering dependency 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. 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>, in this case. 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>
<varlistentry>
all mount units required to access the specified path.</para>
<para>Mount points marked with <option>noauto</option> are not
- mounted automatically and will be ignored for the purposes of
- this option. If such a mount should be a requirement for this
- unit, direct dependencies on the mount units may be added
- (<varname>Requires=</varname> and <varname>After=</varname> or
- some other combination). </para></listitem>
+ mounted automatically through <filename>local-fs.target</filename>,
+ but are still honored for the purposes of this option, i.e. they
+ will be pulled in by this unit.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>JobTimeoutSec=</varname></term>
+ <term><varname>JobRunningTimeoutSec=</varname></term>
<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 <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>
+ <listitem><para>When a job for this unit is queued, a time-out <varname>JobTimeoutSec=</varname> may be
+ configured. Similarly, <varname>JobRunningTimeoutSec=</varname> starts counting when the queued job is actually
+ started. If either 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 (<varname>JobRunningTimeoutSec=</varname> defaults to
+ <varname>DefaultTimeoutStartSec=</varname>). 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
<varname>arm64-be</varname>,
<varname>sh</varname>,
<varname>sh64</varname>,
- <varname>m86k</varname>,
+ <varname>m68k</varname>,
<varname>tilegx</varname>,
- <varname>cris</varname> to test
+ <varname>cris</varname>,
+ <varname>arc</varname>,
+ <varname>arc-be</varname> to test
against a specific architecture. The architecture is
determined from the information returned by
<citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
file <filename><replaceable>name</replaceable>.conf</filename>
there that only changes the specific settings one is interested
in. Note that multiple such drop-in files are read if
- present.</para>
+ present, processed in lexicographic order of their filename.</para>
<para>The advantage of the first method is that one easily
overrides the complete unit, the vendor unit is not parsed at
ordered appropriately (<varname>After=</varname>). Thirdly, in
order to harden the service a bit more, the administrator would
like to set the <varname>PrivateTmp=</varname> setting (see
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details). And lastly, the administrator would like to reset
the niceness of the service to its default value of 0.</para>
projects / thirdparty / systemd.git / blobdiff