doc: grammatical corrections

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

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 02445703617bbf962ed29d4e26e7510597ee8cda..032879a0afdea99327c7f9598dc9b6274e6a9b09 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -70,7 +70,8 @@
 <filename>...</filename>
                 </literallayout></para>
 
 <filename>...</filename>
                 </literallayout></para>
 

-                <para><literallayout><filename>$HOME/.config/systemd/user/*</filename>
+                <para><literallayout><filename>$XDG_CONFIG_HOME/systemd/user/*</filename>
+<filename>$HOME/.config/systemd/user/*</filename>

 <filename>/etc/systemd/user/*</filename>
 <filename>/run/systemd/user/*</filename>
 <filename>/usr/lib/systemd/user/*</filename>
 <filename>/etc/systemd/user/*</filename>
 <filename>/run/systemd/user/*</filename>
 <filename>/usr/lib/systemd/user/*</filename>


@@ -138,10 +139,12 @@
                 <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
                 <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>
+                continue loading the unit. If an option or section name
+                is prefixed with <option>X-</option>, it is ignored
+                completely by systemd. Options within an ignored
+                section do not need the prefix. 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 formats. For positive settings the
 
                 <para>Boolean arguments used in unit files can be
                 written in various formats. For positive settings the


@@ -200,12 +203,6 @@
                 has the appropriate section headers before any
                 directive.</para>
 
                 has the appropriate section headers before any
                 directive.</para>
 

-                <para>If a line starts with <option>.include</option>
-                followed by a filename, the specified file will be
-                parsed at this point. Make sure that the file that is
-                included has the appropriate section headers before
-                any directives.</para>
-

                 <para>Note that while systemd offers a flexible
                 dependency system between units it is recommended to
                 use this functionality only sparingly and instead rely
                 <para>Note that while systemd offers a flexible
                 dependency system between units it is recommended to
                 use this functionality only sparingly and instead rely


@@ -232,7 +229,7 @@
                 multiple units from a single configuration file. If
                 systemd looks for a unit configuration file, it will
                 first search for the literal unit name in the
                 multiple units from a single configuration file. If
                 systemd looks for a unit configuration file, it will
                 first search for the literal unit name in the

-                filesystem. If that yields no success and the unit
+                file system. If that yields no success and the unit

                 name contains an <literal>@</literal> character, systemd will look for a
                 unit template that shares the same name but with the
                 instance string (i.e. the part between the <literal>@</literal> character
                 name contains an <literal>@</literal> character, systemd will look for a
                 unit template that shares the same name but with the
                 instance string (i.e. the part between the <literal>@</literal> character


@@ -325,9 +322,13 @@
                       </row>
                     </thead>
                     <tbody>
                       </row>
                     </thead>
                     <tbody>

+                      <row>
+                        <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry>
+                        <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry>
+                      </row>

                       <row>
                         <entry><filename>$HOME/.config/systemd/user</filename></entry>
                       <row>
                         <entry><filename>$HOME/.config/systemd/user</filename></entry>

-                        <entry>User configuration</entry>
+                        <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry>

                       </row>
                       <row>
                         <entry><filename>/etc/systemd/user</filename></entry>
                       </row>
                       <row>
                         <entry><filename>/etc/systemd/user</filename></entry>


@@ -356,7 +357,7 @@
         </refsect1>
 
         <refsect1>
         </refsect1>
 
         <refsect1>

-                <title>Options</title>
+                <title>[Unit] Section Options</title>

 
                 <para>Unit file may include a [Unit] section, which
                 carries generic information about the unit that is not
 
                 <para>Unit file may include a [Unit] section, which
                 carries generic information about the unit that is not


@@ -548,7 +549,7 @@
                                 of units. When systemd stops or restarts
                                 the units listed here, the action is
                                 propagated to this unit.
                                 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>
                                 changes to this unit do not affect the
                                 listed units.
                                 </para></listitem>


@@ -706,13 +707,26 @@
                         <varlistentry>
                                 <term><varname>RequiresMountsFor=</varname></term>
 
                         <varlistentry>
                                 <term><varname>RequiresMountsFor=</varname></term>
 

-                                <listitem><para>Takes a space-separated
-                                list of absolute paths. Automatically
-                                adds dependencies of type
-                                <varname>Requires=</varname> and
-                                <varname>After=</varname> for all
+                                <listitem><para>Takes a
+                                space-separated list of absolute
+                                paths. Automatically adds dependencies
+                                of type <varname>Requires=</varname>
+                                and <varname>After=</varname> for all

                                 mount units required to access the
                                 mount units required to access the

-                                specified path.</para></listitem>
+                                specified path.</para>
+
+                                <para>Mount points marked with
+                                <option>noauto</option> are not
+                                mounted automatically and will be
+                                ignored for the purposes of this
+                                option. If such a mount should be a
+                                requirement for this unit,
+                                direct dependencies on the mount
+                                units may be added
+                                (<varname>Requires=</varname> and
+                                <varname>After=</varname> or
+                                some other combination).
+                                </para></listitem>

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


@@ -879,6 +893,13 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

+                                <term><varname>ConditionArchitecture=</varname></term>
+                                <term><varname>ConditionVirtualization=</varname></term>
+                                <term><varname>ConditionHost=</varname></term>
+                                <term><varname>ConditionKernelCommandLine=</varname></term>
+                                <term><varname>ConditionSecurity=</varname></term>
+                                <term><varname>ConditionCapability=</varname></term>
+                                <term><varname>ConditionACPower=</varname></term>

                                 <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>


@@ -888,12 +909,6 @@
                                 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
                                 <term><varname>ConditionFileNotEmpty=</varname></term>
                                 <term><varname>ConditionFileIsExecutable=</varname></term>
                                 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
                                 <term><varname>ConditionFileNotEmpty=</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>ConditionHost=</varname></term>
-                                <term><varname>ConditionACPower=</varname></term>

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


@@ -908,93 +923,46 @@
                                 queued start job is to be
                                 executed.</para>
 
                                 queued start job is to be
                                 executed.</para>
 

-                                <para>With
-                                <varname>ConditionPathExists=</varname>
-                                a file existence condition is
-                                checked before a unit is started. If
-                                the specified absolute path name does
-                                not exist, the condition will
-                                fail. If the absolute path name passed
-                                to
-                                <varname>ConditionPathExists=</varname>
-                                is prefixed with an exclamation mark
-                                (<literal>!</literal>), the test is negated, and the unit
-                                is only started if the path does not
-                                exist.</para>
-
-                                <para><varname>ConditionPathExistsGlob=</varname>
-                                is similar to
-                                <varname>ConditionPathExists=</varname>,
-                                but checks for the existence of at
-                                least one file or directory matching
-                                the specified globbing pattern.</para>
-
-                                <para><varname>ConditionPathIsDirectory=</varname>
-                                is similar to
-                                <varname>ConditionPathExists=</varname>
-                                but verifies whether a certain path
-                                exists and is a
-                                directory.</para>
-
-                                <para><varname>ConditionPathIsSymbolicLink=</varname>
-                                is similar to
-                                <varname>ConditionPathExists=</varname>
-                                but verifies whether a certain path
-                                exists and is a symbolic
-                                link.</para>
-
-                                <para><varname>ConditionPathIsMountPoint=</varname>
-                                is similar to
-                                <varname>ConditionPathExists=</varname>
-                                but verifies whether a certain path
-                                exists and is a mount
-                                point.</para>
-
-                                <para><varname>ConditionPathIsReadWrite=</varname>
-                                is similar to
-                                <varname>ConditionPathExists=</varname>
-                                but verifies whether the underlying
-                                file system is readable and writable
-                                (i.e. not mounted
-                                read-only).</para>
-
-                                <para><varname>ConditionDirectoryNotEmpty=</varname>
-                                is similar to
-                                <varname>ConditionPathExists=</varname>
-                                but verifies whether a certain path
-                                exists and is a non-empty
-                                directory.</para>
-
-                                <para><varname>ConditionFileNotEmpty=</varname>
-                                is similar to
-                                <varname>ConditionPathExists=</varname>
-                                but verifies whether a certain path
-                                exists and refers to a regular file
-                                with a non-zero size.</para>
-
-                                <para><varname>ConditionFileIsExecutable=</varname>
-                                is similar to
-                                <varname>ConditionPathExists=</varname>
-                                but verifies whether a certain path
-                                exists, is a regular file and marked
-                                executable.</para>
-
-                                <para>Similarly,
-                                <varname>ConditionKernelCommandLine=</varname>
-                                may be used to check whether a
-                                specific kernel command line option is
-                                set (or if prefixed with the
-                                exclamation mark unset). The argument
-                                must either be a single word, or an
-                                assignment (i.e. two words, separated
-                                <literal>=</literal>). In the former
-                                case the kernel command line is
-                                searched for the word appearing as is,
-                                or as left hand side of an
-                                assignment. In the latter case the
-                                exact assignment is looked for with
-                                right and left hand side
-                                matching.</para>
+                                <para><varname>ConditionArchitecture=</varname>
+                                may be used to check whether the
+                                system is running on a specific
+                                architecture. Takes one of
+                                <varname>x86</varname>,
+                                <varname>x86-64</varname>,
+                                <varname>ppc</varname>,
+                                <varname>ppc64</varname>,
+                                <varname>ia64</varname>,
+                                <varname>parisc</varname>,
+                                <varname>parisc64</varname>,
+                                <varname>s390</varname>,
+                                <varname>s390x</varname>,
+                                <varname>sparc</varname>,
+                                <varname>sparc64</varname>,
+                                <varname>mips</varname>,
+                                <varname>mips64</varname>,
+                                <varname>alpha</varname>,
+                                <varname>arm</varname>,
+                                <varname>arm-be</varname>,
+                                <varname>arm64</varname>,
+                                <varname>arm64-be</varname>,
+                                <varname>sh</varname>,
+                                <varname>sh64</varname>,
+                                <varname>m86k</varname> to test
+                                against a specific architecture. The
+                                architecture is determined from the
+                                information returned by
+                                <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+                                and is thus subject to
+                                <citerefentry><refentrytitle>personality</refentrytitle><manvolnum>2</manvolnum></citerefentry>. Note
+                                that a <varname>Personality=</varname>
+                                setting in the same unit file has no
+                                effect on this condition. A special
+                                architecture name
+                                <varname>native</varname> is mapped to
+                                the architecture the system manager
+                                itself is compiled for. The test may
+                                be negated by prepending an
+                                exclamation mark.</para>

 
                                 <para><varname>ConditionVirtualization=</varname>
                                 may be used to check whether the
 
                                 <para><varname>ConditionVirtualization=</varname>
                                 may be used to check whether the


@@ -1028,6 +996,36 @@
                                 test may be negated by prepending an
                                 exclamation mark.</para>
 
                                 test may be negated by prepending an
                                 exclamation mark.</para>
 

+                                <para><varname>ConditionHost=</varname>
+                                may be used to match against the
+                                hostname or machine ID of the
+                                host. This either takes a hostname
+                                string (optionally with shell style
+                                globs) which is tested against the
+                                locally set hostname as returned by
+                                <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+                                or a machine ID formatted as string
+                                (see
+                                <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+                                The test may be negated by prepending
+                                an exclamation mark.</para>
+
+                                <para><varname>ConditionKernelCommandLine=</varname>
+                                may be used to check whether a
+                                specific kernel command line option is
+                                set (or if prefixed with the
+                                exclamation mark unset). The argument
+                                must either be a single word, or an
+                                assignment (i.e. two words, separated
+                                <literal>=</literal>). In the former
+                                case the kernel command line is
+                                searched for the word appearing as is,
+                                or as left hand side of an
+                                assignment. In the latter case, the
+                                exact assignment is looked for with
+                                right and left hand side
+                                matching.</para>
+

                                 <para><varname>ConditionSecurity=</varname>
                                 may be used to check whether the given
                                 security module is enabled on the
                                 <para><varname>ConditionSecurity=</varname>
                                 may be used to check whether the given
                                 security module is enabled on the


@@ -1053,20 +1051,6 @@
                                 possibly prefixed with an exclamation
                                 mark to negate the check.</para>
 
                                 possibly prefixed with an exclamation
                                 mark to negate the check.</para>
 

-                                <para><varname>ConditionHost=</varname>
-                                may be used to match against the
-                                hostname or machine ID of the
-                                host. This either takes a hostname
-                                string (optionally with shell style
-                                globs) which is tested against the
-                                locally set hostname as returned by
-                                <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
-                                or a machine ID formatted as string
-                                (see
-                                <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
-                                The test may be negated by prepending
-                                an exclamation mark.</para>
-

                                 <para><varname>ConditionACPower=</varname>
                                 may be used to check whether the
                                 system has AC power, or is exclusively
                                 <para><varname>ConditionACPower=</varname>
                                 may be used to check whether the
                                 system has AC power, or is exclusively


@@ -1084,6 +1068,77 @@
                                 all AC connectors are disconnected
                                 from a power source.</para>
 
                                 all AC connectors are disconnected
                                 from a power source.</para>
 

+                                <para>With
+                                <varname>ConditionPathExists=</varname>
+                                a file existence condition is
+                                checked before a unit is started. If
+                                the specified absolute path name does
+                                not exist, the condition will
+                                fail. If the absolute path name passed
+                                to
+                                <varname>ConditionPathExists=</varname>
+                                is prefixed with an exclamation mark
+                                (<literal>!</literal>), the test is negated, and the unit
+                                is only started if the path does not
+                                exist.</para>
+
+                                <para><varname>ConditionPathExistsGlob=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>,
+                                but checks for the existence of at
+                                least one file or directory matching
+                                the specified globbing pattern.</para>
+
+                                <para><varname>ConditionPathIsDirectory=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists and is a
+                                directory.</para>
+
+                                <para><varname>ConditionPathIsSymbolicLink=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists and is a symbolic
+                                link.</para>
+
+                                <para><varname>ConditionPathIsMountPoint=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists and is a mount
+                                point.</para>
+
+                                <para><varname>ConditionPathIsReadWrite=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether the underlying
+                                file system is readable and writable
+                                (i.e. not mounted
+                                read-only).</para>
+
+                                <para><varname>ConditionDirectoryNotEmpty=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists and is a non-empty
+                                directory.</para>
+
+                                <para><varname>ConditionFileNotEmpty=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists and refers to a regular file
+                                with a non-zero size.</para>
+
+                                <para><varname>ConditionFileIsExecutable=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists, is a regular file and marked
+                                executable.</para>
+

                                 <para>Finally,
                                 <varname>ConditionNull=</varname> may
                                 be used to add a constant condition
                                 <para>Finally,
                                 <varname>ConditionNull=</varname> may
                                 be used to add a constant condition


@@ -1126,12 +1181,17 @@
                                 useful for implementation of generator
                                 tools that convert configuration from
                                 an external configuration file format
                                 useful for implementation of generator
                                 tools that convert configuration from
                                 an external configuration file format

-                                into native unit files. Thus
+                                into native unit files. This

                                 functionality should not be used in
                                 normal units.</para></listitem>
                         </varlistentry>
                 </variablelist>
 
                                 functionality should not be used in
                                 normal units.</para></listitem>
                         </varlistentry>
                 </variablelist>
 

+        </refsect1>
+
+        <refsect1>
+                <title>[Install] Section Options</title>
+

                 <para>Unit file may include a [Install] section, which
                 carries installation information for the unit. This
                 section is not interpreted by
                 <para>Unit file may include a [Install] section, which
                 carries installation information for the unit. This
                 section is not interpreted by


@@ -1226,6 +1286,19 @@
                                 of unit names may be
                                 given.</para></listitem>
                         </varlistentry>
                                 of unit names may be
                                 given.</para></listitem>
                         </varlistentry>

+
+                        <varlistentry>
+                                <term><varname>DefaultInstance=</varname></term>
+
+                                <listitem><para>In template unit files,
+                                this specifies for which instance the
+                                unit shall be enabled if the template
+                                is enabled without any explicitly set
+                                instance. This option has no effect in
+                                non-template unit files. The specified
+                                string must be usable as instance
+                                identifier.</para></listitem>
+                        </varlistentry>

                 </variablelist>
 
                 <para>The following specifiers are interpreted in the
                 </variablelist>
 
                 <para>The following specifiers are interpreted in the