systemd.unit(5): clarify the Description= contents

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

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index f45632a0e3599a8bfe5cc7c906ff14d4ee0b8572..17141576d052e9fea76e1f977d0252d72bdddd1c 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -60,7 +60,9 @@
                 <filename><replaceable>target</replaceable>.target</filename>,
                 <filename><replaceable>path</replaceable>.path</filename>,
                 <filename><replaceable>timer</replaceable>.timer</filename>,
                 <filename><replaceable>target</replaceable>.target</filename>,
                 <filename><replaceable>path</replaceable>.path</filename>,
                 <filename><replaceable>timer</replaceable>.timer</filename>,

-                <filename><replaceable>snapshot</replaceable>.snapshot</filename></para>
+                <filename><replaceable>snapshot</replaceable>.snapshot</filename>,
+                <filename><replaceable>slice</replaceable>.slice</filename>,
+                <filename><replaceable>scope</replaceable>.scope</filename></para>

 
                 <para><literallayout><filename>/etc/systemd/system/*</filename>
 <filename>/run/systemd/system/*</filename>
 
                 <para><literallayout><filename>/etc/systemd/system/*</filename>
 <filename>/run/systemd/system/*</filename>


@@ -68,7 +70,8 @@
 <filename>...</filename>
                 </literallayout></para>
 
 <filename>...</filename>
                 </literallayout></para>
 

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

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


@@ -81,12 +84,15 @@
                 <para>A unit configuration file encodes information
                 about a service, a socket, a device, a mount point, an
                 automount point, a swap file or partition, a start-up
                 <para>A unit configuration file encodes information
                 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 <ulink
+                target, a watched file system path, a timer controlled
+                and supervised by
+                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                a temporary system state snapshot, a resource
+                management slice or a group of externally created
+                processes. The syntax is inspired by <ulink

                 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
                 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG

-                Desktop Entry Specification</ulink> <filename>.desktop</filename> files, which are in turn
+                Desktop Entry Specification</ulink>
+                <filename>.desktop</filename> files, which are in turn

                 inspired by Microsoft Windows
                 <filename>.ini</filename> files.</para>
 
                 inspired by Microsoft Windows
                 <filename>.ini</filename> files.</para>
 


@@ -110,6 +116,8 @@
                 <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.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.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+                <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>.

                 </para>
 
                 <para>Unit files are loaded from a set of paths
                 </para>
 
                 <para>Unit files are loaded from a set of paths


@@ -249,10 +257,9 @@
 
                 <para>Unit files are loaded from a set of paths
                 determined during compilation, described in the two
 
                 <para>Unit files are loaded from a set of paths
                 determined during compilation, described in the two

-                tables below. Unit files found in directories higher
-                in the hierarchy override files with the same name
-                lower in the hierarchy, thus allowing overrides.
-                </para>
+                tables below. Unit files found in directories listed
+                earlier override files with the same name in
+                directories lower in the list.</para>

 
                 <para>When systemd is running in user mode
                 (<option>--user</option>) and the variable
 
                 <para>When systemd is running in user mode
                 (<option>--user</option>) and the variable


@@ -276,33 +283,17 @@
                       </row>
                     </thead>
                     <tbody>
                       </row>
                     </thead>
                     <tbody>

-                      <row>
-                        <entry><filename>/run/systemd/generator.early</filename></entry>
-                        <entry>Generated units (early)</entry>
-                      </row>

                       <row>
                         <entry><filename>/etc/systemd/system</filename></entry>
                         <entry>Local configuration</entry>
                       </row>
                       <row>
                       <row>
                         <entry><filename>/etc/systemd/system</filename></entry>
                         <entry>Local configuration</entry>
                       </row>
                       <row>

-                        <entry><filename>/run/systemd/systemd</filename></entry>
-                        <entry>Volatile units</entry>
-                      </row>
-                      <row>
-                        <entry><filename>/run/systemd/generator</filename></entry>
-                        <entry>Generated units (middle)</entry>
-                      </row>
-                      <row>
-                        <entry><filename>/usr/local/lib/systemd/system</filename></entry>
-                        <entry>Units for local packages</entry>
+                        <entry><filename>/run/systemd/system</filename></entry>
+                        <entry>Runtime units</entry>

                       </row>
                       <row>
                         <entry><filename>/usr/lib/systemd/system</filename></entry>
                       </row>
                       <row>
                         <entry><filename>/usr/lib/systemd/system</filename></entry>

-                        <entry>Units for installed packages</entry>
-                      </row>
-                      <row>
-                        <entry><filename>/run/systemd/generator.late</filename></entry>
-                        <entry>Generated units (late)</entry>
+                        <entry>Units of installed packages</entry>

                       </row>
                     </tbody>
                   </tgroup>
                       </row>
                     </tbody>
                   </tgroup>


@@ -310,7 +301,7 @@
 
                 <table>
                   <title>
 
                 <table>
                   <title>

-                    Load path when running in session mode (<option>--user</option>).
+                    Load path when running in user mode (<option>--user</option>).

                   </title>
 
                   <tgroup cols='2'>
                   </title>
 
                   <tgroup cols='2'>


@@ -324,8 +315,8 @@
                     </thead>
                     <tbody>
                       <row>
                     </thead>
                     <tbody>
                       <row>

-                        <entry><filename>/tmp/systemd-generator.early.<replaceable>XXXXXX</replaceable></filename></entry>
-                        <entry>Generated units (early)</entry>
+                        <entry><filename>$HOME/.config/systemd/user</filename></entry>
+                        <entry>User configuration</entry>

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


@@ -333,23 +324,11 @@
                       </row>
                       <row>
                         <entry><filename>/run/systemd/user</filename></entry>
                       </row>
                       <row>
                         <entry><filename>/run/systemd/user</filename></entry>

-                        <entry>Volatile units</entry>
-                      </row>
-                      <row>
-                        <entry><filename>/tmp/systemd-generator.<replaceable>XXXXXX</replaceable></filename></entry>
-                        <entry>Generated units (middle)</entry>
-                      </row>
-                      <row>
-                        <entry><filename>/usr/local/lib/systemd/user</filename></entry>
-                        <entry>Units for local packages</entry>
+                        <entry>Runtime units</entry>

                       </row>
                       <row>
                         <entry><filename>/usr/lib/systemd/user</filename></entry>
                       </row>
                       <row>
                         <entry><filename>/usr/lib/systemd/user</filename></entry>

-                        <entry>Units for installed packages</entry>
-                      </row>
-                      <row>
-                        <entry><filename>/tmp/systemd-generator.late.<replaceable>XXXXXX</replaceable></filename></entry>
-                        <entry>Generated units (late)</entry>
+                        <entry>Units of installed packages</entry>

                       </row>
                     </tbody>
                   </tgroup>
                       </row>
                     </tbody>
                   </tgroup>


@@ -358,7 +337,10 @@
                 <para>Additional units might be loaded into systemd
                 ("linked") from directories not on the unit load
                 path. See the <command>link</command> command for
                 <para>Additional units might be loaded into systemd
                 ("linked") from directories not on the unit load
                 path. See the <command>link</command> command for

-                <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+                <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Also,
+                some units are dynamically created via generators
+                <ulink
+                url="http://www.freedesktop.org/wiki/Software/systemd/Generators/">Generators</ulink>.

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


@@ -377,7 +359,15 @@
                                 describing the unit. This is intended
                                 for use in UIs to show descriptive
                                 information along with the unit
                                 describing the unit. This is intended
                                 for use in UIs to show descriptive
                                 information along with the unit

-                                name.</para></listitem>
+                                name. The description should contain a name
+                                that means something to the end user.
+                                <literal>Apache2 Web Server</literal> is a good
+                                example. Bad examples are
+                                <literal>high-performance light-weight HTTP
+                                server</literal> (too generic) or
+                                <literal>Apache2</literal> (too specific and
+                                meaningless for people who do not know
+                                Apache).</para></listitem>

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


@@ -1119,7 +1109,7 @@
                                 <listitem><para>A symbolic link is
                                 created in the
                                 <filename>.wants/</filename> or
                                 <listitem><para>A symbolic link is
                                 created in the
                                 <filename>.wants/</filename> or

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

                                 of the listed unit when this unit is
                                 activated by <command>systemctl
                                 enable</command>.  This has the effect
                                 of the listed unit when this unit is
                                 activated by <command>systemctl
                                 enable</command>.  This has the effect


@@ -1175,7 +1165,7 @@
                 </variablelist>
 
                 <para>The following specifiers are interpreted in the
                 </variablelist>
 
                 <para>The following specifiers are interpreted in the

-                Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b.
+                Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v.

                 For their meaning see the next section.
                 </para>
         </refsect1>
                 For their meaning see the next section.
                 </para>
         </refsect1>


@@ -1293,6 +1283,11 @@
                         <entry>Host name</entry>
                         <entry>The hostname of the running system.</entry>
                       </row>
                         <entry>Host name</entry>
                         <entry>The hostname of the running system.</entry>
                       </row>

+                      <row>
+                        <entry><literal>%v</literal></entry>
+                        <entry>Kernel release</entry>
+                        <entry>Identical to <command>uname -r</command> output.</entry>
+                      </row>

                       <row>
                         <entry><literal>%%</literal></entry>
                         <entry>Escaped %</entry>
                       <row>
                         <entry><literal>%%</literal></entry>
                         <entry>Escaped %</entry>


@@ -1319,9 +1314,12 @@
                         <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.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.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

                         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,

-                        <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry>

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