X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=17141576d052e9fea76e1f977d0252d72bdddd1c;hp=4f0bd64b121728c488e8ba1747f39348d55b5206;hb=693093c6db9d8510729b7566e74182b4ff50e31c;hpb=409dee2e44e7dc73d6bf00d782938e4cb4105f5b

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 4f0bd64b1..17141576d 100644
--- 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>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>
@@ -68,7 +70,8 @@
 <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>
@@ -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
-                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
-                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>
 
@@ -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.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
@@ -173,7 +181,7 @@
                 <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
@@ -249,10 +257,9 @@
 
                 <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
@@ -276,33 +283,17 @@
                       </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>
-                        <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>
-                        <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>
@@ -310,7 +301,7 @@
 
                 <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'>
@@ -324,8 +315,8 @@
                     </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>
@@ -333,23 +324,11 @@
                       </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>
-                        <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>
@@ -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
-                <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>
 
@@ -377,7 +359,15 @@
                                 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>
@@ -969,6 +959,7 @@
                                 <varname>xen</varname>,
                                 <varname>bochs</varname>,
                                 <varname>chroot</varname>,
+                                <varname>uml</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>
 
-                                <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 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>
@@ -1147,7 +1165,7 @@
                 </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>
@@ -1265,6 +1283,11 @@
                         <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>
@@ -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.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.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>