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 552c747695f46aaf2195ff41e37c025d63674e27..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


@@ -173,7 +181,7 @@
                 <para>Along with a unit file
                 <filename>foo.service</filename> a directory
                 <filename>foo.service.d/</filename> may exist. All
                 <para>Along with a unit file
                 <filename>foo.service</filename> a directory
                 <filename>foo.service.d/</filename> may exist. All

-                files with the suffix <filename>.conf</filename> from
+                files with the suffix <literal>.conf</literal> from

                 this directory will be parsed after the file itself is
                 parsed. This is useful to alter or add configuration
                 settings to a unit, without having to modify their
                 this directory will be parsed after the file itself is
                 parsed. This is useful to alter or add configuration
                 settings to a unit, without having to modify their


@@ -214,9 +222,9 @@
                 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
                 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

-                name contains an @ character, systemd will look for a
+                name contains an <literal>@</literal> character, systemd will look for a

                 unit template that shares the same name but with the
                 unit template that shares the same name but with the

-                instance string (i.e. the part between the @ character
+                instance string (i.e. the part between the <literal>@</literal> character

                 and the suffix) removed. Example: if a service
                 <filename>getty@tty3.service</filename> is requested
                 and no file by that name is found, systemd will look
                 and the suffix) removed. Example: if a service
                 <filename>getty@tty3.service</filename> is requested
                 and no file by that name is found, systemd will look


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


@@ -797,7 +787,7 @@
                                 highly recommended to leave this
                                 option enabled for the majority of
                                 common units. If set to
                                 highly recommended to leave this
                                 option enabled for the majority of
                                 common units. If set to

-                                <option>false</option> this option
+                                <option>false</option>, this option

                                 does not disable all implicit
                                 dependencies, just non-essential
                                 ones.</para></listitem>
                                 does not disable all implicit
                                 dependencies, just non-essential
                                 ones.</para></listitem>


@@ -969,6 +959,7 @@
                                 <varname>xen</varname>,
                                 <varname>bochs</varname>,
                                 <varname>chroot</varname>,
                                 <varname>xen</varname>,
                                 <varname>bochs</varname>,
                                 <varname>chroot</varname>,

+                                <varname>uml</varname>,

                                 <varname>openvz</varname>,
                                 <varname>lxc</varname>,
                                 <varname>lxc-libvirt</varname>,
                                 <varname>openvz</varname>,
                                 <varname>lxc</varname>,
                                 <varname>lxc-libvirt</varname>,


@@ -1115,19 +1106,46 @@
                                 <term><varname>WantedBy=</varname></term>
                                 <term><varname>RequiredBy=</varname></term>
 
                                 <term><varname>WantedBy=</varname></term>
                                 <term><varname>RequiredBy=</varname></term>
 

-                                <listitem><para>Installs a symlink in
-                                the <filename>.wants/</filename>
-                                or <filename>.requires/</filename>
-                                subdirectory for a unit, respectively. This has the
-                                effect that when the listed unit name
-                                is activated the unit listing it is
-                                activated
-                                too. <command>WantedBy=foo.service</command>
+                                <listitem><para>A symbolic link is
+                                created in the
+                                <filename>.wants/</filename> or
+                                <filename>.requires/</filename> directory
+                                of the listed unit when this unit is
+                                activated by <command>systemctl
+                                enable</command>.  This has the effect
+                                that a dependency of type
+                                <varname>Wants=</varname> or
+                                <varname>Requires=</varname> is added
+                                from the listed unit to the current
+                                unit. The primary result is that the
+                                current unit will be started when the
+                                listed unit is started. See the
+                                description of
+                                <varname>Wants=</varname> and
+                                <varname>Requires=</varname> in the
+                                [Unit] section for details.</para>
+
+                                <para><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 a service
                                 <filename>bar.service</filename> is
                                 mostly equivalent to
                                 <command>Alias=foo.service.wants/bar.service</command>

-                                in the same file.</para></listitem>
+                                in the same file. In case of template
+                                units, <command>systemctl enable</command>
+                                must be called with an instance name, and
+                                this instance will be added to the
+                                <filename>.wants/</filename> or
+                                <filename>.requires/</filename> list
+                                of the listed unit.
+                                E.g. <command>WantedBy=getty.target</command>
+                                in a service
+                                <filename>getty@.service</filename>
+                                will result in <command>systemctl
+                                enable getty@tty2.service</command>
+                                creating a
+                                <filename>getty.target.wants/getty@tty2.service</filename>
+                                link to <filename>getty@.service</filename>.
+                                </para></listitem>

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


@@ -1147,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>


@@ -1198,7 +1216,7 @@
                       <row>
                         <entry><literal>%i</literal></entry>
                         <entry>Instance name</entry>
                       <row>
                         <entry><literal>%i</literal></entry>
                         <entry>Instance name</entry>

-                        <entry>For instantiated units: this is the string between the @ character and the suffix.</entry>
+                        <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix.</entry>

                       </row>
                       <row>
                         <entry><literal>%I</literal></entry>
                       </row>
                       <row>
                         <entry><literal>%I</literal></entry>


@@ -1265,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>


@@ -1291,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>