diff --git a/TODO b/TODO index 7ff15d3b8fa..87a92af8061 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/less-variables.xml b/man/common-variables.xml similarity index 64% rename from man/less-variables.xml rename to man/common-variables.xml index 809a9084a21..7798d977146 100644 --- a/man/less-variables.xml +++ b/man/common-variables.xml @@ -7,6 +7,80 @@ 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/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/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/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. 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..8402b9508a0 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -2407,12 +2407,17 @@ 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-coredump.xml b/man/systemd-coredump.xml index f92cfd55ea7..aea1cf861fa 100644 --- a/man/systemd-coredump.xml +++ b/man/systemd-coredump.xml @@ -32,29 +32,12 @@ 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. 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 @@ -62,14 +45,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,22 +134,241 @@ 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. - 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" +… + + 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-resolved.service.xml b/man/systemd-resolved.service.xml index 0ff2b4e8553..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 @@ -246,13 +261,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 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-tmpfiles.xml b/man/systemd-tmpfiles.xml index 90c2626685e..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. - + 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. - 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. + 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, @@ -81,6 +78,12 @@ 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 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). @@ -227,6 +230,24 @@ systemd-tmpfiles --remove --create + + Environment + + + + + + + + + + + + + + + + Unprivileged --cleanup operation 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. + 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. + - 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. + 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 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 \;. + 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. + 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 diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 0850bdda743..6a9d4dc486d 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 - 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. + 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. - 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. + 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 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/systemd.xml b/man/systemd.xml index 893f113431e..27f0a7517d4 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -628,40 +628,44 @@ Some of the variables understood by systemd: - - $SYSTEMD_LOG_COLOR - Controls whether systemd highlights important log messages. This can be overridden - with . - - $SYSTEMD_LOG_LEVEL - systemd reads the log level from this environment variable. This can be overridden - with . + + + 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_COLOR + - - $SYSTEMD_LOG_TARGET - systemd reads the log target from this environment variable. This can be overridden - with . + This can be overridden with . $SYSTEMD_LOG_TIME - Controls whether systemd prefixes log messages with the current time. This can be - overridden with . + + + This can be overridden with . + + + + $SYSTEMD_LOG_LOCATION + + + This can be overridden with . $SYSTEMD_LOG_TID - Controls whether systemd prefixes log messages with the current thread ID - (TID). + + + + + $SYSTEMD_LOG_TARGET + + + This can be overridden with . @@ -692,13 +696,6 @@ - - $SYSTEMD_SYSVINIT_PATH - - Controls where systemd looks for SysV init - scripts. - - $SYSTEMD_SYSVRCND_PATH @@ -706,12 +703,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/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. diff --git a/man/udev.xml b/man/udev.xml index 1e9b92c524d..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.) + @@ -166,6 +168,13 @@ + + KERNELS + + Search the devpath upwards for a matching device name. + + + NAME @@ -190,36 +199,6 @@ 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} - - Match a kernel parameter value. - - - - - - KERNELS - - Search the devpath upwards for a matching device name. - - SUBSYSTEMS @@ -228,6 +207,14 @@ + + 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. + + + DRIVERS @@ -236,19 +223,31 @@ - ATTRS{filename} + ATTR{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. + 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. - TAGS + ATTRS{filename} - Search the devpath upwards for a device with matching tag. + 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. + + + + + SYSCTL{kernel parameter} + + Match a kernel parameter value. @@ -292,6 +291,13 @@ + + TAGS + + Search the devpath upwards for a device with matching tag. + + + TEST{octal mode mask} 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 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); 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;