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 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. Also note that settings from the
+ <literal>[Install]</literal> section are not available 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. -->
above.</para></listitem>
</varlistentry>
- <varlistentry>
- <term><varname>RequiresOverridable=</varname></term>
-
- <listitem><para>Similar to <varname>Requires=</varname>.
- Dependencies listed in <varname>RequiresOverridable=</varname>
- which cannot be fulfilled or fail to start are ignored if the
- startup was explicitly requested by the user. If the start-up
- was pulled in indirectly by some dependency or automatic
- start-up of units that is not requested by the user, this
- dependency must be fulfilled and otherwise the transaction
- fails. Hence, this option may be used to configure
- dependencies that are normally honored unless the user
- explicitly starts up the unit, in which case whether they
- failed or not is irrelevant.</para></listitem>
-
- </varlistentry>
<varlistentry>
<term><varname>Requisite=</varname></term>
- <term><varname>RequisiteOverridable=</varname></term>
- <listitem><para>Similar to <varname>Requires=</varname> and
- <varname>RequiresOverridable=</varname>, respectively.
+ <listitem><para>Similar to <varname>Requires=</varname>.
However, if the units listed here are not started already,
they will not be started and the transaction will fail
immediately. </para></listitem>
<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
<para><varname>ConditionSecurity=</varname> may be used to
check whether the given security module is enabled on the
- system. Currently, the recognized values values are
+ system. Currently, the recognized values are
<varname>selinux</varname>,
<varname>apparmor</varname>,
<varname>ima</varname>,
<filename>/var</filename> on the next following boot. Units
making use of this condition should order themselves before
<citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
- to make sure they run before the stamp files's modification
+ to make sure they run before the stamp file's modification
time gets reset indicating a completed update.</para>
<para><varname>ConditionFirstBoot=</varname> takes a boolean
<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 it was triggered by (which means this is logged about
+ loudly). Use assertion expressions for units that cannot operate when specific requirements are not met, and
+ where 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>
<row>
<entry><literal>%u</literal></entry>
<entry>User name</entry>
- <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
+ <entry>This is the name of the user running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry>
</row>
<row>
<entry><literal>%U</literal></entry>
<entry>User UID</entry>
- <entry>This is the numeric UID of the configured user of the unit, or (if none is set) the user running the systemd user instance. Note that this specifier is not available for units run by the systemd system instance (as opposed to those run by a systemd user instance), unless the user has been configured as a numeric UID in the first place or the configured user is the root user.</entry>
+ <entry>This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to <literal>0</literal>.</entry>
</row>
<row>
<entry><literal>%h</literal></entry>
<entry>User home directory</entry>
- <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry>
+ <entry>This is the home directory of the user running the service manager instance. In case of the system manager this resolves to <literal>/root</literal>.</entry>
</row>
<row>
<entry><literal>%s</literal></entry>
<entry>User shell</entry>
- <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry>
+ <entry>This is the shell of the user running the service manager instance. In case of the system manager this resolves to <literal>/bin/sh</literal>.</entry>
</row>
<row>
<entry><literal>%m</literal></entry>
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