From 6e2f5000c7a83e3cce336d07395463491fc5f16d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 15 Sep 2017 09:33:17 +0200 Subject: [PATCH 1/7] man: delete note about propagating signal termination That advice is generally apropriate for "user" programs, i.e. programs which are run interactively and used pipelines and such. But it makes less sense for daemons to propagate the exit signal. For example, if a process receives a SIGTERM, it is apropriate for it to exit with 0 code. So let's just delete the whole paragraph, since this page doesn't seem to be the right place for the longer discussion which would be required to mention all the caveats and considerations. Fixes #6415. --- man/systemd.service.xml | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 0b8963b7b8..5b82d774ba 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -753,16 +753,6 @@ considered clean service terminations. - Note that if a process has a signal handler installed - and exits by calling - _exit2 - in response to a signal, the information about the signal is - lost. Programs should instead perform cleanup and kill - themselves with the same signal instead. See - Proper - handling of SIGINT/SIGQUIT — How to be a proper - program. - This option may appear more than once, in which case the list of successful exit statuses is merged. If the empty string is assigned to this option, the list is reset, all From 1c12694439ac3227819f5801e1fcc9f6667c820c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 15 Sep 2017 11:23:57 +0200 Subject: [PATCH 2/7] man: explain when networkd removed existing configuration and when not Fixes #6693. --- man/systemd-networkd.service.xml | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/man/systemd-networkd.service.xml b/man/systemd-networkd.service.xml index 0bfe5519bc..a6e079c887 100644 --- a/man/systemd-networkd.service.xml +++ b/man/systemd-networkd.service.xml @@ -64,13 +64,30 @@ networks, see systemd.link5. - Network configurations applied before networkd is started - are not removed, and static configuration applied by networkd is - not removed when networkd exits. Dynamic configuration applied by - networkd may also optionally be left in place on shutdown. This - ensures restarting networkd does not cut the network connection, - and, in particular, that it is safe to transition between the - initrd and the real root, and back. + systemd-networkd will create network devices based + on the configuration in + systemd.netdev5 + files, respecting the [Match] sections in those files. + + systemd-networkd will manage network addresses and + routes for any link for which it finds a .network file + with an appropriate [Match] section, see + systemd.network5. + For those links, it will flush existing network addresses and routes when + bringing up the device. Any links not matched by one of the + .network files will be ignored. It is also possible to + explicitly tell systemd-networkd to ignore a link by + using Unmanaged=yes option, see + systemd.network5. + + + When systemd-networkd exits, it generally leaves + existing network devices and configuration intact. This makes it possible to + transition from the initrams and to restart the service without breaking + connectivity. This also means that when configuration is updated and + systemd-networkd is restarted, netdev interfaces for + which configuration was removed will not be dropped, and may need to be + cleaned up manually. Configuration Files From fa69a4c74b0109f5d0ad803f9e4334180a380fb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 15 Sep 2017 11:47:46 +0200 Subject: [PATCH 3/7] man: update the description of machinectl -M Fixes #6621. Also rework the introduction a bit. --- man/machinectl.xml | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/man/machinectl.xml b/man/machinectl.xml index 46dcb44ca6..66ee0637c8 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -79,17 +79,18 @@ OS kernel with the host OS, in order to run OS userspace instances on top the host OS. - The host system itself + The host system itself. Machines are identified by names that follow the same rules - as UNIX and DNS host names, for details, see below. Machines are - instantiated from disk or file system images that frequently — but not - necessarily — carry the same name as machines running from - them. Images in this sense are considered: + as UNIX and DNS host names. For details, see below. + + Machines are instantiated from disk or file system images that + frequently — but not necessarily — carry the same name as machines running + from them. Images in this sense may be: - Directory trees containing an OS, including its + Directory trees containing an OS, including the top-level directories /usr, /etc, and so on. @@ -299,7 +300,16 @@ - + + + + + + Connect to + systemd-machined.service8 + running in a local container, to perform the specified operation within + the container. + From 157148d6d3bda380d08e4eec4de96f0db07c8dbd Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 15 Sep 2017 14:17:32 +0200 Subject: [PATCH 4/7] man: add a whole section detailing journal stdout/stderr stream logging Details about EPIPE/SIGPIPE handling, metadata and more. Fixes: #6620 --- man/systemd-journald.service.xml | 54 ++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml index 2810638bc2..559ef1090a 100644 --- a/man/systemd-journald.service.xml +++ b/man/systemd-journald.service.xml @@ -70,19 +70,18 @@ Kernel log messages, via kmsg - Simple system log messages, via the libc - syslog3 + Simple system log messages, via the libc syslog3 call Structured system log messages via the native Journal API, see sd_journal_print4 - Standard output and standard error of system - services + Standard output and standard error of service units. For further details see + below. - Audit records, via the audit - subsystem + Audit records, originating from the kernel audit subsystem The daemon will implicitly collect numerous metadata fields @@ -111,6 +110,49 @@ systemd-tmpfiles --create --prefix /var/log/journal for information about the configuration of this service. + + Stream logging + + The systemd service manager invokes all service processes with standard output and standard error connected + to the journal by default. This behaviour may be altered via the + StandardOutput=/StandardError= unit file settings, see + systemd.exec5 for details. The + journal converts the log byte stream received this way into individual log records, splitting the stream at newline + (\n, ASCII 10) and NUL bytes. + + If systemd-journald.service is stopped, the stream connections associated with all + services are terminated. Further writes to those streams by the service will result in EPIPE + errors. In order to react gracefully in this case it is recommended that programs logging to standard output/error + ignore such errors. If the the SIGPIPE UNIX signal handler is not blocked or turned off, such + write attempts will also result in such process signals being generated, see + signal7. To mitigate this issue, + systemd service manager explicitly turns off the SIGPIPE signal for all invoked processes by + default (this may be changed for each unit individually via the IgnoreSIGPIPE= option, see + systemd.exec5 for + details). After the standard output/standard error streams have been terminated they may not be recovered until the + services they are associated with are restarted. Note that during normal operation, + systemd-journald.service stores copies of the file descriptors for those streams in the + service manager. If systemd-journald.service is restarted using systemctl + restart or equivalent operation instead of a pair of separate systemctl stop and + systemctl start commands (or equivalent operations), these stream connections are not terminated + and survive the restart. It is thus safe to restart systemd-journald.service, but stopping it + is not recommended. + + Note that the log record metadata for records transferred via such standard output/error streams reflect the + metadata of the peer the stream was originally created for. If the stream connection is passed on to other + processes (such as further child processes forked off the main service process), the log records will not reflect + their metadata, but will continue to describe the original process. This is different from the other logging + transports listed above, which are inherently record based and where the metadata is always associated with the + individual record. + + In addition to the the implicit standard output/error logging of services, stream logging is also available + via the systemd-cat1 command + line tool. + + Currently, the number of parallel log streams systemd-journald will accept is limited + to 4096. + + Signals From 8baa95250bc4a11088bf823fcf9b694af8687781 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 15 Sep 2017 14:49:44 +0200 Subject: [PATCH 5/7] mailmap: add entry to fix encoding issues --- .mailmap | 1 + 1 file changed, 1 insertion(+) diff --git a/.mailmap b/.mailmap index 73b0700f59..fb64c767e5 100644 --- a/.mailmap +++ b/.mailmap @@ -124,3 +124,4 @@ Josef Andersson Josef Andersson Hendrik Westerberg Stefan Pietsch +Jérémy Rosen From cd9363b11c17c07ec890cb400a4440a2c9ea809d Mon Sep 17 00:00:00 2001 From: Russell Stuart Date: Wed, 13 Sep 2017 09:25:04 +1000 Subject: [PATCH 6/7] man: update udevadm -y/--sysname-match documentation Fixes #6792. [zj: reorganize the sentece for grammatical correctness.] --- man/udevadm.xml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/man/udevadm.xml b/man/udevadm.xml index 8d4fe31ec1..7ace4f9826 100644 --- a/man/udevadm.xml +++ b/man/udevadm.xml @@ -308,9 +308,11 @@ - Trigger events for devices with a matching sys - device path. This option can be specified multiple times - and supports shell style pattern matching. + Trigger events for devices for which the last component + (i.e. the filename) of the /sys path matches + the specified PATH. This option can be + specified multiple times and also supports shell style pattern + matching. From 1245e4132b9584eda4efd6294779b3ed55cc0f4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 15 Sep 2017 14:59:45 +0200 Subject: [PATCH 7/7] man: use "filename" not "file name" by default We settled on "filename" and "file system", so change a couple of places for consistency. The exception is when there's an adjective before "file" that binds more strongly then "name": "password file name", "output file name", etc. Those cases are left intact. --- man/machinectl.xml | 2 +- man/sd_is_fifo.xml | 2 +- man/systemd.resource-control.xml | 2 +- man/systemd.service.xml | 4 ++-- man/systemd.unit.xml | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/man/machinectl.xml b/man/machinectl.xml index 66ee0637c8..cf46fe8024 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -819,7 +819,7 @@ qcow2 or raw disk image, possibly compressed with xz, gzip or bzip2. If the second argument (the resulting image name) is not specified, it is automatically derived from the file - name. If the file name is passed as -, the + name. If the filename is passed as -, the image is read from standard input, in which case the second argument is mandatory. diff --git a/man/sd_is_fifo.xml b/man/sd_is_fifo.xml index 1192ca1681..3bd388d80e 100644 --- a/man/sd_is_fifo.xml +++ b/man/sd_is_fifo.xml @@ -183,7 +183,7 @@ whether the specified file descriptor refers to a special file. If the path parameter is not NULL, it is checked whether the file - descriptor is bound to the specified file name. Special files in + descriptor is bound to the specified filename. Special files in this context are character device nodes and files in /proc or /sys. diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index ed75e737ac..bb69599f99 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -506,7 +506,7 @@ /proc/devices. The latter is useful to whitelist all current and future devices belonging to a specific device group at once. The device group is matched - according to file name globbing rules, you may hence use the + according to filename globbing rules, you may hence use the * and ? wildcards. Examples: /dev/sda5 is a path to a device node, referring to an ATA or SCSI block diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 5b82d774ba..2b183a9cef 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -262,7 +262,7 @@ PIDFile= - Takes an absolute file name pointing to the + Takes an absolute filename pointing to the PID file of this daemon. Use of this option is recommended for services where Type= is set to . systemd will read the PID of the @@ -302,7 +302,7 @@ ExecStop= are not valid.) For each of the specified commands, the first argument must be an absolute path to an - executable. Optionally, this file name may be prefixed with a number of special characters: + executable. Optionally, this filename may be prefixed with a number of special characters: Special executable prefixes diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 69000aab31..64ad4c2b60 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -1137,7 +1137,7 @@ Alias=A space-separated list of additional names this unit shall be installed under. The names listed - here must have the same suffix (i.e. type) as the unit file name. This option may be specified more than once, + here must have the same suffix (i.e. type) as the unit filename. This option may be specified more than once, in which case all listed names are used. At installation time, systemctl enable will create symlinks from these names to the unit filename. Note that not all unit types support such alias names, and this setting is not supported for them. Specifically, mount, slice, swap, and automount units do not support