man: finish systemd.unit.5

1 files changed, 347 insertions, 29 deletions

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 7e657c64f7..99bd8b3906 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -48,15 +48,15 @@
         </refnamediv>
 
         <refsynopsisdiv>
-                <para><filename>systemd.service</filename></para>
-                <para><filename>systemd.socket</filename></para>
-                <para><filename>systemd.device</filename></para>
-                <para><filename>systemd.mount</filename></para>
-                <para><filename>systemd.automount</filename></para>
-                <para><filename>systemd.swap</filename></para>
-                <para><filename>systemd.target</filename></para>
-                <para><filename>systemd.path</filename></para>
-                <para><filename>systemd.timer</filename></para>
+                <para><filename>systemd.service</filename>,
+                <filename>systemd.socket</filename>,
+                <filename>systemd.device</filename>,
+                <filename>systemd.mount</filename>,
+                <filename>systemd.automount</filename>,
+                <filename>systemd.swap</filename>,
+                <filename>systemd.target</filename>,
+                <filename>systemd.path</filename>,
+                <filename>systemd.timer</filename></para>
         </refsynopsisdiv>
 
         <refsect1>
@@ -66,15 +66,74 @@
                 about a service, a socket, a device, a mount point, an
                 automount point, a swap file or partition, a start-up
                 target, a file system path or a timer controlled and
-                supervised by <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The syntax is inspired by XDG
-                <filename>.desktop</filename> files, which are in turn
-                inspired by Microsoft Windows <filename>.ini</filename>
-                files.</para>
+                supervised by
+                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The
+                syntax is inspired by <ulink
+                url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
+                Desktop Entry Specificiation</ulink> <filename>.desktop</filename> files, which are in turn
+                inspired by Microsoft Windows
+                <filename>.ini</filename> files.</para>
 
                 <para>This man pages lists the common configuration
                 options of the all unit types. These options need to
-                be configured either in the [Unit] resp. [Install]
+                be configured in the [Unit] resp. [Install]
                 section of the unit files.</para>
+
+                <para>In addition to the generic [Unit] and [Install]
+                sections described here each unit should have a
+                type-specific section, e.g. [Service] for a service
+                unit. See the respective man pages for more
+                information.</para>
+
+                <para>Unit files may contain additional options on top
+                of those listed here. If systemd encounters an unknown
+                option it will write a warning log message but
+                continue loading the unit. If an option is prefixed
+                with <option>X-</option> it is ignored completely by
+                systemd. Applications may use this to include
+                additional information in the unit files.</para>
+
+                <para>Boolean arguments used in unit files can be
+                written in various forms. For positive settings the
+                strings <option>1</option>, <option>yes</option>,
+                <option>true</option> and <option>on</option> are
+                equivalent. For negative settings the strings
+                <option>0</option>, <option>no</option>,
+                <option>false</option> and <option>off</option> are
+                equivalent.</para>
+
+                <para>Empty lines and lines starting with # or ; are
+                ignored. This may be used for commenting.</para>
+
+                <para>If a line starts with <option>.include</option>
+                followed by a file name the specified file will be
+                read as if its contents where listed in place of the
+                <option>.include</option> directive.</para>
+
+                <para>Along with a unit file
+                <filename>foo.service</filename> a directory
+                <filename>foo.service.wants/</filename> may exist. All
+                units symlinked from such a directory are implicitly
+                added as dependencies of type
+                <varname>Wanted=</varname> to the unit. This is useful
+                to hook units into the start-up of other units,
+                without having to modify their unit configuration
+                files. For details about the semantics of
+                <varname>Wanted=</varname> see below. The preferred
+                way to create symlinks in the
+                <filename>.wants/</filename> directory of a service is
+                with the
+                <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                tool which reads information from the [Install]
+                section of unit files. (See below.)</para>
+
+                <para>Note that while systemd offers a flexible
+                dependency system between units it is recommended to
+                use this functionality only sparsely and instead rely
+                on techniques such as bus-based or socket-based
+                activation which makes dependencies implicit, which
+                both results in a simpler and more flexible
+                system.</para>
         </refsect1>
 
         <refsect1>
@@ -97,13 +156,23 @@
                                 that this option is different from the
                                 <varname>Alias=</varname> option from
                                 the [Install] section mentioned
-                                below. See below for details</para>
+                                below. See below for details.</para>
                                 </listitem>
                         </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>Description=</varname></term>
+                                <listitem><para>A free-form string
+                                describing the unit. This is intended for use
+                                in UIs wanting to show
+                                descriptive information along with the
+                                unit name.</para></listitem>
+                        </varlistentry>
+
                         <varlistentry>
                                 <term><varname>Requires=</varname></term>
 
-                                <listitem><para>Requirement
+                                <listitem><para>Configures requirement
                                 dependencies on other units. If this
                                 units get activated the units listed
                                 here will be activated as well. If one
@@ -112,9 +181,224 @@
                                 be deactivated. This option may be
                                 specified more than once, in which
                                 case requirement dependencies for all
-                                listed names are created.</para>
-                                </listitem>
+                                listed names are 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
+                                <varname>After=</varname> or
+                                <varname>Before=</varname> options. If
+                                a unit
+                                <filename>foo.service</filename>
+                                requires a unit
+                                <filename>bar.service</filename> as
+                                configured with
+                                <varname>Requires=</varname> and no
+                                ordering is configured with
+                                <varname>After=</varname> or
+                                <varname>Before=</varname>, then both
+                                units will be started simultaneously
+                                and without any delay between them if
+                                <filename>foo.service</filename> is
+                                activated. Often it is a better choice
+                                to use <varname>Wants=</varname>
+                                instead of
+                                <varname>Requires=</varname> in order
+                                to achieve a system that is more
+                                robust when dealing with failing
+                                services.</para></listitem>
                         </varlistentry>
+
+
+                        <varlistentry>
+                                <term><varname>RequiresOverridable=</varname></term>
+
+                                <listitem><para>Similar to
+                                <varname>Requires=</varname>.
+                                Dependencies listed in
+                                <varname>RequiresOverridable=</varname>
+                                which cannot be fulfilled or fail to
+                                start are ignored iff the startup was
+                                explicitly requested by the user. If
+                                the start-up was pulled in indirectly
+                                by some dependency or automatic
+                                start-up of units that is not
+                                requested by the user this dependency
+                                must be fulfilled and otherwise the
+                                transaction fails. Hence, this option
+                                may be used to configure dependencies
+                                that are normally honoured unless the
+                                user explicitly starts up the unit, in
+                                which case whether they failed or not
+                                is irrelevant.</para></listitem>
+
+                        </varlistentry>
+                        <varlistentry>
+                                <term><varname>Requisite=</varname></term>
+                                <term><varname>RequisiteOverridable=</varname></term>
+
+                                <listitem><para>Similar to
+                                <varname>Requires=</varname>
+                                resp. <varname>RequiresOverridable=</varname>. However,
+                                if a unit listed here is not started
+                                already it will not be started and the
+                                transaction fails
+                                immediately.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>Wants=</varname></term>
+
+                                <listitem><para>A weaker version of
+                                <varname>Requires=</varname>. A unit
+                                listed in this option will be started
+                                if the configuring unit is. However,
+                                it the listed unit fails to start up
+                                or cannot be added to the transaction
+                                this has no impact on the validity of
+                                the transaction as a whole. This is
+                                the recommended way to hook start-up
+                                of one unit to the start-up of another
+                                unit. Note that dependencies of this
+                                type may also be configured outside of
+                                the unit configuration file by
+                                adding a symlink to a
+                                <filename>.wants/</filename> directory
+                                accompanying the unit file. For
+                                details see above.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>Conflicts=</varname></term>
+
+                                <listitem><para>Configures negative
+                                requirement dependencies. If a unit
+                                that 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
+                                <varname>Before=</varname> ordering
+                                dependencies.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>Before=</varname></term>
+                                <term><varname>After=</varname></term>
+
+                                <listitem><para>Configures ordering
+                                dependencies between units. If a unit
+                                <filename>foo.service</filename>
+                                contains a setting
+                                <option>Before=bar.service</option>
+                                and both units are being started
+                                <filename>bar.service</filename>'s
+                                start-up is delayed until
+                                <filename>foo.service</filename> is
+                                started up. Note that this setting is
+                                independent of and orthogonal to the
+                                requirement dependencies as configured
+                                by <varname>Requires=</varname>. It is
+                                a common pattern to include a unit
+                                name in both the
+                                <varname>After=</varname> and
+                                <varname>Requires=</varname> option in
+                                which case the unit listed will be
+                                started before the unit that is
+                                configured with these options. This
+                                option may be specified more than
+                                once, in which case ordering
+                                dependencies for all listed names are
+                                created. <varname>After=</varname> is
+                                the inverse of
+                                <varname>Before=</varname>, i.e. while
+                                <varname>After=</varname> ensures that
+                                the configured unit is started after
+                                the listed unit finished starting up,
+                                <varname>Before=</varname> ensures the
+                                opposite, i.e.  that the configured
+                                unit is fully started up before the
+                                listed unit is started. Note that when
+                                two units with an ordering dependency
+                                between them are shut down, the
+                                inverse of of the start-up order is
+                                applied. i.e. if a unit is configured
+                                with <varname>After=</varname> on
+                                another unit, the former is stopped
+                                before the latter if both are shut
+                                down. If one unit with an ordering
+                                dependency on another unit is shut
+                                down while the latter is started up,
+                                the shut down is ordered before the
+                                start-up regardless whether the
+                                ordering dependency is actually of
+                                type <varname>After=</varname> or
+                                <varname>Before=</varname>. If two
+                                units have no ordering dependencies
+                                between them they are shut down
+                                resp. started up simultaneously, and
+                                no ordering takes
+                                place. </para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>RecursiveStop=</varname></term>
+
+                                <listitem><para>Takes a boolean
+                                argument. If <option>true</option> and
+                                the unit stops without this being
+                                requested by the user all units
+                                depending on it will be stopped as
+                                well. (e.g. if a service exits or
+                                crashes on its own behalf, units using
+                                it will be stopped) Note that normally
+                                if a unit stops without user request
+                                units depending on it will not be
+                                terminated. Only if the user requested
+                                shutdown of a unit all units depending
+                                on the unit will be shut down as well
+                                and at the same time. Defaults to
+                                <option>false</option>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>StopWhenUnneeded=</varname></term>
+
+                                <listitem><para>Takes a boolean
+                                argument. If <option>true</option>
+                                this unit will be stopped when it is
+                                no longer used. Note that in order to
+                                minimize the work to be executed
+                                systemd will by default not stop units
+                                unless they are conflicting with other
+                                units, or the user explicitly
+                                requested their shut down. If this
+                                option is set a unit will be
+                                automatically cleaned up if no other
+                                active unit requires it. Defaults to
+                                <option>false</option>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>OnlyByDependency=</varname></term>
+
+                                <listitem><para>Takes a boolean
+                                argument. If <option>true</option>
+                                this unit may only be activated
+                                indirectly. In this case explicit
+                                start-up requested by the user is
+                                denied, however if it is started as
+                                dependency of another unit start-up
+                                will succeed. This is mostly a safety
+                                feature to ensure that the user does
+                                not accidently activate units that are
+                                not intended to be activated
+                                explicitly. This option defaults to
+                                <option>false</option>.</para></listitem>
+                        </varlistentry>
+
                 </variablelist>
 
                 <para>Unit file may include a [Install] section, which
@@ -123,7 +407,7 @@
                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                 during runtime. It is used exclusively by the
                 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-                during installation of a unit:</para>
+                tool during installation of a unit:</para>
 
                 <variablelist>
                         <varlistentry>
@@ -148,18 +432,52 @@
                                 unconditionally if the unit is
                                 loaded. The names from
                                 <varname>Alias=</varname> apply only
-                                if the unit is actually installed with
-                                the <command>systemd-install</command>
+                                if the unit has actually been
+                                installed with the
+                                <command>systemd-install</command>
                                 tool.  Also, if systemd searches for a
                                 unit, it will discover symlinked alias
-                                names, but not names configured only
-                                with <varname>Names=</varname>. It is
-                                a common pattern to list a name in both
-                                options. In this case, a unit will be
-                                active under all names if installed,
-                                but also if not installed but
-                                requested
-                                explicitly.</para></listitem>
+                                names as configured with
+                                <varname>Alias=</varname>, but not
+                                names configured with
+                                <varname>Names=</varname> only. It is
+                                a common pattern to list a name in
+                                both options. In this case, a unit
+                                will be active under all names if
+                                installed, but also if not installed
+                                but requested explicitly under its
+                                main name.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>WantedBy=</varname></term>
+
+                                <listitem><para>Installs a symlink in
+                                the <filename>.wants/</filename>
+                                subdirectory for a unit. This has the
+                                effect that when the listed unit name
+                                is activated the unit listing it is
+                                activated
+                                to. <command>WantedBy=foo.service</command>
+                                in a service
+                                <filename>bar.service</filename> is
+                                mostly equivalent to
+                                <command>Alias=foo.service.wants/bar.service</command>
+                                in the same file.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>Also=</varname></term>
+
+                                <listitem><para>Additional units to
+                                install when this unit is
+                                installed. If the user requests
+                                installation of a unit with this
+                                option configured
+                                <command>systemd-install</command>
+                                will automatically install units
+                                listed in this option as
+                                well.</para></listitem>
                         </varlistentry>
                 </variablelist>