From 4f57f77267610388139272d9ab9ee64dd78e9720 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sat, 27 Feb 2021 19:00:51 +0100 Subject: [PATCH 01/18] man: make systemd-coredump and coredumpctl descriptions more accessible Fixes #17910: we didn't clearly explain that coredumps may exist without journal entries, and vice versa. Also, make the examples more concrete, and use '$' instead of '#' to avoid suggesting that running as root is required. The text is extended a bit in various places. In the description of systemd-coredump, the details of executor separation are split out to a separate subsection, since they are rather detailed and not necessary to understand for normal use. --- man/coredumpctl.xml | 28 +++++++++---- man/systemd-coredump.xml | 89 +++++++++++++++++++++++----------------- 2 files changed, 71 insertions(+), 46 deletions(-) diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml index f69f26dc668..2b602b71fa0 100644 --- a/man/coredumpctl.xml +++ b/man/coredumpctl.xml @@ -324,35 +324,47 @@ Examples - List all the core dumps of a program named foo + List all the core dumps of a program - # coredumpctl list foo + $ coredumpctl list /usr/lib64/firefox/firefox +TIME PID UID GID SIG COREFILE EXE SIZE +Tue … 8018 1000 1000 SIGSEGV missing /usr/lib64/firefox/firefox n/a +Wed … 251609 1000 1000 SIGTRAP missing /usr/lib64/firefox/firefox n/a +Fri … 552351 1000 1000 SIGSEGV present /usr/lib64/firefox/firefox 28.7M + + + The journal has three entries pertaining to /usr/lib64/firefox/firefox, and + only the last entry still has an available core file (in external storage on disk). + + Note that coredumpctl needs access to the journal files to retrieve the + relevant entries from the journal. Thus, an unprivileged user will normally only see information about + crashing programs of this user. - Invoke gdb on the last core dump + Invoke <command>gdb</command> on the last core dump - # coredumpctl debug + $ coredumpctl debug - Use gdb to display full register info from the last core dump + Use <command>gdb</command> to display full register info from the last core dump - # coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'" + $ coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'" Show information about a process that dumped core, matching by its PID 6654 - # coredumpctl info 6654 + $ coredumpctl info 6654 Extract the last core dump of /usr/bin/bar to a file named <filename index="false">bar.coredump</filename> - # coredumpctl -o bar.coredump dump /usr/bin/bar + $ coredumpctl -o bar.coredump dump /usr/bin/bar diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml index f92cfd55ea7..2d53a7a8feb 100644 --- a/man/systemd-coredump.xml +++ b/man/systemd-coredump.xml @@ -32,29 +32,11 @@ Description - systemd-coredump@.service is a system service that can acquire core - dumps from the kernel and handle them in various ways. The systemd-coredump - executable does the actual work. It is invoked twice: once as the handler by the kernel, and the - second time in the systemd-coredump@.service to actually write the data to - the journal. - - When the kernel invokes systemd-coredump to handle a core dump, it runs - in privileged mode, and will connect to the socket created by the - systemd-coredump.socket unit, which in turn will spawn an unprivileged - systemd-coredump@.service instance to process the core dump. Hence - systemd-coredump.socket and systemd-coredump@.service - are helper units which do the actual processing of core dumps and are subject to normal service - management. - - Core dumps can be written to the journal or saved as a file. Once saved they can be retrieved - for further processing, for example in - gdb1. - - - By default, systemd-coredump will log the core dump including a backtrace - if possible to the journal and store the core dump itself in an external file in - /var/lib/systemd/coredump. These core dumps are deleted after a few days by - default; see /usr/lib/tmpfiles.d/systemd.conf for details. + systemd-coredump@.service is a system service to process core dumps. It will + log a summary of the event to + systemd-journald.service8, + including information about the process identifier, owner, the signal that killed the process, and the + stack trace if possible. It may also save the core dump for later processing. The behavior of a specific program upon reception of a signal is governed by a few factors which are described in detail in @@ -62,14 +44,47 @@ In particular, the core dump will only be processed when the related resource limits are sufficient. - It is also possible to invoke systemd-coredump with - option. In this case, systemd-coredump expects - a journal entry in the journal - Journal Export Format - on standard input. The entry should contain a MESSAGE= field and any additional - metadata fields the caller deems reasonable. systemd-coredump will append - additional metadata fields in the same way it does for core dumps received from the kernel. In - this mode, no core dump is stored in the journal. + Core dumps can be written to the journal or saved as a file. In both cases, they can be retrieved + for further processing, for example in + gdb1. + See coredumpctl1, + in particular the list and debug verbs. + + By default, systemd-coredump will log the core dump to the journal, including a + backtrace if possible, and store the core dump (an image of the memory contents of the process) itself in + an external file in /var/lib/systemd/coredump. These core dumps are deleted after a + few days by default; see /usr/lib/tmpfiles.d/systemd.conf for details. Note that the + removal of core files from the file system and the purging of journal entries are independent, and the + core file may be present without the journal entry, and journal entries may point to since-removed core + files. Metadata is attached to core files in the form of extended attributes, so the core files may be + useful even without the full metadata available in the journal entry. + + + + Invocation of <command>systemd-coredump</command> + + The systemd-coredump executable does the actual work. It is invoked twice: + once as the handler by the kernel, and the second time in the + systemd-coredump@.service to actually write the data to the journal and process + and save the core file. + + When the kernel invokes systemd-coredump to handle a core dump, it runs in + privileged mode, and will connect to the socket created by the + systemd-coredump.socket unit, which in turn will spawn an unprivileged + systemd-coredump@.service instance to process the core dump. Hence + systemd-coredump.socket and systemd-coredump@.service are + helper units which do the actual processing of core dumps and are subject to normal service + management. + + It is also possible to invoke systemd-coredump with + option. In this case, systemd-coredump expects a + journal entry in the journal + Journal Export Format + on standard input. The entry should contain a MESSAGE= field and any additional + metadata fields the caller deems reasonable. systemd-coredump will append additional + metadata fields in the same way it does for core dumps received from the kernel. In this mode, no core + dump is stored in the journal. + @@ -118,9 +133,8 @@ Disabling coredump processing - To disable potentially resource-intensive processing by systemd-coredump, - set Storage=none -ProcessSizeMax=0 in + To disable potentially resource-intensive processing by systemd-coredump, set + Storage=none ProcessSizeMax=0 in coredump.conf5. @@ -129,10 +143,9 @@ ProcessSizeMax=0 in Usage Data stored in the journal can be viewed with - journalctl1 - as usual. - coredumpctl1 - can be used to retrieve saved core dumps independent of their location, to display information and to process + journalctl1 as usual. + coredumpctl1 can be + used to retrieve saved core dumps independent of their location, to display information and to process them e.g. by passing to the GNU debugger (gdb). From 9d58abfa255ac5840ba8838da3d4a9b56e44e32f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 11:57:43 +0100 Subject: [PATCH 02/18] man: describe coredump fields We save a wealth of information about the process, but this might not be immediately obvious. --- man/systemd-coredump.xml | 236 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 229 insertions(+), 7 deletions(-) diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml index 2d53a7a8feb..aea1cf861fa 100644 --- a/man/systemd-coredump.xml +++ b/man/systemd-coredump.xml @@ -36,7 +36,8 @@ log a summary of the event to systemd-journald.service8, including information about the process identifier, owner, the signal that killed the process, and the - stack trace if possible. It may also save the core dump for later processing. + stack trace if possible. It may also save the core dump for later processing. See the "Information about + the crashed process" section below. The behavior of a specific program upon reception of a signal is governed by a few factors which are described in detail in @@ -141,12 +142,233 @@ - Usage - Data stored in the journal can be viewed with - journalctl1 as usual. - coredumpctl1 can be - used to retrieve saved core dumps independent of their location, to display information and to process - them e.g. by passing to the GNU debugger (gdb). + Information about the crashed process + + coredumpctl1 can + be used to retrieve saved core dumps independently of their location, to display information, and to + process them e.g. by passing to the GNU debugger (gdb). + + Data stored in the journal can be also viewed with + journalctl1 as usual + (or from any other process, using the + sd-journal3 API). + The relevant messages have MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1: + $ journalctl MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1 -o verbose +… +MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1 +COREDUMP_PID=552351 +COREDUMP_UID=1000 +COREDUMP_GID=1000 +COREDUMP_SIGNAL_NAME=SIGSEGV +COREDUMP_SIGNAL=11 +COREDUMP_TIMESTAMP=1614342930000000 +COREDUMP_COMM=Web Content +COREDUMP_EXE=/usr/lib64/firefox/firefox +COREDUMP_USER_UNIT=app-gnome-firefox-552136.scope +COREDUMP_CMDLINE=/usr/lib64/firefox/firefox -contentproc -childID 5 -isForBrowser … +COREDUMP_CGROUP=/user.slice/user-1000.slice/user@1000.service/app.slice/app-….scope +COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web….552351.….zst +… + + + The following fields are saved (if known) with the journal entry + + + + COREDUMP_UID= + COREDUMP_PID= + COREDUMP_GID= + The process number (PID) and owner (UID and GID) of the crashed process. + + + + + COREDUMP_TIMESTAMP= + The time of the crash as reported by the kernel (in µs since the epoch). + + + + + COREDUMP_RLIMIT= + The core file size soft resource limit, see + getrlimit2. + + + + + COREDUMP_UNIT= + COREDUMP_SLICE= + The system unit and slice names. + + + + + COREDUMP_CGROUP= + Control group information in the format used in + /proc/self/cgroup. On systems with the unified cgroup hierarchy, this is a + single path prefixed with 0::, and multiple paths prefixed with controller numbers + on legacy systems. + + + + COREDUMP_OWNER_UID= + COREDUMP_USER_UNIT= + The numerical UID of the user owning the login session or systemd user unit of the + crashed process, and the user manager unit. Both fields are only present for user processes. + + + + + COREDUMP_SIGNAL_NAME= + COREDUMP_SIGNAL= + + The terminating signal name and numerical value. (Both are included because signal + numbers vary by architecture.) + + + + + COREDUMP_CWD= + COREDUMP_ROOT= + + The current working directory and root directory of the crashed process. + + + + + COREDUMP_OPEN_FDS= + + Information about open file descriptors, in the following format: + fd:/path/to/file +pos: ... +flags: ... +... + +fd:/path/to/file +pos: ... +flags: ... +... + + + The first line contains the file descriptor number fd and the path, + while subsequent lines show the contents of + /proc/pid/fdinfo/fd. + + + + + COREDUMP_COMM= + COREDUMP_EXE= + COREDUMP_PROC_STATUS= + COREDUMP_PROC_MAPS= + COREDUMP_PROC_LIMITS= + COREDUMP_PROC_MOUNTINFO= + COREDUMP_ENVIRON= + + Fields that map the per-process entries in the /proc/ + filesystem: /proc/pid/comm (the command name + associated with the process), /proc/pid/exe (the + filename of the executed command), /proc/pid/status + (various metadata about the process), /proc/pid/maps + (memory regions visible to the process and their access permissions), + /proc/pid/limits (the soft and hard resource limits), + /proc/pid/mountinfo (mount points in the process's + mount namespace), /proc/pid/environ + (the environemnt block of the crashed process). + + See + proc5 + for more information. + + + + COREDUMP_HOSTNAME= + + The system hostname. + + + + COREDUMP_CONTAINER_CMDLINE= + + For processes running in a container, the commandline of the process spawning the + container (the first parent process with a different mount namespace). + + + + COREDUMP= + + When the core is stored in the journal, the core image itself. + + + + + COREDUMP_FILENAME= + + When the core is stored externally, the path the the core file. + + + + + COREDUMP_TRUNCATED= + + Set to 1 when the saved coredump was truncated. (A partial core + image may still be processed by some tools, though obviously not all information is available.) + + + + + MESSAGE= + + The message generated by systemd-coredump that includes the + backtrace if it was successfully generated. When systemd-coredump is invoked with + , this field is provided by the caller. + + + + Various other fields exist in the journal entry, but pertain to the logging process, + i.e. systemd-coredump, not the crashed process. See + systemd.journal-fields7. + + + The following fields are saved (if known) with the external file listed in + COREDUMP_FILENAME= as extended attributes: + + + + user.coredump.pid + user.coredump.uid + user.coredump.gid + user.coredump.signal + user.coredump.timestamp + user.coredump.rlimit + user.coredump.hostname + user.coredump.comm + user.coredump.exe + + Those are the same as COREDUMP_PID=, + COREDUMP_UID=, COREDUMP_GID=, + COREDUMP_SIGNAL=, COREDUMP_TIMESTAMP=, + COREDUMP_RLIMIT=, COREDUMP_HOSTNAME=, + COREDUMP_COMM=, and COREDUMP_EXE=, described above. + + + + + Those can be viewed using + getfattr1. + For the core file described in the journal entry shown above: + $ getfattr --absolute-names -d /var/lib/systemd/coredump/core.Web….552351.….zst +# file: /var/lib/systemd/coredump/core.Web….552351.….zst +user.coredump.pid="552351" +user.coredump.uid="1000" +user.coredump.gid="1000" +user.coredump.signal="11" +user.coredump.timestamp="1614342930000000" +user.coredump.comm="Web Content" +user.coredump.exe="/usr/lib64/firefox/firefox" +… + + From 3a559f22c35406225bb8f3f040625e4a4546326b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 11:58:39 +0100 Subject: [PATCH 03/18] coredump: indent comment --- src/coredump/coredump.c | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/coredump/coredump.c b/src/coredump/coredump.c index ed8d4b8ac65..c727cddba42 100644 --- a/src/coredump/coredump.c +++ b/src/coredump/coredump.c @@ -354,7 +354,7 @@ static int save_external_coredump( context->meta[META_ARGV_RLIMIT]); if (rlimit < page_size()) /* Is coredumping disabled? Then don't bother saving/processing the - * coredump. Anything below PAGE_SIZE cannot give a readable coredump + * coredump. Anything below PAGE_SIZE cannot give a readable coredump * (the kernel uses ELF_EXEC_PAGESIZE which is not easily accessible, but * is usually the same as PAGE_SIZE. */ return log_info_errno(SYNTHETIC_ERRNO(EBADSLT), @@ -435,10 +435,10 @@ static int save_external_coredump( if (tmp) unlink_noerrno(tmp); - *ret_filename = TAKE_PTR(fn_compressed); /* compressed */ - *ret_node_fd = TAKE_FD(fd_compressed); /* compressed */ - *ret_data_fd = TAKE_FD(fd); /* uncompressed */ - *ret_size = (uint64_t) st.st_size; /* uncompressed */ + *ret_filename = TAKE_PTR(fn_compressed); /* compressed */ + *ret_node_fd = TAKE_FD(fd_compressed); /* compressed */ + *ret_data_fd = TAKE_FD(fd); /* uncompressed */ + *ret_size = (uint64_t) st.st_size; /* uncompressed */ return 0; From 4ef3ca3447d134cdcbe050a820e0b8fe918288cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 12:18:25 +0100 Subject: [PATCH 04/18] =?UTF-8?q?man:=20rename=20less-variables=E2=86=92co?= =?UTF-8?q?mmon-variables?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Some are not about less, e.g. $SYSTEMD_URLIFY. --- man/{less-variables.xml => common-variables.xml} | 0 man/homectl.xml | 2 +- man/journalctl.xml | 2 +- man/localectl.xml | 2 +- man/loginctl.xml | 2 +- man/machinectl.xml | 2 +- man/portablectl.xml | 2 +- man/systemctl.xml | 12 ++++++------ man/systemd-analyze.xml | 2 +- man/systemd-inhibit.xml | 2 +- man/systemd-nspawn.xml | 2 +- man/systemd.xml | 12 ++++++------ man/timedatectl.xml | 2 +- man/userdbctl.xml | 2 +- 14 files changed, 23 insertions(+), 23 deletions(-) rename man/{less-variables.xml => common-variables.xml} (100%) diff --git a/man/less-variables.xml b/man/common-variables.xml similarity index 100% rename from man/less-variables.xml rename to man/common-variables.xml diff --git a/man/homectl.xml b/man/homectl.xml index 5e8866771e1..184bdcf6fd0 100644 --- a/man/homectl.xml +++ b/man/homectl.xml @@ -848,7 +848,7 @@ On success, 0 is returned, a non-zero failure code otherwise. - + Examples diff --git a/man/journalctl.xml b/man/journalctl.xml index 379344170d1..4be2ed3476e 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -992,7 +992,7 @@ code is returned. - + Examples diff --git a/man/localectl.xml b/man/localectl.xml index 7f7e5775c00..9fa34854eda 100644 --- a/man/localectl.xml +++ b/man/localectl.xml @@ -185,7 +185,7 @@ otherwise. - + See Also diff --git a/man/loginctl.xml b/man/loginctl.xml index 33683144fa3..56a86e56efe 100644 --- a/man/loginctl.xml +++ b/man/loginctl.xml @@ -415,7 +415,7 @@ Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima - + See Also diff --git a/man/machinectl.xml b/man/machinectl.xml index 556fe309dc4..ad47b6102e3 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -980,7 +980,7 @@ otherwise. - + See Also diff --git a/man/portablectl.xml b/man/portablectl.xml index 3f37ad11642..2dae537a40a 100644 --- a/man/portablectl.xml +++ b/man/portablectl.xml @@ -428,7 +428,7 @@ On success, 0 is returned, a non-zero failure code otherwise. - + See Also diff --git a/man/systemctl.xml b/man/systemctl.xml index 73ca3a6be04..62bc7fe832b 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -2407,12 +2407,12 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - - - - - - + + + + + + diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml index 16143d4d0fb..4da066e05c2 100644 --- a/man/systemd-analyze.xml +++ b/man/systemd-analyze.xml @@ -782,7 +782,7 @@ Service b@0.service not loaded, b.socket cannot be started. otherwise. - + See Also diff --git a/man/systemd-inhibit.xml b/man/systemd-inhibit.xml index 2fee0ede845..f6595f1e26c 100644 --- a/man/systemd-inhibit.xml +++ b/man/systemd-inhibit.xml @@ -141,7 +141,7 @@ doing so. - + See Also diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index d282238146e..187baceec21 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1486,7 +1486,7 @@ - + Examples diff --git a/man/systemd.xml b/man/systemd.xml index 893f113431e..b0b6c7236e2 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -706,12 +706,12 @@ script runlevel link farms. - - - - - - + + + + + + $LISTEN_PID diff --git a/man/timedatectl.xml b/man/timedatectl.xml index e7db4870c05..ce141523705 100644 --- a/man/timedatectl.xml +++ b/man/timedatectl.xml @@ -253,7 +253,7 @@ On success, 0 is returned, a non-zero failure code otherwise. - + Examples diff --git a/man/userdbctl.xml b/man/userdbctl.xml index 15e9a72373e..896ad222565 100644 --- a/man/userdbctl.xml +++ b/man/userdbctl.xml @@ -256,7 +256,7 @@ AuthorizedKeysCommandUser root On success, 0 is returned, a non-zero failure code otherwise. - + See Also From 5bd27a17ca1e8b5f51fa43d61816de62337ef6b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 13:22:06 +0100 Subject: [PATCH 05/18] man: describe various logging configuration variables Fixes #17484. This patch affects systemctl(1), as well as all man pages that include all of common-variables.xml, i.e. most of our command line tools. --- man/common-variables.xml | 73 ++++++++++++++++++++++++++++++++++++++++ man/systemctl.xml | 5 +++ 2 files changed, 78 insertions(+) diff --git a/man/common-variables.xml b/man/common-variables.xml index 809a9084a21..b875e38d394 100644 --- a/man/common-variables.xml +++ b/man/common-variables.xml @@ -7,6 +7,79 @@ Environment + + $SYSTEMD_LOG_LEVEL + + The maximum log level of emitted messages (messages with a higher log level, i.e. less + important ones, will be suppressed). Either one of (in order of decreasing importance) + emerg, alert, crit, + err, warning, notice, + info, debug, or an integer in the range 0…7. See + syslog3 + for more information. + + + + + $SYSTEMD_LOG_COLOR + + A boolean. If true, messages written to the tty will be colored according to + priority. + + This setting is only useful when messages are written directly to the terminal, because + journalctl1 and + other tools that display logs will color messages based on the log level on their own. + + + + + $SYSTEMD_LOG_TIME + + A boolean. If true, log messages will be prefixed with a timestamp. + + This setting is only useful when messages are written directly to the terminal or a file, because + journalctl1 and + other tools that display logs will attach timestamps based on the entry metadata on their own. + + + + + $SYSTEMD_LOG_LOCATION + + A boolean. If true, messages will be prefixed with a filename and line number + in the source code where the message originates. + + Note that the log location is often attached as metadata to journal entries anyway. Including it + directly in the message text can nevertheless be convenient when debugging programs. + + + + + $SYSTEMD_LOG_TID + + A boolean. If true, messages will be prefixed with the current numerical thread ID + (TID). + + Note that the this information is attached as metadata to journal entries anyway. Including it + directly in the message text can nevertheless be convenient when debugging programs. + + + + + $SYSTEMD_LOG_TARGET + + The destination for log messages. One of console (log to the + attached tty), console-prefixed (log to the attached tty but with prefixes + encoding the log level and "facility", see syslog3, + kmsg (log to the kernel circular log buffer), journal (log to + the journal), journal-or-kmsg (log to the journal if available, and to kmsg + otherwise), auto (dermine the appropriate log target automatically, the default), + null (disable log output). + + + + $SYSTEMD_PAGER diff --git a/man/systemctl.xml b/man/systemctl.xml index 62bc7fe832b..8402b9508a0 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -2407,6 +2407,11 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err + + + + + From 969524fae22517f31669d069f7aa7fb2a97235c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 13:30:07 +0100 Subject: [PATCH 06/18] basic/log: align tables --- src/basic/log.c | 16 ++++++------- src/basic/syslog-util.c | 52 ++++++++++++++++++++--------------------- 2 files changed, 34 insertions(+), 34 deletions(-) diff --git a/src/basic/log.c b/src/basic/log.c index b9817419ad9..c8cca96bca4 100644 --- a/src/basic/log.c +++ b/src/basic/log.c @@ -1310,15 +1310,15 @@ bool log_on_console(void) { } static const char *const log_target_table[_LOG_TARGET_MAX] = { - [LOG_TARGET_CONSOLE] = "console", + [LOG_TARGET_CONSOLE] = "console", [LOG_TARGET_CONSOLE_PREFIXED] = "console-prefixed", - [LOG_TARGET_KMSG] = "kmsg", - [LOG_TARGET_JOURNAL] = "journal", - [LOG_TARGET_JOURNAL_OR_KMSG] = "journal-or-kmsg", - [LOG_TARGET_SYSLOG] = "syslog", - [LOG_TARGET_SYSLOG_OR_KMSG] = "syslog-or-kmsg", - [LOG_TARGET_AUTO] = "auto", - [LOG_TARGET_NULL] = "null", + [LOG_TARGET_KMSG] = "kmsg", + [LOG_TARGET_JOURNAL] = "journal", + [LOG_TARGET_JOURNAL_OR_KMSG] = "journal-or-kmsg", + [LOG_TARGET_SYSLOG] = "syslog", + [LOG_TARGET_SYSLOG_OR_KMSG] = "syslog-or-kmsg", + [LOG_TARGET_AUTO] = "auto", + [LOG_TARGET_NULL] = "null", }; DEFINE_STRING_TABLE_LOOKUP(log_target, LogTarget); diff --git a/src/basic/syslog-util.c b/src/basic/syslog-util.c index 4eb9eba97c8..0371922e398 100644 --- a/src/basic/syslog-util.c +++ b/src/basic/syslog-util.c @@ -57,26 +57,26 @@ int syslog_parse_priority(const char **p, int *priority, bool with_facility) { } static const char *const log_facility_unshifted_table[LOG_NFACILITIES] = { - [LOG_FAC(LOG_KERN)] = "kern", - [LOG_FAC(LOG_USER)] = "user", - [LOG_FAC(LOG_MAIL)] = "mail", - [LOG_FAC(LOG_DAEMON)] = "daemon", - [LOG_FAC(LOG_AUTH)] = "auth", - [LOG_FAC(LOG_SYSLOG)] = "syslog", - [LOG_FAC(LOG_LPR)] = "lpr", - [LOG_FAC(LOG_NEWS)] = "news", - [LOG_FAC(LOG_UUCP)] = "uucp", - [LOG_FAC(LOG_CRON)] = "cron", + [LOG_FAC(LOG_KERN)] = "kern", + [LOG_FAC(LOG_USER)] = "user", + [LOG_FAC(LOG_MAIL)] = "mail", + [LOG_FAC(LOG_DAEMON)] = "daemon", + [LOG_FAC(LOG_AUTH)] = "auth", + [LOG_FAC(LOG_SYSLOG)] = "syslog", + [LOG_FAC(LOG_LPR)] = "lpr", + [LOG_FAC(LOG_NEWS)] = "news", + [LOG_FAC(LOG_UUCP)] = "uucp", + [LOG_FAC(LOG_CRON)] = "cron", [LOG_FAC(LOG_AUTHPRIV)] = "authpriv", - [LOG_FAC(LOG_FTP)] = "ftp", - [LOG_FAC(LOG_LOCAL0)] = "local0", - [LOG_FAC(LOG_LOCAL1)] = "local1", - [LOG_FAC(LOG_LOCAL2)] = "local2", - [LOG_FAC(LOG_LOCAL3)] = "local3", - [LOG_FAC(LOG_LOCAL4)] = "local4", - [LOG_FAC(LOG_LOCAL5)] = "local5", - [LOG_FAC(LOG_LOCAL6)] = "local6", - [LOG_FAC(LOG_LOCAL7)] = "local7" + [LOG_FAC(LOG_FTP)] = "ftp", + [LOG_FAC(LOG_LOCAL0)] = "local0", + [LOG_FAC(LOG_LOCAL1)] = "local1", + [LOG_FAC(LOG_LOCAL2)] = "local2", + [LOG_FAC(LOG_LOCAL3)] = "local3", + [LOG_FAC(LOG_LOCAL4)] = "local4", + [LOG_FAC(LOG_LOCAL5)] = "local5", + [LOG_FAC(LOG_LOCAL6)] = "local6", + [LOG_FAC(LOG_LOCAL7)] = "local7", }; DEFINE_STRING_TABLE_LOOKUP_WITH_FALLBACK(log_facility_unshifted, int, LOG_FAC(~0)); @@ -86,14 +86,14 @@ bool log_facility_unshifted_is_valid(int facility) { } static const char *const log_level_table[] = { - [LOG_EMERG] = "emerg", - [LOG_ALERT] = "alert", - [LOG_CRIT] = "crit", - [LOG_ERR] = "err", + [LOG_EMERG] = "emerg", + [LOG_ALERT] = "alert", + [LOG_CRIT] = "crit", + [LOG_ERR] = "err", [LOG_WARNING] = "warning", - [LOG_NOTICE] = "notice", - [LOG_INFO] = "info", - [LOG_DEBUG] = "debug" + [LOG_NOTICE] = "notice", + [LOG_INFO] = "info", + [LOG_DEBUG] = "debug", }; DEFINE_STRING_TABLE_LOOKUP_WITH_FALLBACK(log_level, int, LOG_DEBUG); From b4c87f7d381ad492cd8edfcc550bc85d03cc65ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 13:41:58 +0100 Subject: [PATCH 07/18] man: reuse common-variables in systemd(1) This requires a bit of gimnastics, but I think it's still better than status quo ante, and better than duplicating the text. --- man/common-variables.xml | 27 ++++++++++++++------------- man/systemd.xml | 40 ++++++++++++++++++++++------------------ 2 files changed, 36 insertions(+), 31 deletions(-) diff --git a/man/common-variables.xml b/man/common-variables.xml index b875e38d394..7798d977146 100644 --- a/man/common-variables.xml +++ b/man/common-variables.xml @@ -10,9 +10,9 @@ $SYSTEMD_LOG_LEVEL - The maximum log level of emitted messages (messages with a higher log level, i.e. less - important ones, will be suppressed). Either one of (in order of decreasing importance) - emerg, alert, crit, + The maximum log level of emitted messages (messages with a higher + log level, i.e. less important ones, will be suppressed). Either one of (in order of decreasing + importance) emerg, alert, crit, err, warning, notice, info, debug, or an integer in the range 0…7. See syslog3 @@ -23,8 +23,8 @@ $SYSTEMD_LOG_COLOR - A boolean. If true, messages written to the tty will be colored according to - priority. + A boolean. If true, messages written to the tty will be colored + according to priority. This setting is only useful when messages are written directly to the terminal, because journalctl1 and @@ -35,7 +35,8 @@ $SYSTEMD_LOG_TIME - A boolean. If true, log messages will be prefixed with a timestamp. + A boolean. If true, log messages will be prefixed with a + timestamp. This setting is only useful when messages are written directly to the terminal or a file, because journalctl1 and @@ -46,8 +47,8 @@ $SYSTEMD_LOG_LOCATION - A boolean. If true, messages will be prefixed with a filename and line number - in the source code where the message originates. + A boolean. If true, messages will be prefixed with a filename + and line number in the source code where the message originates. Note that the log location is often attached as metadata to journal entries anyway. Including it directly in the message text can nevertheless be convenient when debugging programs. @@ -57,8 +58,8 @@ $SYSTEMD_LOG_TID - A boolean. If true, messages will be prefixed with the current numerical thread ID - (TID). + A boolean. If true, messages will be prefixed with the current + numerical thread ID (TID). Note that the this information is attached as metadata to journal entries anyway. Including it directly in the message text can nevertheless be convenient when debugging programs. @@ -68,9 +69,9 @@ $SYSTEMD_LOG_TARGET - The destination for log messages. One of console (log to the - attached tty), console-prefixed (log to the attached tty but with prefixes - encoding the log level and "facility", see The destination for log messages. One of + console (log to the attached tty), console-prefixed (log to + the attached tty but with prefixes encoding the log level and "facility", see syslog3, kmsg (log to the kernel circular log buffer), journal (log to the journal), journal-or-kmsg (log to the journal if available, and to kmsg diff --git a/man/systemd.xml b/man/systemd.xml index b0b6c7236e2..504c82b25ee 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -629,39 +629,43 @@ - $SYSTEMD_LOG_COLOR - Controls whether systemd highlights important log messages. This can be overridden - with . + $SYSTEMD_LOG_LEVEL + + + This can be overridden with . - $SYSTEMD_LOG_LEVEL - systemd reads the log level from this environment variable. This can be overridden - with . + $SYSTEMD_LOG_COLOR + + + This can be overridden with . - $SYSTEMD_LOG_LOCATION - Controls whether systemd prints the code location along with log messages. This can - be overridden with . + $SYSTEMD_LOG_TIME + + + This can be overridden with . - $SYSTEMD_LOG_TARGET - systemd reads the log target from this environment variable. This can be overridden - with . + $SYSTEMD_LOG_LOCATION + + + This can be overridden with . - $SYSTEMD_LOG_TIME - Controls whether systemd prefixes log messages with the current time. This can be - overridden with . + $SYSTEMD_LOG_TID + - $SYSTEMD_LOG_TID - Controls whether systemd prefixes log messages with the current thread ID - (TID). + $SYSTEMD_LOG_TARGET + + + This can be overridden with . From 09d90814473bc88514d874f816ab5550f07d488a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 13:43:57 +0100 Subject: [PATCH 08/18] man: move description of $SYSTEMD_SYSVINIT_PATH to the only user --- man/systemd-sysv-generator.xml | 14 ++++++++++++++ man/systemd.xml | 7 ------- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/man/systemd-sysv-generator.xml b/man/systemd-sysv-generator.xml index 14ab932fedb..aafd3321325 100644 --- a/man/systemd-sysv-generator.xml +++ b/man/systemd-sysv-generator.xml @@ -60,6 +60,20 @@ systemd.generator7. + + Environment + + Special variables understood by systemd-sysv-generator: + + + + $SYSTEMD_SYSVINIT_PATH + + Controls where systemd looks for SysV init scripts. + + + + See Also diff --git a/man/systemd.xml b/man/systemd.xml index 504c82b25ee..27f0a7517d4 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -696,13 +696,6 @@ - - $SYSTEMD_SYSVINIT_PATH - - Controls where systemd looks for SysV init - scripts. - - $SYSTEMD_SYSVRCND_PATH From fc070a25742a2a0aa407a1ce0637db505e204c1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 14:12:12 +0100 Subject: [PATCH 09/18] man: describe the syntax for {Job,}{Running,}TimeoutSec= Fixes #16644. Also break the text into paragraphs to make it a bit easier to read. --- man/systemd.unit.xml | 94 +++++++++++++++++++++++++----------------- man/timesyncd.conf.xml | 9 ++-- 2 files changed, 62 insertions(+), 41 deletions(-) diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 0453c783b6d..0441e4152dd 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -976,16 +976,24 @@ JobTimeoutSec= JobRunningTimeoutSec= - When a job for this unit is queued, a timeout JobTimeoutSec= may be - configured. Similarly, JobRunningTimeoutSec= starts counting when the queued job is actually - started. If either time limit is reached, the job will be cancelled, the unit however will not change state or - even enter the failed mode. This value defaults to infinity (job timeouts - disabled), except for device units (JobRunningTimeoutSec= defaults to - DefaultTimeoutStartSec=). NB: this timeout is independent from any unit-specific timeout - (for example, the timeout set with TimeoutStartSec= in service units) as the job timeout has - no effect on the unit itself, only on the job that might be pending for it. Or in other words: unit-specific - timeouts are useful to abort unit state changes, and revert them. The job timeout set with this option however - is useful to abort only the job waiting for the unit state to change. + JobTimeoutSec= specifies a timeout for the whole job that starts + running when the job is queued. JobRunningTimeoutSec= specifies a timeout that + starts running when the queued job is actually started. If either limit is reached, the job will be + cancelled, the unit however will not change state or even enter the failed mode. + + + Both settings take a time span with the default unit of seconds, but other units may be + specified, see + systemd.time5. + The default is infinity (job timeouts disabled), except for device units where + JobRunningTimeoutSec= defaults to DefaultTimeoutStartSec=. + + + Note: these timeouts are independent from any unit-specific timeouts (for example, the timeout + set with TimeoutStartSec= in service units). The job timeout has no effect on the + unit itself. Or in other words: unit-specific timeouts are useful to abort unit state changes, and + revert them. The job timeout set with this option however is useful to abort only the job waiting for + the unit state to change. @@ -993,13 +1001,14 @@ JobTimeoutAction= JobTimeoutRebootArgument= - JobTimeoutAction= optionally configures an additional action to take when - the timeout is hit, see description of JobTimeoutSec= and + JobTimeoutAction= optionally configures an additional action to + take when the timeout is hit, see description of JobTimeoutSec= and JobRunningTimeoutSec= above. It takes the same values as - StartLimitAction=. Defaults to . - JobTimeoutRebootArgument= configures an optional reboot string to pass to the - reboot2 system call. - + StartLimitAction=. Defaults to . + + JobTimeoutRebootArgument= configures an optional reboot string to pass to + the reboot2 system + call. @@ -1007,28 +1016,39 @@ StartLimitBurst=burst Configure unit start rate limiting. Units which are started more than - burst times within an interval time interval are not - permitted to start any more. Use StartLimitIntervalSec= to configure the checking interval - (defaults to DefaultStartLimitIntervalSec= in manager configuration file, set it to 0 to - disable any kind of rate limiting). Use StartLimitBurst= to configure how many starts per - interval are allowed (defaults to DefaultStartLimitBurst= in manager configuration - file). These configuration options are particularly useful in conjunction with the service setting + burst times within an interval time span are + not permitted to start any more. Use StartLimitIntervalSec= to configure the + checking interval and StartLimitBurst= to configure how many starts per interval + are allowed. + + interval is a time span with the default unit of seconds, but other + units may be specified, see + systemd.time5. + Defaults to DefaultStartLimitIntervalSec= in manager configuration file, and may + be set to 0 to disable any kind of rate limiting. burst is a number and + defaults to DefaultStartLimitBurst= in manager configuration file. + + These configuration options are particularly useful in conjunction with the service setting Restart= (see - systemd.service5); however, - they apply to all kinds of starts (including manual), not just those triggered by the - Restart= logic. Note that units which are configured for Restart= and - which reach the start limit are not attempted to be restarted anymore; however, they may still be restarted - manually at a later point, after the interval has passed. From this point on, the - restart logic is activated again. Note that systemctl reset-failed will cause the restart - rate counter for a service to be flushed, which is useful if the administrator wants to manually start a unit - and the start limit interferes with that. Note that this rate-limiting is enforced after any unit condition - checks are executed, and hence unit activations with failing conditions do not count towards this rate - limit. This setting does not apply to slice, target, device, and scope units, since they are unit types whose - activation may either never fail, or may succeed only a single time. - - When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters are - flushed out too. This means that configuring start rate limiting for a unit that is not referenced continuously - has no effect. + systemd.service5); + however, they apply to all kinds of starts (including manual), not just those triggered by the + Restart= logic. + + Note that units which are configured for Restart=, and which reach the start + limit are not attempted to be restarted anymore; however, they may still be restarted manually at a + later point, after the interval has passed. From that point on, the + restart logic is activated again. systemctl reset-failed will cause the restart + rate counter for a service to be flushed, which is useful if the administrator wants to manually + start a unit and the start limit interferes with that. Rate-limiting is enforced after any unit + condition checks are executed, and hence unit activations with failing conditions do not count + towards the rate limit. + + When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters + are flushed out too. This means that configuring start rate limiting for a unit that is not + referenced continuously has no effect. + + This setting does not apply to slice, target, device, and scope units, since they are unit + types whose activation may either never fail, or may succeed only a single time. diff --git a/man/timesyncd.conf.xml b/man/timesyncd.conf.xml index 9554cbb378d..3fd11cea04c 100644 --- a/man/timesyncd.conf.xml +++ b/man/timesyncd.conf.xml @@ -73,7 +73,7 @@ the current server does not satisfy this limit, systemd-timesyncd will switch to a different server. - Takes a time value. The default unit is seconds, but other units may be specified, see + Takes a time span value. The default unit is seconds, but other units may be specified, see systemd.time5. Defaults to 5 seconds. @@ -85,8 +85,9 @@ minimum poll interval, and is adjusted within the specified limits in response to received packets. - Each setting takes a time value. The default unit is seconds, but other units may be specified, - see systemd.time5. + Each setting takes a time span value. The default unit is seconds, but other units may be + specified, see + systemd.time5. PollIntervalMinSec= defaults to 32 seconds and must not be smaller than 16 seconds. PollIntervalMaxSec= defaults to 34 min 8 s (2048 seconds) and must be larger than PollIntervalMinSec=. @@ -97,7 +98,7 @@ Specifies the minimum delay before subsequent attempts to contact a new NTP server are made. - Takes a time value. The default unit is seconds, but other units may be specified, see + Takes a time span value. The default unit is seconds, but other units may be specified, see systemd.time5. Defaults to 30 seconds and must not be smaller than 1 second. From 9273d8e6c9363f82ce4f8120879a021b0176fb30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 17:12:38 +0100 Subject: [PATCH 10/18] man: move motivational explanation to footnote --- man/systemd-resolved.service.xml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index 0ff2b4e8553..e6bfdf938ba 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -246,13 +246,13 @@ has failed, as absolute, while other names would be resolved in opposite order. The ndots option in /etc/resolv.conf was used to control how many dots the name needs to have to be resolved as relative first. This stub resolver does not implement - this at all: multi-label names are only resolved as FQDNs. (There are currently more than 1500 - top-level domain names defined, and new ones are added regularly, often using "attractive" names that - are also likely to be used locally. Not looking up multi-label names in this fashion avoids fragility - in both directions: a valid global name could be obscured by a local name, and resolution of a relative - local name could suddenly break when a new top-level domain is created, or when a new subdomain of a - top-level domain in registered. Resolving any given name as either relative or absolute avoids this - ambiguity.) + this at all: multi-label names are only resolved as FQDNs.There are currently more than + 1500 top-level domain names defined, and new ones are added regularly, often using "attractive" names + that are also likely to be used locally. Not looking up multi-label names in this fashion avoids + fragility in both directions: a valid global name could be obscured by a local name, and resolution of + a relative local name could suddenly break when a new top-level domain is created, or when a new + subdomain of a top-level domain in registered. Resolving any given name as either relative or absolute + avoids this ambiguity.) This resolver has a notion of the special .local domain used for MulticastDNS, and will not route queries with that suffix to unicast DNS servers unless explicitly From 32f82ccceae7b955cfa1e1ce8643df0735cc9e20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 17:36:00 +0100 Subject: [PATCH 11/18] man: add footnote explaining why "localhost" query is sent out to the network I tried to make the explanation brief, but this isn't so easy. It seems better to push this out to a footnote instead of the main text. Fixes #16584. --- man/systemd-resolved.service.xml | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index e6bfdf938ba..ed6214cd625 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -115,8 +115,8 @@ Protocols and Routing - Lookup requests are routed to the available DNS servers, LLMNR, and MulticastDNS interfaces - according to the following rules: + The lookup requests that systemd-resolved.service receives are routed to the + available DNS servers, LLMNR, and MulticastDNS interfaces according to the following rules: Names for which synthetic records are generated (the local hostname, @@ -172,7 +172,8 @@ resolved.conf5 for a description of globally configured DNS settings. - The following query routing logic applies for unicast DNS traffic: + The following query routing logic applies for unicast DNS lookups initiated by + systemd-resolved.service: If a name to look up matches (that is: is equal to or has as suffix) any of the @@ -228,8 +229,22 @@ Some names are always resolved internally (see Synthetic Records above). Traditionally - they would be resolved by nss-files, and only if provided in - /etc/hosts. + they would be resolved by nss-files if provided in + /etc/hosts. But note that the details of how a query is constructed are under the + control of the client library. nss-dns will first try to resolve names using + search domains and even if those queries are routed to systemd-resolved, it will + send them out over the network using the usual rules for multi-label name routing For + example, if /etc/nsswitch.conf has nameserver 127.0.0.53 +search foobar.com barbar.com + and we look up localhost, nss-dns will send + the following queries to systemd-resolved listening on 127.0.0.53:53: first + localhost.foobar.com, then localhost.barbar.com, and finally + localhost. If (hopefully) the first two queries fail, + systemd-resolved will synthesize an answer for the third query. + + When using nss-dns with any search domains, it is thus crucial to always + configure nss-files with higher priority and provide mappings for names that + should not be resolved using search domains.. Single-label names are not resolved for A and AAAA records using unicast DNS (unless overridden with ResolveUnicastSingleLabel=, see From 9479d92ebc487af66d29b716a347bf2f2620e3dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 17:45:06 +0100 Subject: [PATCH 12/18] man: reorder match types in udev rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The plural version should always be adjacent to the singular one. And the plural should not be explained before the singular one… --- man/udev.xml | 66 ++++++++++++++++++++++++++++------------------------ 1 file changed, 35 insertions(+), 31 deletions(-) diff --git a/man/udev.xml b/man/udev.xml index 1e9b92c524d..c1166b55008 100644 --- a/man/udev.xml +++ b/man/udev.xml @@ -166,6 +166,13 @@ + + KERNELS + + Search the devpath upwards for a matching device name. + + + NAME @@ -190,65 +197,55 @@ Match the subsystem of the event device. + - DRIVER - - Match the driver name of the event device. Only set this key for devices - which are bound to a driver at the time the event is generated. - - - - ATTR{filename} - - Match sysfs attribute values of the event device. Trailing - whitespace in the attribute values is ignored unless the specified match - value itself contains trailing whitespace. - - - - - SYSCTL{kernel parameter} + SUBSYSTEMS - Match a kernel parameter value. - + Search the devpath upwards for a matching device subsystem name. - KERNELS + DRIVER - Search the devpath upwards for a matching device name. + Match the driver name of the event device. Only set this key for devices + which are bound to a driver at the time the event is generated. - SUBSYSTEMS + DRIVERS - Search the devpath upwards for a matching device subsystem name. + Search the devpath upwards for a matching device driver name. - DRIVERS + ATTR{filename} - Search the devpath upwards for a matching device driver name. + Match sysfs attribute value of the event device. + + Trailing whitespace in the attribute values is ignored unless the specified match value + itself contains trailing whitespace. ATTRS{filename} - Search the devpath upwards for a device with matching sysfs attribute values. - If multiple ATTRS matches are specified, all of them - must match on the same device. Trailing whitespace in the attribute values is ignored - unless the specified match value itself contains trailing whitespace. + Search the devpath upwards for a device with matching sysfs attribute values. If + multiple ATTRS matches are specified, all of them must match on the same + device. + + Trailing whitespace in the attribute values is ignored unless the specified match value + itself contains trailing whitespace. - TAGS + SYSCTL{kernel parameter} - Search the devpath upwards for a device with matching tag. + Match a kernel parameter value. @@ -292,6 +289,13 @@ + + TAGS + + Search the devpath upwards for a device with matching tag. + + + TEST{octal mode mask} From 5929b6b52281c9c89d62fba525cda54b8958625d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 17:54:05 +0100 Subject: [PATCH 13/18] man: mention that != matches nonexistent keys too Fixes #15984. --- man/udev.xml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/man/udev.xml b/man/udev.xml index c1166b55008..8782bb15c54 100644 --- a/man/udev.xml +++ b/man/udev.xml @@ -79,14 +79,16 @@ == - Compare for equality. + Compare for equality. (The specified key has the specified value.) != - Compare for inequality. + Compare for inequality. (The specified key doesn't have the specified value, or the + specified key is not present at all.) + From 36f57e02d768d006c7b610e1f99cda87e115f6a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 18:08:53 +0100 Subject: [PATCH 14/18] man: explain how to invoke tmpfiles for debugging Fixes #11914. --- TODO | 1 + man/systemd-tmpfiles.xml | 21 +++++++++++++++++++++ 2 files changed, 22 insertions(+) diff --git a/TODO b/TODO index f82ca75231d..926c3c8ae7f 100644 --- a/TODO +++ b/TODO @@ -1272,6 +1272,7 @@ Features: - creating new directories/subvolumes/fifos/device nodes should not follow symlinks. None of the other adjustment or creation calls follow symlinks. + - add --test mode * make sure systemd-ask-password-wall does not shutdown systemd-ask-password-console too early diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml index 90c2626685e..bd93474d407 100644 --- a/man/systemd-tmpfiles.xml +++ b/man/systemd-tmpfiles.xml @@ -81,6 +81,9 @@ system instance, such as the one typically configured for /tmp/, will thus also affect files created by the user instance if they are placed in /tmp/, even if the user instance's time-based cleanup is turned off. + + To debug systemd-tmpfiles, it may be useful to invoke it directly from the + command line with increased log level (see $SYSTEMD_LOG_LEVEL below). @@ -227,6 +230,24 @@ systemd-tmpfiles --remove --create + + Environment + + + + + + + + + + + + + + + + Unprivileged --cleanup operation From 4d729e3796e2c48e6840b86a1474d8009d8d940d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 18:36:00 +0100 Subject: [PATCH 15/18] man: move quoting description to systemd.syntax We use very similar quoting rules in many places. Let's move this lengthy text out of systemd.service page. --- man/systemd.service.xml | 98 +++++------------------------------------ man/systemd.syntax.xml | 90 +++++++++++++++++++++++++++++++++++-- 2 files changed, 96 insertions(+), 92 deletions(-) diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 0e9fa3e7323..501da54b8aa 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1107,11 +1107,9 @@ Check - systemd.exec5 - and - systemd.kill5 - for more settings. - + systemd.exec5 and + systemd.kill5 for more + settings. @@ -1126,21 +1124,13 @@ ExecStop=, and ExecStopPost= options. - Multiple command lines may be concatenated in a single - directive by separating them with semicolons (these semicolons - must be passed as separate words). Lone semicolons may be escaped - as \;. - - Each command line is split on whitespace, with the first item being the command to - execute, and the subsequent items being the arguments. Double quotes ("…") and single quotes - ('…') may be used to wrap a whole item (the opening quote may appear only at the beginning or - after whitespace that is not quoted, and the closing quote must be followed by whitespace or the - end of line), in which case everything until the next matching quote becomes part of the same - argument. Quotes themselves are removed. C-style escapes are also supported. The table below - contains the list of known escape patterns. Only escape patterns which match the syntax in the - table are allowed; other patterns may be added in the future and unknown patterns will result in - a warning. In particular, any backslashes should be doubled. Finally, a trailing backslash - (\) may be used to merge lines. + Multiple command lines may be concatenated in a single directive by separating them with semicolons + (these semicolons must be passed as separate words). Lone semicolons may be escaped as + \;. + + Each command line is unquoted using the rules described in "Quoting" section in + systemd.syntax5. The + first item becomes the command to execute, and the subsequent items the arguments. This syntax is inspired by shell syntax, but only the meta-characters and expansions described in the following paragraphs are understood, and the expansion of variables is @@ -1240,74 +1230,6 @@ ls >/dev/null, &, ;, and ls. - - - C escapes supported in command lines and environment variables - - - - - - Literal - Actual value - - - - - \a - bell - - - \b - backspace - - - \f - form feed - - - \n - newline - - - \r - carriage return - - - \t - tab - - - \v - vertical tab - - - \\ - backslash - - - \" - double quotation mark - - - \' - single quotation mark - - - \s - space - - - \xxx - character number xx in hexadecimal encoding - - - \nnn - character number nnn in octal encoding - - - -
diff --git a/man/systemd.syntax.xml b/man/systemd.syntax.xml index 7960adb6597..5f207912b95 100644 --- a/man/systemd.syntax.xml +++ b/man/systemd.syntax.xml @@ -74,10 +74,10 @@ .ini files. - Each file is a plain text file divided into sections, with configuration entries in the - style key=value. - Whitespace immediately before or after the = is ignored. Empty lines and lines starting with # or ; are - ignored, which may be used for commenting. + Each file is a plain text file divided into sections, with configuration entries in the style + key=value. Whitespace immediately before or after + the = is ignored. Empty lines and lines starting with # or + ; are ignored, which 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. The limit on @@ -129,6 +129,88 @@ KeyThree=value 3\ file format. + + Quoting + + For settings where quoting is allowed, the following general rules apply: double quotes ("…") and + single quotes ('…') may be used to wrap a whole item (the opening quote may appear only at the beginning + or after whitespace that is not quoted, and the closing quote must be followed by whitespace or the end + of line), in which case everything until the next matching quote becomes part of the same item. Quotes + themselves are removed. C-style escapes are also supported. The table below contains the list of known + escape patterns. Only escape patterns which match the syntax in the table are allowed; other patterns may + be added in the future and unknown patterns will result in a warning. In particular, any backslashes + should be doubled. Finally, a trailing backslash (\) may be used to merge lines, as + described above. + + + Supported C escapes + + + + + + Literal + Actual value + + + + + \a + bell + + + \b + backspace + + + \f + form feed + + + \n + newline + + + \r + carriage return + + + \t + tab + + + \v + vertical tab + + + \\ + backslash + + + \" + double quotation mark + + + \' + single quotation mark + + + \s + space + + + \xxx + character number xx in hexadecimal encoding + + + \nnn + character number nnn in octal encoding + + + +
+ + See Also From e531091ba0b0f3c69006cad48a2081f235a5bb1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 18:37:01 +0100 Subject: [PATCH 16/18] man: describe quoting and specifiers in Environment= Fixes #10604. --- man/systemd.exec.xml | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index bac8f9cdff9..30e64224c3e 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -2263,18 +2263,24 @@ SystemCallErrorNumber=EPERM Environment= - Sets environment variables for executed processes. Takes a space-separated list of - variable assignments. This option may be specified more than once, in which case all listed variables - will be set. If the same variable is set twice, the later setting will override the earlier - setting. If the empty string is assigned to this option, the list of environment variables is reset, - all prior assignments have no effect. Variable expansion is not performed inside the strings, - however, specifier expansion is possible. The $ character has no special - meaning. If you need to assign a value containing spaces or the equals sign to a variable, use double - quotes (") for the assignment. - - The names of the variables can contain ASCII letters, digits, and the underscore - character. Variable names cannot be empty or start with a digit. In variable values, most characters - are allowed, but non-printable characters are currently rejected. + Sets environment variables for executed processes. Each line is unquoted using the + rules described in "Quoting" section in + systemd.syntax5 + and becomes a list of variable assignments. If you need to assign a value containing spaces or the + equals sign to a variable, put quotes around the whole assignment. Variable expansion is not + performed inside the strings and the $ character has no special meaning. Specifier + expansion is performed, see the "Specifiers" section in + systemd.unit5. + + + This option may be specified more than once, in which case all listed variables will be set. If + the same variable is listed twice, the later setting will override the earlier setting. If the empty + string is assigned to this option, the list of environment variables is reset, all prior assignments + have no effect. + + The names of the variables can contain ASCII letters, digits, and the underscore character. + Variable names cannot be empty or start with a digit. In variable values, most characters are + allowed, but non-printable characters are currently rejected. Example: Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6" @@ -2284,10 +2290,9 @@ SystemCallErrorNumber=EPERM word3, $word 5 6. - - See environ7 for details - about environment variables. + See environ7 for + details about environment variables. Note that environment variables are not suitable for passing secrets (such as passwords, key material, …) to service processes. Environment variables set for a unit are exposed to unprivileged From aa2e348d7b8adf9735a45af942a39233d3248d41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 20:44:25 +0100 Subject: [PATCH 17/18] man: tweak descriptions of how tmpfiles should be started We shouldn't imply that invocation without any parameters is OK. Also, mention that the service can be restarted. Fixes #8684. --- man/systemd-tmpfiles.xml | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml index bd93474d407..5f97e37025f 100644 --- a/man/systemd-tmpfiles.xml +++ b/man/systemd-tmpfiles.xml @@ -48,23 +48,20 @@ Description - systemd-tmpfiles creates, deletes, and - cleans up volatile and temporary files and directories, based on - the configuration file format and location specified in - tmpfiles.d5. - - - If invoked with no arguments, it applies all directives from all configuration - files. When invoked with , - arguments specified on the command line are used instead of the configuration file - PATH. Otherwise, if one or more absolute filenames are - passed on the command line, only the directives in these files are applied. If - - is specified instead of a filename, directives are read from - standard input. If only the basename of a configuration file is specified, all - configuration directories as specified in - tmpfiles.d5 - are searched for a matching file and the file found that has the highest priority is - executed. + systemd-tmpfiles creates, deletes, and cleans up volatile and temporary files + and directories, using the configuration file format and location specified in + tmpfiles.d5. It must + be invoked with one or more options , , and + , to select the respective subset of operations. + + By default, directives from all configuration files are applied. When invoked with + , arguments specified on the command line are + used instead of the configuration file PATH. Otherwise, if one or more + absolute filenames are passed on the command line, only the directives in these files are applied. If + - is specified instead of a filename, directives are read from standard input. If only + the basename of a configuration file is specified, all configuration directories as specified in + tmpfiles.d5 are + searched for a matching file and the file found that has the highest priority is executed. System services (systemd-tmpfiles-setup.service, systemd-tmpfiles-setup-dev.service, @@ -82,8 +79,11 @@ affect files created by the user instance if they are placed in /tmp/, even if the user instance's time-based cleanup is turned off. - To debug systemd-tmpfiles, it may be useful to invoke it directly from the - command line with increased log level (see $SYSTEMD_LOG_LEVEL below). + To re-apply settings after configuration has been modified, simply restart + systemd-tmpfiles-clean.service, which will apply any settings which can be safely + executed at runtime. To debug systemd-tmpfiles, it may be useful to invoke it + directly from the command line with increased log level (see $SYSTEMD_LOG_LEVEL + below). From dac05c080882baa2cca4144db70f34f1d77fddaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 1 Mar 2021 10:08:28 +0100 Subject: [PATCH 18/18] man: say that machine-info doesn't have to exist Esp. CHASSIS is only useful as an override. Make that clear in the description. Fixes #3496. --- man/machine-info.xml | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/man/machine-info.xml b/man/machine-info.xml index c42f6e22113..3de68100470 100644 --- a/man/machine-info.xml +++ b/man/machine-info.xml @@ -37,12 +37,10 @@ file without implementing a shell compatible execution engine. - /etc/machine-info contains metadata - about the machine that is set by the user or administrator. - - Depending on the operating system other configuration files - might be checked for machine information as well, however only as - fallback. + /etc/machine-info contains metadata about the machine that is set by the user + or administrator. The settings configured here have the highest precedence. When not set, appropriate + values may be determined automatically, based on the information about the hardware or other + configuration files. It is thus completely fine for this file to not be present. You may use hostnamectl1 @@ -102,13 +100,11 @@ as well as the special chassis types vm and container for - virtualized systems that lack an immediate physical chassis. - Note that many systems allow detection of the chassis type - automatically (based on firmware information or suchlike). - This setting (if set) shall take precedence over automatically - detected information and is useful to override misdetected - configuration or to manually configure the chassis type where - automatic detection is not available. + virtualized systems that lack an immediate physical chassis. + + Note that most systems allow detection of the chassis type automatically (based on firmware + information or suchlike). This setting should only be used to override a misdetection or to manually + configure the chassis type where automatic detection is not available.