1
1
mirror of https://github.com/systemd/systemd-stable.git synced 2024-12-23 17:34:00 +03:00

man: don't claim that AssertXYZ= expressions failing had an effect on unit state

In the documentation for ConditionXYZ= we claimed that AssertXYZ= would
have an effect on unit state (which is wrong), while at the
documentation for AssertXYZ= we said it only has an effect on the job,
but not the unit (which is right). Let's fix this contradiction, and
only claim the latter.

Also, fix a couple of other things (for example, stop talking about a
"failure state", but let's just expressly called it "the 'failed' state",
as that's the actual name of that state.

Finally, let's emphasize again when the conditions/assertions are
executed, and that they hence are not useful to conditionalize deps.

Fixes: #10433
This commit is contained in:
Lennart Poettering 2018-10-29 20:07:22 +01:00
parent 860cc6df6d
commit 53bd20ea06

View File

@ -990,12 +990,13 @@
<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
@ -1276,9 +1277,16 @@
<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>