man: extend man pages a little

3 files changed, 84 insertions, 9 deletions

diff --git a/fixme b/fixme
index ef2b3f987a..30cfaac34a 100644
--- a/fixme
+++ b/fixme
@@ -49,8 +49,6 @@
 
 * maintenance units müssen vergessen werden
 
-* maintenance muss dokumentiert werden, ebenso OnStartup= und JobTimeoutSec=
-
 * fingerprint.target, wireless.target, gps.target
 
 * fix merging of device units
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index a03df65dcb..7284524dbb 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -399,6 +399,15 @@
                         </varlistentry>
 
                         <varlistentry>
+                                <term><varname>OnFailure=</varname></term>
+
+                                <listitem><para>Lists one or more
+                                units that are activated when this
+                                unit fails (i.e. enters maintenance
+                                state).</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
                                 <term><varname>RecursiveStop=</varname></term>
 
                                 <listitem><para>Takes a boolean
@@ -495,6 +504,34 @@
                                 fails the unit will immediately fail
                                 too and the job is removed.</para></listitem>
                         </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>JobTimeoutSec=</varname></term>
+
+                                <listitem><para>When clients are
+                                waiting for a job of this unit to
+                                complete, time out after the specified
+                                time. If this time limit is reached
+                                the job will be cancelled, the unit
+                                however will not change state or even
+                                enter maintenance 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>Timeout=</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>
+                        </varlistentry>
+
                 </variablelist>
 
                 <para>Unit file may include a [Install] section, which
diff --git a/man/systemd.xml b/man/systemd.xml
index e74d71b126..25f24ce722 100644
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -141,7 +141,7 @@
                                 <listitem><para>Tell systemd to run a
                                 system instance (resp. session
                                 instance), even if the process ID is
-                                not 1 (resp. is 1), i.e. system is not
+                                not 1 (resp. is 1), i.e. systemd is not
                                 (resp. is) run as init process.
                                 Normally it should not be necessary to
                                 pass these options, as systemd
@@ -232,12 +232,23 @@
                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                 however some are created automatically from other
                 configuration or dynamically from system state. Units
-                may be active (meaning started, bound, plugged in, ...
-                depending on the unit type), or inactive (meaning
-                stopped, unbound, unplugged, ...), as well as in the
-                process of being activated or deactivated,
-                i.e. between the two states. The following unit types
-                are available:</para>
+                may be 'active' (meaning started, bound, plugged in,
+                ...  depending on the unit type, see below), or
+                'inactive' (meaning stopped, unbound, unplugged, ...),
+                as well as in the process of being activated or
+                deactivated, i.e. between the two states (these states
+                are called 'activating', 'deactivating'). A special
+                'maintenance' state is available as well which is very
+                similar to 'inactive' and is entered when the service
+                failed in some way (process returned error code on
+                exit, or crashed, or an operation timed out). If this
+                state is entered the cause will be logged, for later
+                reference. Note that the various unit types may have a
+                number of additional substates, which are mapped to
+                the five generalized unit states described
+                here.</para>
+
+                <para>The following unit types are available:</para>
 
                 <orderedlist>
                         <listitem><para>Service units, which control
@@ -304,6 +315,35 @@
                 list you may find in
                 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 
+                <para>systemd knows various kinds of dependencies,
+                including positive and negative requirement
+                dependencies (i.e. <varname>Requires=</varname> and
+                <varname>Conflicts=</varname>) as well as ordering
+                dependencies (<varname>After=</varname> and
+                <varname>Before=</varname>). NB: ordering and
+                requirement dependencies are orthogonal. If only a
+                requirement dependency exists between two units
+                (e.g. <filename>foo.service</filename> requires
+                <filename>bar.service</filename>), but no ordering
+                dependency (e.g. <filename>foo.service</filename>
+                after <filename>bar.service</filename>) and both are
+                requested to start, they will be started in
+                parallel. It is a common pattern that both requirement
+                and ordering dependencies are placed between two
+                units. Also note that the majority of dependencies are
+                implicitly created and maintained by systemd. In most
+                cases it should be unnecessary to declare additional
+                dependencies manually, however it is possible to do
+                this.</para>
+
+                <para>Application programs and units (via
+                dependencies) may requests state changes of units. In
+                systemd, these requests are encapsulated as 'jobs' and
+                maintained in a job queue. Jobs may succeed or can
+                fail, their execution is ordered based on the ordering
+                dependencies of the units they have been scheduled
+                for.</para>
+
                 <para>On boot systemd activates the target unit
                 <filename>default.target</filename> whose job is to
                 activate on-boot services and other on-boot units by