From 6e004630fea24f1d4d76f8b062f9f862ba237140 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 10 Feb 2016 21:29:45 +0100 Subject: [PATCH 1/7] man: document rescue.target and emergency.target in more detail Fixes: #2523 --- man/systemd.special.xml | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) 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 @@ emergency.target - 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 - systemd.unit= and has otherwise little - use. - + 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 + systemd.unit=; it is also used when a file system check on a required file system fails, + and boot-up cannot continue. Compare with rescue.target, which serves a similar purpose, + but also starts the most basic services and mounts all file systems. + + Use the systemd.unit=emergency.target kernel command line option to boot into this + mode. A short alias for this kernel command line option is emergency, for compatibility + with SysV. + + In many ways booting into emergency.target is similar to the effect of booting + with init=/bin/sh 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. @@ -440,11 +450,18 @@ rescue.target - A special target unit for setting up the base system - and a rescue shell. + 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 + emergency.target, which is much more reduced and does not provide the file systems or + most basic services. - runlevel1.target is an alias for - this target unit, for compatibility with SysV. + runlevel1.target is an alias for this target unit, for compatibility with + SysV. + + Use the systemd.unit=rescue.target kernel command line option to boot into this + mode. A short alias for this kernel command line option is 1, for compatibility with + SysV. From 41448597f2289c570e96315abf34adab4ff204e1 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 10 Feb 2016 21:30:25 +0100 Subject: [PATCH 2/7] man: document distinction between ConditionXYZ= and AssertXYZ= References: #2468 --- man/systemd.unit.xml | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 46b288f20b..04c4515cd9 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -827,13 +827,14 @@ useful and probably just confusing. --> - 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. + 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 AssertArchitecture=, + AssertVirtualization=, … options for a similar mechanism that puts the unit in a failure + state and logs about the failed check (see below). ConditionArchitecture= may be used to check whether the system is running on a specific @@ -1067,14 +1068,12 @@ AssertFileNotEmpty= AssertFileIsExecutable= - Similar to the - ConditionArchitecture=, - ConditionVirtualization=, 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. + Similar to the ConditionArchitecture=, + ConditionVirtualization=, …, 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. From be73bb486a1a1bb43a04319c3cb0b639edd6b98f Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 10 Feb 2016 21:39:36 +0100 Subject: [PATCH 3/7] man: document that [Install] has no effect in unit file .d/*.conf drop-ins Fixes: #1774 Fixes: #1090 --- man/systemd.unit.xml | 36 +++++++++++++++--------------------- 1 file changed, 15 insertions(+), 21 deletions(-) diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 04c4515cd9..16aded89d1 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -178,18 +178,14 @@ directory suffix is .requires/ in this case. - Along with a unit file foo.service, a - directory foo.service.d/ may exist. All files - with the suffix .conf 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 - .d/ subdirectory and read its - .conf files, followed by the template - .d/ subdirectory and reads its - .conf files. + Along with a unit file foo.service, a "drop-in" directory + foo.service.d/ may exist. All files with the suffix .conf 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 + .d/ subdirectory and read its .conf files, followed by the template + .d/ subdirectory and reads its .conf files. Also note that settings from the + [Install] section are not available in drop-in unit files, and have no effect. In addition to /etc/systemd/system, the drop-in .conf files for system services @@ -1093,15 +1089,13 @@ [Install] Section Options - Unit file may include an [Install] - section, which carries installation information for the unit. This - section is not interpreted by - systemd1 - during runtime. It is used exclusively by the - enable and disable commands - of the - systemctl1 - tool during installation of a unit: + Unit files may include an [Install] section, which carries installation information for + the unit. This section is not interpreted by + systemd1 during runtime; it is + used by the enable and disable commands of the + systemctl1 tool during + installation of a unit. Note that settings in the [Install] section may not appear in + .d/*.conf unit file drop-ins (see above). From 358a9d51147f721c3e1701ea7df3522ca049254c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 10 Feb 2016 21:43:34 +0100 Subject: [PATCH 4/7] man: document that nss-myhostname handles *.localhost and *.localdomain too (And similar for resolved) Fixes: #1630 --- man/nss-myhostname.xml | 6 +++--- man/systemd-resolved.service.xml | 6 +++--- 2 files changed, 6 insertions(+), 6 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). - The hostname localhost is - resolved to the IP addresses 127.0.0.1 and - ::1. + The hostname localhost (as well as any hostname ending in + .localhost, .localdomain or equal to localdomain) is + resolved to the IP addresses 127.0.0.1 and ::1. The hostname gateway is resolved to all current default routing gateway addresses, 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). - The hostname localhost is - resolved to the IP addresses 127.0.0.1 and - ::1. + The hostname localhost (as well as any hostname ending in + .localhost, .localdomain or equal to localdomain) is + resolved to the IP addresses 127.0.0.1 and ::1. The hostname gateway is resolved to all current default routing gateway addresses, From 1534e170b495acf38e4540b9624fcb71b86cfdbf Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 10 Feb 2016 21:47:07 +0100 Subject: [PATCH 5/7] man: document that "systemctl enable" supports abbreviated unit file names Fixes: #1502 --- man/systemctl.xml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/man/systemctl.xml b/man/systemctl.xml index cce7861139..51742bfaa6 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1703,7 +1703,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service unit specifications (designated as PATTERN...). 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, .service 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. - For unit file commands, the specified - NAME should be the full name of the - unit file, or the absolute path to the unit file: + For unit file commands, the specified NAME should be the name of the unit file + (possibly abbreviated, see above), or the absolute path to the unit file: # systemctl enable foo.service or # systemctl link /path/to/foo.service From 1917c8cab4b2e4a135b8c46d43c448733c0e1564 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 10 Feb 2016 21:52:40 +0100 Subject: [PATCH 6/7] man: document that ExecStartPost= is only run if ExecStart= succeeded Fixes: #846 --- man/systemd.service.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 - exit successfully. ExecStartPost= commands are only run after - the service has started, as determined by Type= + the service has started successfully, as determined by Type= (i.e. the process has been started for Type=simple or Type=idle, the process exits successfully for Type=oneshot, the initial process exits successfully From a858cd71136c166ab37aeb96bca083e0d77e739c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 10 Feb 2016 22:02:33 +0100 Subject: [PATCH 7/7] man: correct explanation of "systemctl is-enabled" output The "is-enabled" command doesn't care whether the symlinks are declared in the [Install] section of a unit file or not, when returning "enabled". Any alias, .wants/ or .requires/ symlinks suffice. Fixes: #975 --- man/systemctl.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man/systemctl.xml b/man/systemctl.xml index 51742bfaa6..50eb939313 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1134,7 +1134,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service enabled - Enabled through creating symlinks encoded in the [Install] section (permanently or just in /run). + Enabled via .wants/, .requires/ or alias symlinks (permanently in /etc/systemd/system/, or transiently in /run/systemd/system/). 0