summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>2016-02-10 19:49:14 -0500
committerZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>2016-02-10 19:49:14 -0500
commit462c0cc526358b53bbf9177583c3273d866fac1b (patch)
treecf26381ff0da1663a392009f1ece57475cc98a0b
parent926db6521b16f5fbf9c532142fd243ee6cea4ca8 (diff)
parenta858cd71136c166ab37aeb96bca083e0d77e739c (diff)
Merge pull request #2575 from poettering/manfixes
A variety of man page fixes
-rw-r--r--man/nss-myhostname.xml6
-rw-r--r--man/systemctl.xml9
-rw-r--r--man/systemd-resolved.service.xml6
-rw-r--r--man/systemd.service.xml2
-rw-r--r--man/systemd.special.xml37
-rw-r--r--man/systemd.unit.xml65
6 files changed, 67 insertions, 58 deletions
diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml
index 859bec29e3..251bdecbad 100644
--- a/man/nss-myhostname.xml
+++ b/man/nss-myhostname.xml
@@ -71,9 +71,9 @@
is on the local loopback) and the IPv6 address ::1 (which is the
local host).</para></listitem>
- <listitem><para>The hostname <literal>localhost</literal> is
- resolved to the IP addresses 127.0.0.1 and
- ::1.</para></listitem>
+ <listitem><para>The hostname <literal>localhost</literal> (as well as any hostname ending in
+ <literal>.localhost</literal>, <literal>.localdomain</literal> or equal to <literal>localdomain</literal>) is
+ resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem>
<listitem><para>The hostname <literal>gateway</literal> is
resolved to all current default routing gateway addresses,
diff --git a/man/systemctl.xml b/man/systemctl.xml
index cce7861139..50eb939313 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -1134,7 +1134,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
<tbody>
<row>
<entry><literal>enabled</literal></entry>
- <entry morerows='1'>Enabled through creating symlinks encoded in the <literal>[Install]</literal> section (permanently or just in <filename>/run</filename>).</entry>
+ <entry morerows='1'>Enabled via <filename>.wants/</filename>, <filename>.requires/</filename> or alias symlinks (permanently in <filename>/etc/systemd/system/</filename>, or transiently in <filename>/run/systemd/system/</filename>).</entry>
<entry morerows='1'>0</entry>
</row>
<row>
@@ -1703,7 +1703,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
unit specifications (designated as
<replaceable>PATTERN</replaceable>...). In the first case, the
unit name with or without a suffix must be given. If the suffix
- is not specified, systemctl will append a suitable suffix,
+ is not specified ("abbreviated"), systemctl will append a suitable suffix,
<literal>.service</literal> by default, and a type-specific
suffix in case of commands which operate only on specific unit
types. For example,
@@ -1740,9 +1740,8 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
loaded are not considered for glob expansion.
</para>
- <para>For unit file commands, the specified
- <replaceable>NAME</replaceable> should be the full name of the
- unit file, or the absolute path to the unit file:
+ <para>For unit file commands, the specified <replaceable>NAME</replaceable> should be the name of the unit file
+ (possibly abbreviated, see above), or the absolute path to the unit file:
<programlisting># systemctl enable foo.service</programlisting>
or
<programlisting># systemctl link /path/to/foo.service</programlisting>
diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml
index 1b63afdded..4b4ea52aba 100644
--- a/man/systemd-resolved.service.xml
+++ b/man/systemd-resolved.service.xml
@@ -87,9 +87,9 @@
is on the local loopback) and the IPv6 address ::1 (which is the
local host).</para></listitem>
- <listitem><para>The hostname <literal>localhost</literal> is
- resolved to the IP addresses 127.0.0.1 and
- ::1.</para></listitem>
+ <listitem><para>The hostname <literal>localhost</literal> (as well as any hostname ending in
+ <literal>.localhost</literal>, <literal>.localdomain</literal> or equal to <literal>localdomain</literal>) is
+ resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem>
<listitem><para>The hostname <literal>gateway</literal> is
resolved to all current default routing gateway addresses,
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 2145e33d05..d7760d4f2c 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -371,7 +371,7 @@
with a <literal>-</literal> exit successfully.</para>
<para><varname>ExecStartPost=</varname> commands are only run after
- the service has started, as determined by <varname>Type=</varname>
+ the service has started successfully, as determined by <varname>Type=</varname>
(i.e. the process has been started for <varname>Type=simple</varname>
or <varname>Type=idle</varname>, the process exits successfully for
<varname>Type=oneshot</varname>, the initial process exits successfully
diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index 0a37f65956..055d854555 100644
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -204,12 +204,22 @@
<varlistentry>
<term><filename>emergency.target</filename></term>
<listitem>
- <para>A special target unit that starts an emergency shell
- on the main console. This unit is supposed to be used with
- the kernel command line option
- <varname>systemd.unit=</varname> and has otherwise little
- use.
- </para>
+ <para>A special target unit that starts an emergency shell on the main console. This target does not pull in
+ any serices or mounts. It is the most minimal version of starting the system in order to acquire an
+ interactive shell; the only processes running are usually just the system manager (PID 1) and the shell
+ process. This unit is supposed to be used with the kernel command line option
+ <varname>systemd.unit=</varname>; it is also used when a file system check on a required file system fails,
+ and boot-up cannot continue. Compare with <filename>rescue.target</filename>, which serves a similar purpose,
+ but also starts the most basic services and mounts all file systems.</para>
+
+ <para>Use the <literal>systemd.unit=emergency.target</literal> kernel command line option to boot into this
+ mode. A short alias for this kernel command line option is <literal>emergency</literal>, for compatibility
+ with SysV.</para>
+
+ <para>In many ways booting into <filename>emergency.target</filename> is similar to the effect of booting
+ with <literal>init=/bin/sh</literal> on the kernel command line, except that emergency mode provides you with
+ the full system and service manager, and allows starting individual units in order to continue the boot
+ process in steps.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -440,11 +450,18 @@
<varlistentry>
<term><filename>rescue.target</filename></term>
<listitem>
- <para>A special target unit for setting up the base system
- and a rescue shell.</para>
+ <para>A special target unit that pulls in the base system (including system mounts) and spawns a rescue
+ shell. Isolate to this target in order to administer the system in single-user mode with all file systems
+ mounted but with no services running, except for the most basic. Compare with
+ <filename>emergency.target</filename>, which is much more reduced and does not provide the file systems or
+ most basic services.</para>
- <para><filename>runlevel1.target</filename> is an alias for
- this target unit, for compatibility with SysV.</para>
+ <para><filename>runlevel1.target</filename> is an alias for this target unit, for compatibility with
+ SysV.</para>
+
+ <para>Use the <literal>systemd.unit=rescue.target</literal> kernel command line option to boot into this
+ mode. A short alias for this kernel command line option is <literal>1</literal>, for compatibility with
+ SysV.</para>
</listitem>
</varlistentry>
<varlistentry>
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 46b288f20b..16aded89d1 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -178,18 +178,14 @@
directory suffix is <filename>.requires/</filename> in this
case.</para>
- <para>Along with a unit file <filename>foo.service</filename>, a
- directory <filename>foo.service.d/</filename> may exist. All 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 unit files. Make sure that the file that is included has the
- appropriate section headers before any directive. Note that, for
- instanced units, this logic will first look for the instance
- <literal>.d/</literal> subdirectory and read its
- <literal>.conf</literal> files, followed by the template
- <literal>.d/</literal> subdirectory and reads its
- <literal>.conf</literal> files.</para>
+ <para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory
+ <filename>foo.service.d/</filename> may exist. All 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 unit files. Make sure that the file that is included has the appropriate
+ section headers before any directive. Note that for instanced units, this logic will first look for the instance
+ <literal>.d/</literal> subdirectory and read its <literal>.conf</literal> files, followed by the template
+ <literal>.d/</literal> subdirectory and reads its <literal>.conf</literal> files. Also note that settings from the
+ <literal>[Install]</literal> section are not available in drop-in unit files, and have no effect.</para>
<para>In addition to <filename>/etc/systemd/system</filename>,
the drop-in <literal>.conf</literal> files for system services
@@ -827,13 +823,14 @@
useful and probably just
confusing. -->
- <listitem><para>Before starting a unit verify that the
- specified condition is true. If it is not true, the starting
- of the unit will be skipped, however all ordering dependencies
- of it are still respected. A failing condition will not result
- in the unit being moved into a failure state. The condition is
- checked at the time the queued start job is to be
- executed.</para>
+ <listitem><para>Before starting a unit, verify that the specified condition is true. If it is not true, the
+ starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still
+ respected. A failing condition will not result in the unit being moved into a failure state. The condition is
+ checked at the time the queued start job is to be executed. Use condition expressions in order to silently skip
+ units that do not apply to the local running system, for example because the kernel or runtime environment
+ doesn't require its functionality. Use the various <varname>AssertArchitecture=</varname>,
+ <varname>AssertVirtualization=</varname>, … options for a similar mechanism that puts the unit in a failure
+ state and logs about the failed check (see below).</para>
<para><varname>ConditionArchitecture=</varname> may be used to
check whether the system is running on a specific
@@ -1067,14 +1064,12 @@
<term><varname>AssertFileNotEmpty=</varname></term>
<term><varname>AssertFileIsExecutable=</varname></term>
- <listitem><para>Similar to the
- <varname>ConditionArchitecture=</varname>,
- <varname>ConditionVirtualization=</varname>, etc., condition
- settings described above, these settings add assertion checks
- to the start-up of the unit. However, unlike the conditions
- settings, any assertion setting that is not met results in
- failure of the start job it was triggered
- by.</para></listitem>
+ <listitem><para>Similar to the <varname>ConditionArchitecture=</varname>,
+ <varname>ConditionVirtualization=</varname>, …, condition settings described above, these settings add
+ assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting
+ that is not met results in failure of the start job it was triggered by (which means this is logged about
+ loudly). Use assertion expressions for units that cannot operate when specific requirements are not met, and
+ where this is something the administrator or user should look into.</para></listitem>
</varlistentry>
<varlistentry>
@@ -1094,15 +1089,13 @@
<refsect1>
<title>[Install] Section Options</title>
- <para>Unit file may include an <literal>[Install]</literal>
- section, which carries installation information for the unit. This
- section is not interpreted by
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- during runtime. It is used exclusively by the
- <command>enable</command> and <command>disable</command> commands
- of the
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- tool during installation of a unit:</para>
+ <para>Unit files may include an <literal>[Install]</literal> section, which carries installation information for
+ the unit. This section is not interpreted by
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> during runtime; it is
+ used by the <command>enable</command> and <command>disable</command> commands of the
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool during
+ installation of a unit. Note that settings in the <literal>[Install]</literal> section may not appear in
+ <filename>.d/*.conf</filename> unit file drop-ins (see above).</para>
<variablelist class='unit-directives'>
<varlistentry>