<row>
<entry><filename>/run/systemd/generator.early</filename></entry>
<entry>Generated units with high priority (see <replaceable>early-dir</replaceable> in <citerefentry
- ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+ ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
</row>
<row>
<entry><filename>/etc/systemd/system</filename></entry>
<row>
<entry><filename>/run/systemd/generator</filename></entry>
<entry>Generated units with medium priority (see <replaceable>normal-dir</replaceable> in <citerefentry
- ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+ ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
</row>
<row>
<entry><filename>/usr/local/lib/systemd/system</filename></entry>
<row>
<entry><filename>/run/systemd/generator.late</filename></entry>
<entry>Generated units with low priority (see <replaceable>late-dir</replaceable> in <citerefentry
- ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+ ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
</row>
</tbody>
</tgroup>
<row>
<entry><filename>/run/systemd/generator.early</filename></entry>
<entry>Generated units with high priority (see <replaceable>early-dir</replaceable> in <citerefentry
- ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+ ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
</row>
<row>
<entry><filename>$XDG_CONFIG_HOME/systemd/user</filename> or <filename>$HOME/.config/systemd/user</filename></entry>
<row>
<entry><filename>$XDG_RUNTIME_DIR/systemd/generator</filename></entry>
<entry>Generated units with medium priority (see <replaceable>normal-dir</replaceable> in <citerefentry
- ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+ ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
</row>
<row>
<entry><filename>$XDG_DATA_HOME/systemd/user</filename> or <filename>$HOME/.local/share/systemd/user</filename></entry>
<row>
<entry><filename>$XDG_RUNTIME_DIR/systemd/generator.late</filename></entry>
<entry>Generated units with low priority (see <replaceable>late-dir</replaceable> in <citerefentry
- ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+ ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
</row>
</tbody>
</tgroup>
<varlistentry>
<term><varname>Description=</varname></term>
- <listitem><para>A free-form string describing the unit. This
- is intended for use in UIs to show descriptive information
- along with the unit name. The description should contain a
- name that means something to the end user. <literal>Apache2
- Web Server</literal> is a good example. Bad examples are
- <literal>high-performance light-weight HTTP server</literal>
- (too generic) or <literal>Apache2</literal> (too specific and
- meaningless for people who do not know
- Apache).</para></listitem>
+ <listitem><para>A human readable name for the unit. This is used by
+ <command>systemd</command> (and other UIs) as the label for the unit, so this string should
+ identify the unit rather than describe it, despite the name. <literal>Apache2 Web
+ Server</literal> is a good example. Bad examples are <literal>high-performance light-weight
+ HTTP server</literal> (too generic) or <literal>Apache2</literal> (too specific and
+ meaningless for people who do not know Apache). <command>systemd</command> will use this
+ string as a noun in status messages (<literal>Starting
+ <replaceable>description</replaceable>...</literal>, <literal>Started
+ <replaceable>description</replaceable>.</literal>, <literal>Reached target
+ <replaceable>description</replaceable>.</literal>, <literal>Failed to start
+ <replaceable>description</replaceable>.</literal>), so it should be capitalized, and should
+ not be a full sentence or a phrase with a continous verb. Bad examples include
+ <literal>exiting the container</literal> or <literal>updating the database once per
+ day.</literal>.</para>
+ </listitem>
</varlistentry>
<varlistentry>
<para>If a unit A that conflicts with a unit B is scheduled to
be started at the same time as B, the transaction will either
- fail (in case both are required part of the transaction) or be
+ fail (in case both are required parts of the transaction) or be
modified to be fixed (in case one or both jobs are not a
required part of the transaction). In the latter case, the job
- that is not the required will be removed, or in case both are
+ that is not required will be removed, or in case both are
not required, the unit that conflicts will be started and the
unit that is conflicted is stopped.</para></listitem>
</varlistentry>
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. <option>exit</option> causes the manager to exit following the normal shutdown procedure, and
- <option>exit-force</option> causes it terminate without shutting down services.</para></listitem>
+ might result in data loss (i.e. equivalent to <command>systemctl reboot -ff</command>). Similarly,
+ <option>poweroff</option>, <option>poweroff-force</option>, <option>poweroff-immediate</option> have the effect
+ of powering down the system with similar semantics. <option>exit</option> causes the manager to exit following
+ the normal shutdown procedure, and <option>exit-force</option> causes it terminate without shutting down
+ services. When <option>exit</option> or <option>exit-force</option> is used by default the exit status of the
+ main process of the unit (if this applies) is returned from the service manager. However, this may be overriden
+ with <varname>FailureActionExitStatus=</varname>/<varname>SuccessActionExitStatus=</varname>, see
+ below.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>FailureActionExitStatus=</varname></term>
+ <term><varname>SuccessActionExitStatus=</varname></term>
+
+ <listitem><para>Controls the exit status to propagate back to an invoking container manager (in case of a
+ system service) or service manager (in case of a user manager) when the
+ <varname>FailureAction=</varname>/<varname>SuccessAction=</varname> are set to <option>exit</option> or
+ <option>exit-force</option> and the action is triggered. By default the exit status of the main process of the
+ triggering unit (if this applies) is propagated. Takes a value in the range 0…255 or the empty string to
+ request default behaviour.</para></listitem>
</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 <varname>JobTimeoutSec=</varname> may be
+ <listitem><para>When a job for this unit is queued, a timeout <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
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>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>JobTimeoutAction=</varname></term>
+ <term><varname>JobTimeoutRebootArgument=</varname></term>
- <para><varname>JobTimeoutAction=</varname> optionally configures an additional action to take when the time-out
- is hit. It takes the same values as <varname>StartLimitAction=</varname>. Defaults to <option>none</option>.
+ <listitem><para><varname>JobTimeoutAction=</varname> optionally configures an additional action to take when
+ the timeout is hit, see description of <varname>JobTimeoutSec=</varname> and
+ <varname>JobRunningTimeoutSec=</varname> above. It takes the same values as
+ <varname>StartLimitAction=</varname>. Defaults to <option>none</option>.
<varname>JobTimeoutRebootArgument=</varname> configures an optional reboot string to pass to the
- <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- system call.</para></listitem>
+ <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call.
+ </para></listitem>
</varlistentry>
<varlistentry>
<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>
+ respected. A failing condition will not result in the unit being moved into the <literal>failed</literal>
+ 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 their functionality. Use the various
+ <varname>AssertArchitecture=</varname>, <varname>AssertVirtualization=</varname>, … options for a similar
+ mechanism that causes the job to fail (instead of being skipped) and results in logging about the failed check
+ (instead of being silently processed). For details about assertion conditions see below.</para>
<para><varname>ConditionArchitecture=</varname> may be used to
check whether the system is running on a specific
cgroup controller name (eg. <option>cpu</option>), verifying that it is
available for use on the system. For example, a particular controller
may not be available if it was disabled on the kernel command line with
- <literal>cgroup_disable=</literal><replaceable>controller</replaceable>.
- Multiple controllers may be passed with a space separating them; in
- this case the condition will only pass if all listed controllers are
- available for use. Controllers unknown to systemd are ignored. Valid
- controllers are <option>cpu</option>, <option>cpuacct</option>,
- <option>io</option>, <option>blkio</option>, <option>memory</option>,
+ <varname>cgroup_disable=controller</varname>. Multiple controllers may
+ be passed with a space separating them; in this case the condition will
+ only pass if all listed controllers are available for use. Controllers
+ unknown to systemd are ignored. Valid controllers are
+ <option>cpu</option>, <option>cpuacct</option>, <option>io</option>,
+ <option>blkio</option>, <option>memory</option>,
<option>devices</option>, and <option>pids</option>.</para>
<para>If multiple conditions are specified, the unit will be
<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>
+ that is not met results in failure of the start job (which means this is logged loudly). Note that hitting a
+ configured assertion does not cause the unit to enter the <literal>failed</literal> state (or in fact result in
+ any state change of the unit), it affects only the job queued for it. 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>
+
+ <para>Note that neither assertion nor condition expressions result in unit state changes. Also note that both
+ are checked at the time the job is to be executed, i.e. long after depending jobs and it itself were
+ queued. Thus, neither condition nor assertion expressions are suitable for conditionalizing unit
+ dependencies.</para></listitem>
</varlistentry>
<varlistentry>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
projects / thirdparty / systemd.git / blobdiff