95 lines
5.8 KiB
Diff
95 lines
5.8 KiB
Diff
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
|