units: introduce new Documentation= field and make use of it everywhere

[elogind.git] / man / systemd.unit.xml

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index a94476acb89e788ba07c1e2eac75942f69b6afee..dbc5fedea9a30fb514b94a269cffe86bd67f1bd9 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -8,16 +8,16 @@
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it

-  under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or

   (at your option) any later version.
 
   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   (at your option) any later version.
 
   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

-  General Public License for more details.
+  Lesser General Public License for more details.

 
 

-  You should have received a copy of the GNU General Public License
+  You should have received a copy of the GNU Lesser General Public License

   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 


@@ -121,8 +121,9 @@
 
                 <para>If a line starts with <option>.include</option>
                 followed by a file name, the specified file will be
 
                 <para>If a line starts with <option>.include</option>
                 followed by a file name, the specified file will be

-                read as if its contents were listed in place of the
-                <option>.include</option> directive.</para>
+                parsed at this point. Make sure that the file that is
+                included has the appropriate section headers before
+                any directives.</para>

 
                 <para>Along with a unit file
                 <filename>foo.service</filename> a directory
 
                 <para>Along with a unit file
                 <filename>foo.service</filename> a directory


@@ -293,6 +294,23 @@
                                 name.</para></listitem>
                         </varlistentry>
 
                                 name.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>Documentation=</varname></term>
+                                <listitem><para>A space separated list
+                                of URIs referencing documentation for
+                                this unit or its
+                                configuration. Accepted are only URIs
+                                of the types
+                                <literal>http://</literal>,
+                                <literal>https://</literal>,
+                                <literal>file:</literal>,
+                                <literal>info:</literal>,
+                                <literal>man:</literal>. For more
+                                information about the syntax of these
+                                URIs see
+                                <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><varname>Requires=</varname></term>
 
                         <varlistentry>
                                 <term><varname>Requires=</varname></term>
 


@@ -508,6 +526,34 @@
                                 state.</para></listitem>
                         </varlistentry>
 
                                 state.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>PropagateReloadTo=</varname></term>
+                                <term><varname>PropagateReloadFrom=</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>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>RequiresMountsFor=</varname></term>
+
+                                <listitem><para>Takes a space
+                                separated list of paths. Automatically
+                                adds dependencies of type
+                                <varname>Requires=</varname> and
+                                <varname>After=</varname> for all
+                                mount units required to access the
+                                specified path.</para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><varname>OnFailureIsolate=</varname></term>
 
                         <varlistentry>
                                 <term><varname>OnFailureIsolate=</varname></term>
 


@@ -665,11 +711,15 @@
                                 <term><varname>ConditionPathExists=</varname></term>
                                 <term><varname>ConditionPathExistsGlob=</varname></term>
                                 <term><varname>ConditionPathIsDirectory=</varname></term>
                                 <term><varname>ConditionPathExists=</varname></term>
                                 <term><varname>ConditionPathExistsGlob=</varname></term>
                                 <term><varname>ConditionPathIsDirectory=</varname></term>

+                                <term><varname>ConditionPathIsSymbolicLink=</varname></term>
+                                <term><varname>ConditionPathIsMountPoint=</varname></term>
+                                <term><varname>ConditionPathIsReadWrite=</varname></term>

                                 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
                                 <term><varname>ConditionFileIsExecutable=</varname></term>
                                 <term><varname>ConditionKernelCommandLine=</varname></term>
                                 <term><varname>ConditionVirtualization=</varname></term>
                                 <term><varname>ConditionSecurity=</varname></term>
                                 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
                                 <term><varname>ConditionFileIsExecutable=</varname></term>
                                 <term><varname>ConditionKernelCommandLine=</varname></term>
                                 <term><varname>ConditionVirtualization=</varname></term>
                                 <term><varname>ConditionSecurity=</varname></term>

+                                <term><varname>ConditionCapability=</varname></term>

                                 <term><varname>ConditionNull=</varname></term>
 
                                 <listitem><para>Before starting a unit
                                 <term><varname>ConditionNull=</varname></term>
 
                                 <listitem><para>Before starting a unit


@@ -690,21 +740,39 @@
                                 is prefixed with an exclamation mark
                                 (!), the test is negated, and the unit
                                 is only started if the path does not
                                 is prefixed with an exclamation mark
                                 (!), the test is negated, and the unit
                                 is only started if the path does not

-                                exist. The test follows symlinks.
+                                exist.

                                 <varname>ConditionPathExistsGlob=</varname>
                                 works in a similar way, but checks for
                                 the existence of at least one file or
                                 directory matching the specified
                                 <varname>ConditionPathExistsGlob=</varname>
                                 works in a similar way, but checks for
                                 the existence of at least one file or
                                 directory matching the specified

-                                globbing pattern.
-                                <varname>ConditionPathIsDirectory=</varname>
-                                is similar to <varname>ConditionPathExists=</varname>
-                                but verifies whether a certain path exists and
-                                is a directory. It does not follow symlinks.
-                                <varname>ConditionFileIsExecutable=</varname>
-                                is similar to <varname>ConditionPathExists=</varname>
-                                but verifies whether a certain path exists,
-                                is a regular file and marked executable.
-                                It follows symlinks.
+                                globbing
+                                pattern. <varname>ConditionPathIsDirectory=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists and is a
+                                directory. <varname>ConditionPathIsSymbolicLink=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists and is a symbolic
+                                link. <varname>ConditionPathIsMountPoint=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists and is a mount
+                                point. <varname>ConditionPathIsReadWrite=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether the underlying
+                                file system is read and writable
+                                (i.e. not mounted
+                                read-only). <varname>ConditionFileIsExecutable=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists, is a regular file and marked
+                                executable.

                                 <varname>ConditionDirectoryNotEmpty=</varname>
                                 is similar to
                                 <varname>ConditionPathExists=</varname>
                                 <varname>ConditionDirectoryNotEmpty=</varname>
                                 is similar to
                                 <varname>ConditionPathExists=</varname>


@@ -732,16 +800,27 @@
                                 whether it is a specific
                                 implementation. Takes either boolean
                                 value to check if being executed in
                                 whether it is a specific
                                 implementation. Takes either boolean
                                 value to check if being executed in

-                                any virtual environment or one of the
+                                any virtualized environment, or one of
+                                <varname>vm</varname> and
+                                <varname>container</varname> to test
+                                against a specific type of
+                                virtualization solution, or one of

                                 <varname>qemu</varname>,
                                 <varname>kvm</varname>,
                                 <varname>vmware</varname>,
                                 <varname>microsoft</varname>,
                                 <varname>oracle</varname>,
                                 <varname>xen</varname>,
                                 <varname>qemu</varname>,
                                 <varname>kvm</varname>,
                                 <varname>vmware</varname>,
                                 <varname>microsoft</varname>,
                                 <varname>oracle</varname>,
                                 <varname>xen</varname>,

-                                <varname>pidns</varname>,
-                                <varname>openvz</varname> to test
-                                against a specific implementation. The
+                                <varname>bochs</varname>,
+                                <varname>chroot</varname>,
+                                <varname>openvz</varname>,
+                                <varname>lxc</varname>,
+                                <varname>lxc-libvirt</varname>,
+                                <varname>systemd-nspawn</varname> to
+                                test against a specific
+                                implementation. If multiple
+                                virtualization technologies are nested
+                                only the innermost is considered. The

                                 test may be negated by prepending an
                                 exclamation mark.
                                 <varname>ConditionSecurity=</varname>
                                 test may be negated by prepending an
                                 exclamation mark.
                                 <varname>ConditionSecurity=</varname>


@@ -750,7 +829,19 @@
                                 system.  Currently the only recognized
                                 value is <varname>selinux</varname>.
                                 The test may be negated by prepending
                                 system.  Currently the only recognized
                                 value is <varname>selinux</varname>.
                                 The test may be negated by prepending

-                                an exclamation mark. Finally,
+                                an exclamation
+                                mark. <varname>ConditionCapability=</varname>
+                                may be used to check whether the given
+                                capability exists in the capability
+                                bounding set of the service manager
+                                (i.e. this does not check whether
+                                capability is actually available in
+                                the permitted or effective sets, see
+                                <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                for details). Pass a capability name
+                                such as <literal>CAP_MKNOD</literal>,
+                                possibly prefixed with an exclamation
+                                mark to negate the check. Finally,

                                 <varname>ConditionNull=</varname> may
                                 be used to add a constant condition
                                 check value to the unit. It takes a
                                 <varname>ConditionNull=</varname> may
                                 be used to add a constant condition
                                 check value to the unit. It takes a


@@ -772,7 +863,10 @@
                                 prefix an argument with the pipe
                                 symbol and an exclamation mark the
                                 pipe symbol must be passed first, the
                                 prefix an argument with the pipe
                                 symbol and an exclamation mark the
                                 pipe symbol must be passed first, the

-                                exclamation second.</para></listitem>
+                                exclamation second. Except for
+                                <varname>ConditionPathIsSymbolicLink=</varname>,
+                                all path checks follow
+                                symlinks.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -904,7 +998,8 @@
                         <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

-                        <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>

                 </para>
         </refsect1>
 
                 </para>
         </refsect1>