<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>
<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>
projects / thirdparty / systemd.git / blobdiff