man: extend man pages a little

diff --git a/fixme b/fixme
index ef2b3f987a19ba9b458b6f69914858bdf010880a..30cfaac34afc1eeda4447fbdf30e30080427002f 100644 (file)
--- a/fixme
+++ b/fixme
@@ -49,8 +49,6 @@
 
 * maintenance units müssen vergessen werden
 
 
 * 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
 * fingerprint.target, wireless.target, gps.target
 
 * fix merging of device units

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index a03df65dcb50b24432a3e4606ebec0b3f26fbf00..7284524dbbae65b58567efd4da29cf0b1a0de5b0 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -398,6 +398,15 @@
                                 place. </para></listitem>
                         </varlistentry>
 
                                 place. </para></listitem>
                         </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>
 
                         <varlistentry>
                                 <term><varname>RecursiveStop=</varname></term>
 


@@ -495,6 +504,34 @@
                                 fails the unit will immediately fail
                                 too and the job is removed.</para></listitem>
                         </varlistentry>
                                 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
                 </variablelist>
 
                 <para>Unit file may include a [Install] section, which

diff --git a/man/systemd.xml b/man/systemd.xml
index e74d71b126f096a2fd78c404f8e271841ec97da1..25f24ce7229f4c0f17143b25f0f12980b55cf3b2 100644 (file)
--- 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
                                 <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
                                 (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
                 <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
 
                 <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>
 
                 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
                 <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