From 06c5b7a9f3d47834ea4dbbfb24f169b6893dd338 Mon Sep 17 00:00:00 2001

From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>

Date: Sat, 30 Nov 2013 21:23:01 -0500

Subject: [PATCH] man: explicitly say when multiple units can be specified

itistoday> how do you specify multiple dependencies in a unit file? i've been

           googling and can't find this basic thing :-\

itistoday> do you use a comma, or use multiple After= statements?

---

 man/systemd.unit.xml | 128 ++++++++++++++++++++++++++++-----------------------

 1 file changed, 70 insertions(+), 58 deletions(-)

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml

index 5c8b8e8..029392c 100644

--- a/man/systemd.unit.xml

+++ b/man/systemd.unit.xml

@@ -410,10 +410,12 @@

                                 of the other units gets deactivated or

                                 its activation fails, this unit will

                                 be deactivated. This option may be

-                                specified more than once, in which

-                                case requirement dependencies for all

-                                listed names are created. Note that

-                                requirement dependencies do not

+                                specified more than once or multiple

+                                space-separated units may be specified

+                                in one option in which case

+                                requirement dependencies for all

+                                listed names will be created. Note

+                                that requirement dependencies do not

                                 influence the order in which services

                                 are started or stopped. This has to be

                                 configured independently with the

@@ -476,22 +478,23 @@

                                 <term><varname>RequisiteOverridable=</varname></term>

                                 <listitem><para>Similar to

-                                <varname>Requires=</varname>

-                                and <varname>RequiresOverridable=</varname>, respectively. However,

-                                if a unit listed here is not started

-                                already it will not be started and the

-                                transaction fails

-                                immediately.</para></listitem>

+                                <varname>Requires=</varname> and

+                                <varname>RequiresOverridable=</varname>,

+                                respectively. However, if the units

+                                listed here are not started already

+                                they will not be started and the

+                                transaction will fail immediately.

+                                </para></listitem>

                         </varlistentry>

                         <varlistentry>

                                 <term><varname>Wants=</varname></term>

                                 <listitem><para>A weaker version of

-                                <varname>Requires=</varname>. A unit

+                                <varname>Requires=</varname>. Units

                                 listed in this option will be started

                                 if the configuring unit is. However,

-                                if the listed unit fails to start up

+                                if the listed units fail to start

                                 or cannot be added to the transaction

                                 this has no impact on the validity of

                                 the transaction as a whole. This is

@@ -501,8 +504,8 @@

                                 <para>Note that dependencies of this

                                 type may also be configured outside of

-                                the unit configuration file by

-                                adding a symlink to a

+                                the unit configuration file by adding

+                                symlinks to a

                                 <filename>.wants/</filename> directory

                                 accompanying the unit file. For

                                 details see above.</para></listitem>

@@ -534,7 +537,7 @@

                                 of units. When systemd stops or restarts

                                 the units listed here, the action is

                                 propagated to this unit.

-                                Note that this is a one way dependency -

+                                Note that this is a one way dependency —

                                 changes to this unit do not affect the

                                 listed units.

                                 </para></listitem>

@@ -543,12 +546,12 @@

                         <varlistentry>

                                 <term><varname>Conflicts=</varname></term>

-                                <listitem><para>Configures negative

+                                <listitem><para>A space-separated list

+                                of unit names. Configures negative

                                 requirement dependencies. If a unit

-                                has a

-                                <varname>Conflicts=</varname> setting

-                                on another unit, starting the former

-                                will stop the latter and vice

+                                has a <varname>Conflicts=</varname>

+                                setting on another unit, starting the

+                                former will stop the latter and vice

                                 versa. Note that this setting is

                                 independent of and orthogonal to the

                                 <varname>After=</varname> and

@@ -575,7 +578,8 @@

                                 <term><varname>Before=</varname></term>

                                 <term><varname>After=</varname></term>

-                                <listitem><para>Configures ordering

+                                <listitem><para>A space-separated list

+                                of unit names. Configures ordering

                                 dependencies between units. If a unit

                                 <filename>foo.service</filename>

                                 contains a setting

@@ -624,18 +628,18 @@

                                 type <varname>After=</varname> or

                                 <varname>Before=</varname>. If two

                                 units have no ordering dependencies

-                                between them, they are shut down

-                                or started up simultaneously, and

-                                no ordering takes

+                                between them, they are shut down or

+                                started up simultaneously, and no

+                                ordering takes

                                 place. </para></listitem>

                         </varlistentry>

                         <varlistentry>

                                 <term><varname>OnFailure=</varname></term>

-                                <listitem><para>Lists one or more

-                                units that are activated when this

-                                unit enters the

+                                <listitem><para>A space-separated list

+                                of one or more units that are

+                                activated when this unit enters the

                                 <literal>failed</literal>

                                 state.</para></listitem>

                         </varlistentry>

@@ -644,16 +648,17 @@

                                 <term><varname>PropagatesReloadTo=</varname></term>

                                 <term><varname>ReloadPropagatedFrom=</varname></term>

-                                <listitem><para>Lists one or more

-                                units where reload requests on the

-                                unit will be propagated to/on the

-                                other unit will be propagated

-                                from. Issuing a reload request on a

-                                unit will automatically also enqueue a

-                                reload request on all units that the

-                                reload request shall be propagated to

-                                via these two

-                                settings.</para></listitem>

+                                <listitem><para>A space-separated list

+                                of one or more units where reload

+                                requests on this unit will be

+                                propagated to, or reload requests on

+                                the other unit will be propagated to

+                                this unit, respectively. Issuing a

+                                reload request on a unit will

+                                automatically also enqueue a reload

+                                request on all units that the reload

+                                request shall be propagated to via

+                                these two settings.</para></listitem>

                         </varlistentry>

                         <varlistentry>

@@ -1089,32 +1094,34 @@

                         <varlistentry>

                                 <term><varname>Alias=</varname></term>

-                                <listitem><para>Additional names this

-                                unit shall be installed under. The

-                                names listed here must have the same

-                                suffix (i.e. type) as the unit file

-                                name. This option may be specified

-                                more than once, in which case all

-                                listed names are used. At installation

-                                time,

-                                <command>systemctl enable</command>

-                                will create symlinks from these names

-                                to the unit filename.</para></listitem>

+                                <listitem><para>A space-seperated list

+                                of additional names this unit shall be

+                                installed under. The names listed here

+                                must have the same suffix (i.e. type)

+                                as the unit file name. This option may

+                                be specified more than once, in which

+                                case all listed names are used. At

+                                installation time, <command>systemctl

+                                enable</command> will create symlinks

+                                from these names to the unit

+                                filename.</para></listitem>

                         </varlistentry>

                         <varlistentry>

                                 <term><varname>WantedBy=</varname></term>

                                 <term><varname>RequiredBy=</varname></term>

-                                <listitem><para>A symbolic link is

-                                created in the

-                                <filename>.wants/</filename> or

-                                <filename>.requires/</filename> directory

-                                of the listed unit when this unit is

-                                activated by <command>systemctl

-                                enable</command>.  This has the effect

-                                that a dependency of type

-                                <varname>Wants=</varname> or

+                                <listitem><para>This option may be

+                                used more than once, or a

+                                space-separated list of unit names may

+                                be given. A symbolic link is created

+                                in the <filename>.wants/</filename> or

+                                <filename>.requires/</filename>

+                                directory of each of the listed units

+                                when this unit is installed by

+                                <command>systemctl enable</command>.

+                                This has the effect that a dependency

+                                of type <varname>Wants=</varname> or

                                 <varname>Requires=</varname> is added

                                 from the listed unit to the current

                                 unit. The primary result is that the

@@ -1160,7 +1167,12 @@

                                 and <command>systemctl

                                 disable</command> will automatically

                                 install/uninstall units listed in this option as

-                                well.</para></listitem>

+                                well.</para>

+

+                                <para>This option may be used more

+                                than once, or a space-separated list

+                                of unit names may be

+                                given.</para></listitem>

                         </varlistentry>

                 </variablelist>