From c9b3950580db43c576d3ec8f7bf14e49905a09cb Mon Sep 17 00:00:00 2001

From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>

Date: Sat, 13 Aug 2016 09:38:12 -0400

Subject: [PATCH] man: describe what symlinks to unit do, and specify that

 presets must use real names

The man pages didn't ever mention that symlinks to units can be created, and what

exactly this means. Fix that omission, and disallow presets on alias names.

(cherry picked from commit d923e42eed9a29137821760dafecb13798264c07)

---

 man/systemctl.xml      |  3 ++-

 man/systemd.preset.xml |  4 ++++

 man/systemd.unit.xml   | 36 +++++++++++++++++++++++-------------

 3 files changed, 29 insertions(+), 14 deletions(-)

diff --git a/man/systemctl.xml b/man/systemctl.xml

index e7880d24f7..8b73e91bdb 100644

--- a/man/systemctl.xml

+++ b/man/systemctl.xml

@@ -1088,7 +1088,8 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service

             enabled and disabled, or only enabled, or only disabled.</para>

             <para>If the unit carries no install information, it will be silently ignored

-            by this command.</para>

+            by this command. <replaceable>NAME</replaceable> must be the real unit name,

+            any alias names are ignored silently.</para>

             <para>For more information on the preset policy format, see

             <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>.

diff --git a/man/systemd.preset.xml b/man/systemd.preset.xml

index b7164014f0..d09167baaf 100644

--- a/man/systemd.preset.xml

+++ b/man/systemd.preset.xml

@@ -98,6 +98,10 @@

     Empty lines and lines whose first non-whitespace character is # or

     ; are ignored.</para>

+    <para>Presets must refer to the "real" unit file, and not to any aliases. See

+    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>

+    for a description of unit aliasing.</para>

+

     <para>Two different directives are understood:

     <literal>enable</literal> may be used to enable units by default,

     <literal>disable</literal> to disable units by default.</para>

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml

index 85a7b12d76..f818e772a9 100644

--- a/man/systemd.unit.xml

+++ b/man/systemd.unit.xml

@@ -144,21 +144,31 @@

     <option>false</option> and <option>off</option> are

     equivalent.</para>

-    <para>Time span values encoded in unit files can be written in

-    various formats. A stand-alone number specifies a time in seconds.

-    If suffixed with a time unit, the unit is honored. A concatenation

-    of multiple values with units is supported, in which case the

-    values are added up. Example: "50" refers to 50 seconds; "2min

-    200ms" refers to 2 minutes plus 200 milliseconds, i.e. 120200ms.

-    The following time units are understood: s, min, h, d, w, ms, us.

-    For details see

+    <para>Time span values encoded in unit files can be written in various formats. A stand-alone number specifies a

+    time in seconds.  If suffixed with a time unit, the unit is honored. A concatenation of multiple values with units

+    is supported, in which case the values are added up. Example: <literal>50</literal> refers to 50 seconds;

+    <literal>2min 200ms</literal> refers to 2 minutes and 200 milliseconds, i.e. 120200 ms.  The following time units

+    are understood: <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>d</literal>,

+    <literal>w</literal>, <literal>ms</literal>, <literal>us</literal>.  For details see

     <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>

-    <para>Empty lines and lines starting with # or ; are

-    ignored. This may be used for commenting. Lines ending

-    in a backslash are concatenated with the following

-    line while reading and the backslash is replaced by a

-    space character. This may be used to wrap long lines.</para>

+    <para>Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are ignored. This may be

+    used for commenting. Lines ending in a backslash are concatenated with the following line while reading and the

+    backslash is replaced by a space character. This may be used to wrap long lines.</para>

+

+    <para>Units can be aliased (have an alternative name), by creating a symlink from the new name to the existing name

+    in one of the unit search paths. For example, <filename>systemd-networkd.service</filename> has the alias

+    <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as the symlink

+    <filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service</filename>. In addition, unit files may

+    specify aliases through the <varname>Alias=</varname> directive in the [Install] section; those aliases are only

+    effective when the unit is enabled. When the unit is enabled, symlinks will be created for those names, and removed

+    when the unit is disabled. For example, <filename>reboot.target</filename> specifies

+    <varname>Alias=ctrl-alt-del.target</varname>, so when enabled it will be invoked whenever CTRL+ALT+DEL is

+    pressed. Alias names may be used in commands like <command>enable</command>, <command>disable</command>,

+    <command>start</command>, <command>stop</command>, <command>status</command>, …, and in unit dependency directives

+    <varname>Wants=</varname>, <varname>Requires=</varname>, <varname>Before=</varname>, <varname>After=</varname>, …,

+    with the limitation that aliases specified through <varname>Alias=</varname> are only effective when the unit is

+    enabled. Aliases cannot be used with the <command>preset</command> command.</para>

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

     directory <filename>foo.service.wants/</filename> may exist. All