From af2a7ac568af7b8ecf1002023dd9d07135c3c9c2 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 25 Apr 2024 04:54:54 +0200 Subject: Merging upstream version 255.5. Signed-off-by: Daniel Baumann --- man/common-variables.xml | 8 +- man/crypttab.xml | 4 +- man/custom-entities.ent.in | 2 +- man/custom-html.xsl | 6 +- man/daemon.xml | 4 +- man/event-quick-child.c | 2 +- man/hwdb-usb-device.c | 6 +- man/journalctl.xml | 2 +- man/kernel-command-line.xml | 22 ++++ man/notify-selfcontained-example.c | 173 +++++++++++++++++++++++++++++ man/org.freedesktop.resolve1.xml | 39 +++++-- man/path-documents.c | 2 +- man/portablectl.xml | 6 +- man/repart.d.xml | 4 +- man/sd_bus_error-example.c | 2 +- man/sd_event_add_io.xml | 24 ++-- man/sd_journal_get_cursor.xml | 15 +-- man/sd_journal_seek_head.xml | 10 +- man/sd_notify.xml | 5 + man/systemctl.xml | 68 +++++++----- man/systemd-bless-boot.service.xml | 2 +- man/systemd-bsod.service.xml | 2 +- man/systemd-cryptsetup.xml | 2 +- man/systemd-hibernate-resume-generator.xml | 11 +- man/systemd-hibernate-resume.service.xml | 2 +- man/systemd-journald.service.xml | 18 +++ man/systemd-nspawn.xml | 2 +- man/systemd-pcrlock.xml | 4 +- man/systemd-poweroff.service.xml | 2 +- man/systemd-repart.xml | 2 +- man/systemd-socket-proxyd.xml | 5 + man/systemd-soft-reboot.service.xml | 2 +- man/systemd-storagetm.service.xml | 2 +- man/systemd-sysext.xml | 2 +- man/systemd-timedated.service.xml | 4 +- man/systemd-tpm2-setup.service.xml | 2 +- man/systemd-vmspawn.xml | 4 +- man/systemd.exec.xml | 29 +++-- man/systemd.network.xml | 12 +- man/systemd.pcrlock.xml | 10 +- man/systemd.resource-control.xml | 16 ++- man/systemd.service.xml | 14 ++- man/systemd.socket.xml | 2 +- man/ukify.xml | 10 +- man/varlinkctl.xml | 8 +- 45 files changed, 439 insertions(+), 134 deletions(-) create mode 100644 man/notify-selfcontained-example.c (limited to 'man') diff --git a/man/common-variables.xml b/man/common-variables.xml index 81425e5..1aa31e1 100644 --- a/man/common-variables.xml +++ b/man/common-variables.xml @@ -137,6 +137,9 @@ + Note that setting the regular $LESS environment variable has no effect + for less invocations by systemd tools. + See less1 for more discussion. @@ -146,7 +149,10 @@ $SYSTEMD_LESSCHARSET Override the charset passed to less (by default utf-8, if - the invoking terminal is determined to be UTF-8 compatible). + the invoking terminal is determined to be UTF-8 compatible). + + Note that setting the regular $LESSCHARSET environment variable has no effect + for less invocations by systemd tools. diff --git a/man/crypttab.xml b/man/crypttab.xml index e94bf1c..126d3a0 100644 --- a/man/crypttab.xml +++ b/man/crypttab.xml @@ -126,7 +126,7 @@ For the latter five mechanisms the source for the key material used for unlocking the volume is primarily configured in the third field of each /etc/crypttab line, but may also - configured in /etc/cryptsetup-keys.d/ and + be configured in /etc/cryptsetup-keys.d/ and /run/cryptsetup-keys.d/ (see above) or in the LUKS2 JSON token header (in case of the latter three). Use the systemd-cryptenroll1 @@ -923,7 +923,7 @@ is acquired by connecting to the socket and reading the key from the connection. The connection is made from an AF_UNIX socket name in the abstract namespace, see unix7 for - details. The source socket name is chosen according the following format: + details. The source socket name is chosen according to the following format: NUL RANDOM /cryptsetup/ VOLUME diff --git a/man/custom-entities.ent.in b/man/custom-entities.ent.in index a854d11..9513235 100644 --- a/man/custom-entities.ent.in +++ b/man/custom-entities.ent.in @@ -18,5 +18,5 @@ - + diff --git a/man/custom-html.xsl b/man/custom-html.xsl index 8b21e15..2373bc3 100644 --- a/man/custom-html.xsl +++ b/man/custom-html.xsl @@ -81,13 +81,11 @@ - https://www.archlinux.org/ - - / + https://man.archlinux.org/man/ . - .html + .en.html diff --git a/man/daemon.xml b/man/daemon.xml index 8fa2506..819ff9b 100644 --- a/man/daemon.xml +++ b/man/daemon.xml @@ -75,7 +75,7 @@ create an independent session. In the child, call fork() again, to ensure that the daemon can - never re-acquire a terminal again. (This relevant if the program — and all its dependencies — does + never re-acquire a terminal again. (This is relevant if the program — and all its dependencies — does not carefully specify `O_NOCTTY` on each and every single `open()` call that might potentially open a TTY device node.) @@ -228,7 +228,7 @@ If the service opens sockets or other files on it own, and those file descriptors shall survive a restart, the daemon should store them in the service manager via sd_notify3 with - FDSTORE=1.. + FDSTORE=1. Instead of using the syslog() call to log directly to the system syslog service, a new-style daemon may choose to simply log to standard error via diff --git a/man/event-quick-child.c b/man/event-quick-child.c index 8195efb..b95ee1b 100644 --- a/man/event-quick-child.c +++ b/man/event-quick-child.c @@ -3,7 +3,7 @@ #include #include #include -#include +#include int main(int argc, char **argv) { pid_t pid = fork(); diff --git a/man/hwdb-usb-device.c b/man/hwdb-usb-device.c index 19a5db8..facd8c4 100644 --- a/man/hwdb-usb-device.c +++ b/man/hwdb-usb-device.c @@ -2,16 +2,16 @@ #include #include -#include +#include int print_usb_properties(uint16_t vid, uint16_t pid) { - char match[STRLEN("usb:vp") + DECIMAL_STR_MAX(uint16_t) * 2]; + char match[128]; sd_hwdb *hwdb; const char *key, *value; int r; /* Match this USB vendor and product ID combination */ - xsprintf(match, "usb:v%04Xp%04X", vid, pid); + snprintf(match, sizeof match, "usb:v%04Xp%04X", vid, pid); r = sd_hwdb_new(&hwdb); if (r < 0) diff --git a/man/journalctl.xml b/man/journalctl.xml index bdead3f..d1066b8 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -813,7 +813,7 @@ Commands - The following commands are understood. If none is specified the default is to display journal records. + The following commands are understood. If none is specified the default is to display journal records: diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index 6ac20ad..004b394 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -688,6 +688,28 @@ + + + systemd.battery_check= + + Accepts a boolean argument. If false the boot-time battery charge check implemented + by + systemd-battery-check.service8 + is disabled. + + + + + + ifname= + net.ifname_policy= + + Controls interface naming policies, implemented by + systemd-network-generator.service8. + + + + diff --git a/man/notify-selfcontained-example.c b/man/notify-selfcontained-example.c new file mode 100644 index 0000000..9a7553e --- /dev/null +++ b/man/notify-selfcontained-example.c @@ -0,0 +1,173 @@ +/* SPDX-License-Identifier: MIT-0 */ + +/* Implement the systemd notify protocol without external dependencies. + * Supports both readiness notification on startup and on reloading, + * according to the protocol defined at: + * https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html + * This protocol is guaranteed to be stable as per: + * https://systemd.io/PORTABILITY_AND_STABILITY/ */ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#define _cleanup_(f) __attribute__((cleanup(f))) + +static void closep(int *fd) { + if (!fd || *fd < 0) + return; + + close(*fd); + *fd = -1; +} + +static int notify(const char *message) { + union sockaddr_union { + struct sockaddr sa; + struct sockaddr_un sun; + } socket_addr = { + .sun.sun_family = AF_UNIX, + }; + size_t path_length, message_length; + _cleanup_(closep) int fd = -1; + const char *socket_path; + + socket_path = getenv("NOTIFY_SOCKET"); + if (!socket_path) + return 0; /* Not running under systemd? Nothing to do */ + + if (!message) + return -EINVAL; + + message_length = strlen(message); + if (message_length == 0) + return -EINVAL; + + /* Only AF_UNIX is supported, with path or abstract sockets */ + if (socket_path[0] != '/' && socket_path[0] != '@') + return -EAFNOSUPPORT; + + path_length = strlen(socket_path); + /* Ensure there is room for NUL byte */ + if (path_length >= sizeof(socket_addr.sun.sun_path)) + return -E2BIG; + + memcpy(socket_addr.sun.sun_path, socket_path, path_length); + + /* Support for abstract socket */ + if (socket_addr.sun.sun_path[0] == '@') + socket_addr.sun.sun_path[0] = 0; + + fd = socket(AF_UNIX, SOCK_DGRAM|SOCK_CLOEXEC, 0); + if (fd < 0) + return -errno; + + if (connect(fd, &socket_addr.sa, offsetof(struct sockaddr_un, sun_path) + path_length) != 0) + return -errno; + + ssize_t written = write(fd, message, message_length); + if (written != (ssize_t) message_length) + return written < 0 ? -errno : -EPROTO; + + return 1; /* Notified! */ +} + +static int notify_ready(void) { + return notify("READY=1"); +} + +static int notify_reloading(void) { + /* A buffer with length sufficient to format the maximum UINT64 value. */ + char reload_message[sizeof("RELOADING=1\nMONOTONIC_USEC=18446744073709551615")]; + struct timespec ts; + uint64_t now; + + /* Notify systemd that we are reloading, including a CLOCK_MONOTONIC timestamp in usec + * so that the program is compatible with a Type=notify-reload service. */ + + if (clock_gettime(CLOCK_MONOTONIC, &ts) < 0) + return -errno; + + if (ts.tv_sec < 0 || ts.tv_nsec < 0 || + (uint64_t) ts.tv_sec > (UINT64_MAX - (ts.tv_nsec / 1000ULL)) / 1000000ULL) + return -EINVAL; + + now = (uint64_t) ts.tv_sec * 1000000ULL + (uint64_t) ts.tv_nsec / 1000ULL; + + if (snprintf(reload_message, sizeof(reload_message), "RELOADING=1\nMONOTONIC_USEC=%" PRIu64, now) < 0) + return -EINVAL; + + return notify(reload_message); +} + +static volatile sig_atomic_t reloading = 0; +static volatile sig_atomic_t terminating = 0; + +static void signal_handler(int sig) { + if (sig == SIGHUP) + reloading = 1; + else if (sig == SIGINT || sig == SIGTERM) + terminating = 1; +} + +int main(int argc, char **argv) { + struct sigaction sa = { + .sa_handler = signal_handler, + .sa_flags = SA_RESTART, + }; + int r; + + /* Setup signal handlers */ + sigemptyset(&sa.sa_mask); + sigaction(SIGHUP, &sa, NULL); + sigaction(SIGINT, &sa, NULL); + sigaction(SIGTERM, &sa, NULL); + + /* Do more service initialization work here … */ + + /* Now that all the preparations steps are done, signal readiness */ + + r = notify_ready(); + if (r < 0) { + fprintf(stderr, "Failed to notify readiness to $NOTIFY_SOCKET: %s\n", strerror(-r)); + return EXIT_FAILURE; + } + + while (!terminating) { + if (reloading) { + reloading = false; + + /* As a separate but related feature, we can also notify the manager + * when reloading configuration. This allows accurate state-tracking, + * and also automated hook-in of 'systemctl reload' without having to + * specify manually an ExecReload= line in the unit file. */ + + r = notify_reloading(); + if (r < 0) { + fprintf(stderr, "Failed to notify reloading to $NOTIFY_SOCKET: %s\n", strerror(-r)); + return EXIT_FAILURE; + } + + /* Do some reconfiguration work here … */ + + r = notify_ready(); + if (r < 0) { + fprintf(stderr, "Failed to notify readiness to $NOTIFY_SOCKET: %s\n", strerror(-r)); + return EXIT_FAILURE; + } + } + + /* Do some daemon work here … */ + sleep(5); + } + + return EXIT_SUCCESS; +} diff --git a/man/org.freedesktop.resolve1.xml b/man/org.freedesktop.resolve1.xml index f9cba4f..c6b0153 100644 --- a/man/org.freedesktop.resolve1.xml +++ b/man/org.freedesktop.resolve1.xml @@ -156,16 +156,6 @@ node /org/freedesktop/resolve1 { }; - - - - - - - - - - @@ -433,6 +423,30 @@ node /org/freedesktop/resolve1 { The RevertLink() method may be used to revert all per-link settings described above to the defaults. + The FlushCaches() flushes all resource record caches maintained by the + resolver, and ensures that any subsequent lookups re-request their responses from their sources. + + The ResetServerFeatures() flushes any feature information learned about + remote DNS servers. This ensures that subsequent lookups will be initially attempted at the highest DNS + protocol feature level again, possibly requiring a (potentially slow) downgrade cycle to recognize the + supported feature level again. + + The RegisterService() method may be used to register a DNS-SD service on the + host. This functionality is closely related to the functionality provided by + systemd.dnssd5 + files. It takes a server identifier string as first parameter (this is jus a local identifier, and + should be chosen so that it neither collides with the basename of *.dnssd files + nor with names chosen by other IPC clients). It also takes a name template string for the DNS-SD + service name visible on the network. This string is subject to specifier expansation, as documented for + the Name= setting in *.dnssd files. It also takes a service + type string containing the DNS-SD service type, as well as an IP port, a priority/weight pair for the + DNS-SD SRV record. Finally, it takes an array of TXT record data. It returns an object path which may be + used as handle to the registered service. + + The UnregisterService() method undoes the effect of + RegisterService() and deletes a DNS-SD service previously created via IPC + again. + The Flags Parameter @@ -635,6 +649,9 @@ node /org/freedesktop/resolve1 { enabled. Possible values are yes (enabled), no (disabled), udp (only the UDP listener is enabled), and tcp (only the TCP listener is enabled). + + The DNSSECNegativeTrustAnchors property contains a list of recognized DNSSEC + negative trust anchors and contains a list of domains. @@ -689,8 +706,6 @@ node /org/freedesktop/resolve1/link/_1 { }; - - diff --git a/man/path-documents.c b/man/path-documents.c index a357dd6..994f20b 100644 --- a/man/path-documents.c +++ b/man/path-documents.c @@ -2,7 +2,7 @@ #include #include -#include +#include int main(void) { int r; diff --git a/man/portablectl.xml b/man/portablectl.xml index 03ca65e..c1946d7 100644 --- a/man/portablectl.xml +++ b/man/portablectl.xml @@ -45,12 +45,12 @@ within the file system context of the image. Portable service images are an efficient way to bundle multiple related services and other units together, - and transfer them as a whole between systems. When these images are attached the local system the contained units + and transfer them as a whole between systems. When these images are attached to the local system, the contained units may run in most ways like regular system-provided units, either with full privileges or inside strict sandboxing, depending on the selected configuration. For more details, see Portable Services Documentation. - Specifically portable service images may be of the following kind: + Portable service images may be of the following kinds: Directory trees containing an OS, including the top-level directories /usr/, @@ -397,7 +397,7 @@ multiple times, in which case the order in which images are laid down follows the rules specified in systemd.exec5 for the ExtensionImages= directive and for the - systemd-sysext8 and. + systemd-sysext8 and systemd-confext8 tools. The images must contain an extension-release file with metadata that matches what is defined in the os-release of IMAGE. See: diff --git a/man/repart.d.xml b/man/repart.d.xml index 79908a0..efca8d5 100644 --- a/man/repart.d.xml +++ b/man/repart.d.xml @@ -382,7 +382,7 @@ The file specified here must have a size that is a multiple of the basic block size 512 and not be empty. If this option is used, the size allocation algorithm is slightly altered: the partition is - created as least as big as required to fit the data in, i.e. the data size is an additional minimum + created at least as big as required to fit the data in, i.e. the data size is an additional minimum size value taken into consideration for the allocation algorithm, similar to and in addition to the SizeMin= value configured above. @@ -406,7 +406,7 @@ squashfs or the special value swap. If specified and the partition is newly created it is formatted with the specified file system (or as swap device). The file system UUID and label are automatically derived from the partition UUID and label. If this option is used, - the size allocation algorithm is slightly altered: the partition is created as least as big as + the size allocation algorithm is slightly altered: the partition is created at least as big as required for the minimal file system of the specified type (or 4KiB if the minimal size is not known). diff --git a/man/sd_bus_error-example.c b/man/sd_bus_error-example.c index 9b162eb..4b5217c 100644 --- a/man/sd_bus_error-example.c +++ b/man/sd_bus_error-example.c @@ -3,7 +3,7 @@ #include #include #include -#include +#include int writer_with_negative_errno_return(int fd, sd_bus_error *error) { const char *message = "Hello, World!\n"; diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml index da0fa58..9d4fd27 100644 --- a/man/sd_event_add_io.xml +++ b/man/sd_event_add_io.xml @@ -216,16 +216,20 @@ source object and returns the non-negative file descriptor or a negative error number on error (see below). - sd_event_source_set_io_fd() - changes the UNIX file descriptor of an I/O event source created - previously with sd_event_add_io(). It takes - the event source object and the new file descriptor. - - sd_event_source_set_io_fd_own() controls whether the file descriptor of the event source - shall be closed automatically when the event source is freed, i.e. whether it shall be considered 'owned' by the - event source object. By default it is not closed automatically, and the application has to do this on its own. The - b parameter is a boolean parameter: if zero, the file descriptor is not closed automatically - when the event source is freed, otherwise it is closed. + sd_event_source_set_io_fd() changes the UNIX file descriptor of an I/O event + source created previously with sd_event_add_io(). It takes the event source object + and the new file descriptor. If the event source takes the ownership of the previous file descriptor, + that is, sd_event_source_set_io_fd_own() was called for the event source with a + non-zero value, then the previous file descriptor will be closed and the event source will also take the + ownership of the new file descriptor on success. + + sd_event_source_set_io_fd_own() controls whether the file descriptor of the + event source shall be closed automatically when the event source is freed (or when the file descriptor + assigned to the event source is replaced by sd_event_source_set_io_fd()), i.e. + whether it shall be considered 'owned' by the event source object. By default it is not closed + automatically, and the application has to do this on its own. The b parameter is a + boolean parameter: if zero, the file descriptor is not closed automatically when the event source is + freed, otherwise it is closed. sd_event_source_get_io_fd_own() may be used to query the current setting of the file descriptor ownership boolean flag as set with sd_event_source_set_io_fd_own(). It returns diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml index 0baae03..29b8bc7 100644 --- a/man/sd_journal_get_cursor.xml +++ b/man/sd_journal_get_cursor.xml @@ -61,12 +61,6 @@ and should be freed after use with free3. - Note that sd_journal_get_cursor() will - not work before - sd_journal_next3 - (or related call) has been called at least once, in order to - position the read pointer at a valid entry. - sd_journal_test_cursor() may be used to check whether the current position in the journal matches the specified cursor. This is @@ -75,10 +69,17 @@ multiple different cursor strings, and hence string comparing cursors is not possible. Use this call to verify after an invocation of - sd_journal_seek_cursor3 + sd_journal_seek_cursor3, whether the entry being sought to was actually found in the journal or the next closest entry was used instead. + + Note that sd_journal_get_cursor() + and sd_journal_test_cursor() + will not work before + sd_journal_next3 + (or one of the other functions which move to an entry) + has been called at least once to position the read pointer at a valid entry. diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml index 15c72c0..03aec1d 100644 --- a/man/sd_journal_seek_head.xml +++ b/man/sd_journal_seek_head.xml @@ -82,8 +82,7 @@ string. For details on cursors, see sd_journal_get_cursor3. If no entry matching the specified cursor is found the call will seek to the next closest entry (in terms - of time) instead. To verify whether the newly selected entry actually matches the cursor, use - sd_journal_test_cursor3. + of time) instead. Note that these calls do not actually make any entry the new current entry, this needs to be done in a separate step with a subsequent @@ -97,6 +96,13 @@ used, the closest following entry will be sought to, if sd_journal_previous3 is used the closest preceding entry is sought to. + + After the seek is done, and + sd_journal_next3 + or a similar call has been made, + sd_journal_test_cursor3 + may be used to verify whether the newly selected entry actually matches the cursor. + diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 7c32a22..1b96c83 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -486,6 +486,11 @@ (i.e.: lower than 1024), as an attempt to address concerns that unprivileged processes in the guest might try to send malicious notifications to the host, driving it to make destructive decisions based on them. + + Note that, while using this library should be preferred in order to avoid code duplication, it is + also possible to reimplement the simple readiness notification protocol without external dependencies, + as demonstrated in the following self-contained example: + diff --git a/man/systemctl.xml b/man/systemctl.xml index 25b6e46..9bdd882 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1318,36 +1318,49 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err show-environment - Dump the systemd manager environment block. This is the environment - block that is passed to all processes the manager spawns. The environment - block will be dumped in straightforward form suitable for sourcing into - most shells. If no special characters or whitespace is present in the variable - values, no escaping is performed, and the assignments have the form - VARIABLE=value. If whitespace or characters which have - special meaning to the shell are present, dollar-single-quote escaping is - used, and assignments have the form VARIABLE=$'value'. - This syntax is known to be supported by - bash1, - zsh1, - ksh1, - and - busybox1's - ash1, - but not - dash1 - or - fish1. + Dump the systemd manager environment block. This is the environment block that is passed to + all processes the manager spawns. The environment block will be dumped in straightforward form + suitable for sourcing into most shells. If no special characters or whitespace is present in the + variable values, no escaping is performed, and the assignments have the form + VARIABLE=value. If whitespace or characters which have special meaning to the + shell are present, dollar-single-quote escaping is used, and assignments have the form + VARIABLE=$'value'. This syntax is known to be supported by bash1, + zsh1, + ksh1, and + busybox1's + ash1, but + not dash1 or + fish1. + + Note that this shows the effective block, i.e. the combination of + environment variables configured via configuration files, environment generators and via IPC + (i.e. via the set-environment described below). At the moment a unit process + is forked off this combined environment block will be further combined with per-unit environment + variables, which are not visible in this command. set-environment VARIABLE=VALUE… - Set one or more systemd manager environment variables, as specified on the command + Set one or more service manager environment variables, as specified on the command line. This command will fail if variable names and values do not conform to the rules listed above. + Note that this operates on an environment block separate from the environment block + configured from service manager configuration and environment generators. Whenever a process is + invoked the two blocks are combined (also incorporating any per-service environment variables), + and passed to it. The show-environment verb will show the combination of the + blocks, see above. + @@ -1355,11 +1368,16 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err unset-environment VARIABLE… - Unset one or more systemd manager environment - variables. If only a variable name is specified, it will be - removed regardless of its value. If a variable and a value - are specified, the variable is only removed if it has the - specified value. + Unset one or more systemd manager environment variables. If only a variable name is + specified, it will be removed regardless of its value. If a variable and a value are specified, + the variable is only removed if it has the specified value. + + Note that this operates on an environment block separate from the environment block + configured from service manager configuration and environment generators. Whenever a process is + invoked the two blocks are combined (also incorporating any per-service environment variables), + and passed to it. The show-environment verb will show the combination of the + blocks, see above. Note that this means this command cannot be used to unset environment + variables defined in the service manager configuration files or via generators. diff --git a/man/systemd-bless-boot.service.xml b/man/systemd-bless-boot.service.xml index 66454d1..c39f248 100644 --- a/man/systemd-bless-boot.service.xml +++ b/man/systemd-bless-boot.service.xml @@ -37,7 +37,7 @@ boot counting is used. Internally, the service operates based on the LoaderBootCountPath EFI variable (of the - vendor UUID 4a67b082-0a4c-41cf-b6c7-440b29bb8c4), which is passed from the boot loader to the + vendor UUID 4a67b082-0a4c-41cf-b6c7-440b29bb8c4f), which is passed from the boot loader to the OS. It contains a file system path (relative to the EFI system partition) of the Boot Loader Specification compliant boot loader entry file or unified kernel image file that was used to boot up the diff --git a/man/systemd-bsod.service.xml b/man/systemd-bsod.service.xml index 9f54b40..502d239 100644 --- a/man/systemd-bsod.service.xml +++ b/man/systemd-bsod.service.xml @@ -18,7 +18,7 @@ systemd-bsod.service systemd-bsod - Displays boot-time emergency log message in full screen. + Displays boot-time emergency log message in full screen diff --git a/man/systemd-cryptsetup.xml b/man/systemd-cryptsetup.xml index 1d3a313..fb7861c 100644 --- a/man/systemd-cryptsetup.xml +++ b/man/systemd-cryptsetup.xml @@ -52,7 +52,7 @@ systemd-cryptsetup is used to set up (with attach) and tear down (with detach) access to an encrypted block device. It is primarily used via systemd-cryptsetup@.service during early boot, but may also be be called manually. - The positional arguments VOLUME, SOURCEDEVICE, + The positional arguments VOLUME, SOURCE-DEVICE, KEY-FILE, and CRYPTTAB-OPTIONS have the same meaning as the fields in crypttab5. diff --git a/man/systemd-hibernate-resume-generator.xml b/man/systemd-hibernate-resume-generator.xml index 9771350..9483cd9 100644 --- a/man/systemd-hibernate-resume-generator.xml +++ b/man/systemd-hibernate-resume-generator.xml @@ -28,14 +28,11 @@ Description - systemd-hibernate-resume-generator is a - generator that initiates the procedure to resume the system from hibernation. - It creates the + systemd-hibernate-resume-generator is a generator that initiates the procedure + to resume the system from hibernation. When kernel command line option or + HibernateLocation EFI variable is detected, it enables the systemd-hibernate-resume.service8 - unit according to the value of parameter - specified on the kernel command line, or the value of EFI variable - HibernateLocation, which will instruct the kernel - to resume the system from the hibernation image on that device. + unit, which will instruct the kernel to resume the system from the hibernation image. diff --git a/man/systemd-hibernate-resume.service.xml b/man/systemd-hibernate-resume.service.xml index 964c2bd..c9c8014 100644 --- a/man/systemd-hibernate-resume.service.xml +++ b/man/systemd-hibernate-resume.service.xml @@ -33,7 +33,7 @@ systemd-hibernate-resume only supports the in-kernel hibernation implementation, see Swap suspend. - Internally, it works by writing the major:minor of specified device node to + Internally, it works by writing the major:minor of selected device node to /sys/power/resume, along with the offset in memory pages (/sys/power/resume_offset) if supported. diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml index 31435b2..7e252ae 100644 --- a/man/systemd-journald.service.xml +++ b/man/systemd-journald.service.xml @@ -245,6 +245,24 @@ systemd-tmpfiles --create --prefix /var/log/journal + + + systemd.journald.max_level_store= + systemd.journald.max_level_syslog= + systemd.journald.max_level_kmsg= + systemd.journald.max_level_console= + systemd.journald.max_level_wall= + systemd.journald.max_level_socket= + + Controls the maximum log level of messages that are stored in the journal, forwarded + to syslog, kmsg, the console, the wall, or a socket. This kernel command line options override the + settings of the same names in the + journald.conf5 + file. + + + + Note that these kernel command line options are only honoured by the default namespace, see diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index e1e6d84..349bc8a 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1734,7 +1734,7 @@ After=sys-subsystem-net-devices-ens1.device In order to embed binary data into the credential data for , use C-style escaping (i.e. \n to embed a newline, or \x00 to embed a NUL byte). Note that the invoking shell might already apply unescaping - once, hence this might require double escaping!. + once, hence this might require double escaping! The systemd-sysusers.service8 diff --git a/man/systemd-pcrlock.xml b/man/systemd-pcrlock.xml index f82268c..a364dd3 100644 --- a/man/systemd-pcrlock.xml +++ b/man/systemd-pcrlock.xml @@ -389,7 +389,7 @@ Generates/removes a .pcrlock file based on raw binary data. The data is either read from the specified file or from STDIN (if none is specified). This requires that - is specified. The generated pcrlock file is written to the file specified + is specified. The generated .pcrlock file is written to the file specified via or to STDOUT (if none is specified). @@ -436,7 +436,7 @@ - Specifies to NV index to store the policy in. Honoured by + Specifies the NV index to store the policy in. Honoured by make-policy. If not specified the command will automatically pick a free NV index. diff --git a/man/systemd-poweroff.service.xml b/man/systemd-poweroff.service.xml index b430170..1484a45 100644 --- a/man/systemd-poweroff.service.xml +++ b/man/systemd-poweroff.service.xml @@ -60,7 +60,7 @@ kexec, depending on the chosen action. All executables in this directory are executed in parallel, and execution of the action is not continued before all executables finished. Note that these executables are run after all services have been shut down, and after most - mounts have been detached (the root file system as well as /run/ and various API + mounts have been unmounted (the root file system as well as /run/ and various API file systems are still around though). This means any programs dropped into this directory must be prepared to run in such a limited execution environment and not rely on external services or hierarchies such as /var/ to be around (or writable). diff --git a/man/systemd-repart.xml b/man/systemd-repart.xml index 5cd4c1c..27fa257 100644 --- a/man/systemd-repart.xml +++ b/man/systemd-repart.xml @@ -599,7 +599,7 @@ Generate a configuration extension image The following creates a configuration extension DDI (confext) for an - /etc/motd update. + /etc/motd update: mkdir tree tree/etc tree/etc/extension-release.d echo "Hello World" > tree/etc/motd diff --git a/man/systemd-socket-proxyd.xml b/man/systemd-socket-proxyd.xml index 57a6827..59a1073 100644 --- a/man/systemd-socket-proxyd.xml +++ b/man/systemd-socket-proxyd.xml @@ -53,6 +53,11 @@ Accept=no and an event-driven design that scales better with the number of connections. + + Note that systemd-socket-proxyd will not forward socket side channel + information, i.e. will not forward SCM_RIGHTS, SCM_CREDENTIALS, + SCM_SECURITY, SO_PEERCRED, SO_PEERPIDFD, + SO_PEERSEC, SO_PEERGROUPS and similar. Options diff --git a/man/systemd-soft-reboot.service.xml b/man/systemd-soft-reboot.service.xml index e83e18f..c4ee207 100644 --- a/man/systemd-soft-reboot.service.xml +++ b/man/systemd-soft-reboot.service.xml @@ -104,7 +104,7 @@ via SurviveFinalKillSignal=yes, and also be configured to avoid being stopped on isolate via IgnoreOnIsolate=yes. They also have to be configured to be stopped on normal shutdown, reboot and maintenance mode. Finally, they have to be ordered after - basic.target to ensure correct ordeering on boot. Note that in case any new or + basic.target to ensure correct ordering on boot. Note that in case any new or custom units are used to isolate to, or that implement an equivalent shutdown functionality, they will also have to be configured manually for correct ordering and conflicting. For example: diff --git a/man/systemd-storagetm.service.xml b/man/systemd-storagetm.service.xml index 4fa7958..1834f85 100644 --- a/man/systemd-storagetm.service.xml +++ b/man/systemd-storagetm.service.xml @@ -67,7 +67,7 @@ exposed NVMe-TCP mass storage devices. The NQN should follow the syntax described in NVM Express Base Specification 2.0c, section 4.5 "NVMe Qualified Names". Note that the NQN - specified here will be suffixed with a dot and the the block device name before it is exposed on the + specified here will be suffixed with a dot and the block device name before it is exposed on the NVMe target. If not specified defaults to nqn.2023-10.io.systemd:storagetm.ID, where ID is replaced by a 128bit ID derived from diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml index 7607693..3f0a0c2 100644 --- a/man/systemd-sysext.xml +++ b/man/systemd-sysext.xml @@ -140,7 +140,7 @@ but the used architecture identifiers are the same as for ConditionArchitecture= described in systemd.unit5. EXTENSION_RELOAD_MANAGER= can be set to 1 if the extension requires a service manager reload after application - of the extension. Note that the for the reasons mentioned earlier: + of the extension. Note that for the reasons mentioned earlier: Portable Services remain the recommended way to ship system services. diff --git a/man/systemd-timedated.service.xml b/man/systemd-timedated.service.xml index 112bdf3..c0314d5 100644 --- a/man/systemd-timedated.service.xml +++ b/man/systemd-timedated.service.xml @@ -63,7 +63,7 @@ List of network time synchronization services - systemd-timesyncd will look for files with a .list extension + systemd-timedated will look for files with a .list extension in ntp-units.d/ directories. Each file is parsed as a list of unit names, one per line. Empty lines and lines with comments (#) are ignored. Files are read from /usr/lib/systemd/ntp-units.d/ and the corresponding directories under @@ -82,7 +82,7 @@ systemd-timesyncd.service If the environment variable $SYSTEMD_TIMEDATED_NTP_SERVICES is set, - systemd-timesyncd will parse the contents of that variable as a colon-separated list + systemd-timedated will parse the contents of that variable as a colon-separated list of unit names. When set, this variable overrides the file-based list described above. diff --git a/man/systemd-tpm2-setup.service.xml b/man/systemd-tpm2-setup.service.xml index 8c13895..505183a 100644 --- a/man/systemd-tpm2-setup.service.xml +++ b/man/systemd-tpm2-setup.service.xml @@ -37,7 +37,7 @@ The services will store the public key of the SRK key pair in a PEM file in /run/systemd/tpm2-srk-public-key.pem and - /var/lib/systemd/tpm2-srk-public-key.pem. It will also store it in TPM2B_PUBLIC + /var/lib/systemd/tpm2-srk-public-key.pem. They will also store it in TPM2B_PUBLIC format in /run/systemd/tpm2-srk-public-key.tpm2_public and /var/lib/systemd/tpm2-srk-public-key.tpm2b_public. diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index fa55f8e..9bec440 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -18,7 +18,7 @@ systemd-vmspawn - Spawn an OS in a virtual machine. + Spawn an OS in a virtual machine @@ -171,7 +171,7 @@ In order to embed binary data into the credential data for , use C-style escaping (i.e. \n to embed a newline, or \x00 to embed a NUL byte). Note that the invoking shell might already apply unescaping - once, hence this might require double escaping!. + once, hence this might require double escaping! diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index a671649..1e95a94 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -1369,6 +1369,11 @@ CapabilityBoundingSet=~CAP_B CAP_C accessible to privileged processes. However, most namespacing settings, that will not work on their own in user services, will work when used in conjunction with PrivateUsers=. + Note that the various options that turn directories read-only (such as + ProtectSystem=, ReadOnlyPaths=, …) do not affect the ability for + programs to connect to and communicate with AF_UNIX sockets in these + directores. These options cannot be used to lock down access to IPC services hence. + @@ -1382,14 +1387,16 @@ CapabilityBoundingSet=~CAP_B CAP_C mounted read-only, except for the API file system subtrees /dev/, /proc/ and /sys/ (protect these directories using PrivateDevices=, ProtectKernelTunables=, - ProtectControlGroups=). This setting ensures that any modification of the vendor-supplied - operating system (and optionally its configuration, and local mounts) is prohibited for the service. It is - recommended to enable this setting for all long-running services, unless they are involved with system updates - or need to modify the operating system in other ways. If this option is used, - ReadWritePaths= may be used to exclude specific directories from being made read-only. This - setting is implied if DynamicUser= is set. This setting cannot ensure protection in all - cases. In general it has the same limitations as ReadOnlyPaths=, see below. Defaults to - off. + ProtectControlGroups=). This setting ensures that any modification of the + vendor-supplied operating system (and optionally its configuration, and local mounts) is prohibited + for the service. It is recommended to enable this setting for all long-running services, unless they + are involved with system updates or need to modify the operating system in other ways. If this option + is used, ReadWritePaths= may be used to exclude specific directories from being + made read-only. Similar, StateDirectory=, LogsDirectory=, … and + related directory settings (see below) also exclude the specific directories from the effect of + ProtectSystem=. This setting is implied if DynamicUser= is + set. This setting cannot ensure protection in all cases. In general it has the same limitations as + ReadOnlyPaths=, see below. Defaults to off. @@ -3121,6 +3128,9 @@ StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZX values are indexed may also be used to implement cross-unit log record matching. Assign an empty string to reset the list. + Note that this functionality is currently only available in system services, not in per-user + services. + @@ -3176,6 +3186,9 @@ StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZX the kernel log buffer (kmsg), the systemd console, or sent as wall messages to all logged-in users. + Note that this functionality is currently only available in system services, not in per-user + services. + diff --git a/man/systemd.network.xml b/man/systemd.network.xml index 6dd38ea..5f0a703 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -795,7 +795,7 @@ Table=1234 IPForward= to one of ipv4, ipv6 or yes. Note. Any positive boolean values such as yes or - true are now deprecated. Please use one of the values in the above. + true are now deprecated. Please use one of the values above. @@ -3494,7 +3494,7 @@ Address=192.168.0.1/24 Address=192.168.0.2/24 [DHCPServer] ServerAddress=192.168.0.1/24 - are equivalent to the following. + are equivalent to the following: [Network] DHCPServer=yes Address=192.168.0.2/24 @@ -3856,7 +3856,7 @@ ServerAddress=192.168.0.1/24 Takes a timespan. Configures the retransmit time, used by clients to retransmit Neighbor Solicitation messages on address resolution and the Neighbor Unreachability Detection algorithm. - An integer the default unit of seconds, in the range 0…4294967295 msec. Defaults to 0. + An integer, the default unit is seconds, in the range 0…4294967295 msec. Defaults to 0. @@ -3945,8 +3945,8 @@ ServerAddress=192.168.0.1/24 HomeAgent= - Takes a boolean. Specifies that IPv6 router advertisements which indicates to hosts that - the router acts as a Home Agent and includes a Home Agent Option. Defaults to false. See + Takes a boolean. Specifies that IPv6 router advertisements which indicate to hosts that + the router acts as a Home Agent and includes a Home Agent option. Defaults to false. See RFC 6275 for further details. @@ -3956,7 +3956,7 @@ ServerAddress=192.168.0.1/24 HomeAgentLifetimeSec= - Takes a timespan. Specifies the lifetime of the Home Agent. An integer the default unit of seconds, + Takes a timespan. Specifies the lifetime of the Home Agent. An integer, the default unit is seconds, in the range 1…65535. Defaults to the value set to RouterLifetimeSec=. diff --git a/man/systemd.pcrlock.xml b/man/systemd.pcrlock.xml index 5687db5..ec08ffd 100644 --- a/man/systemd.pcrlock.xml +++ b/man/systemd.pcrlock.xml @@ -94,7 +94,7 @@ 250-firmware-code-early.pcrlock Firmware code measurements, as recorded to PCR 0 and 2, up to the separator - measurement (see 400-secureboot-separator.pcrlock. below). May be generated via + measurement (see 400-secureboot-separator.pcrlock below). May be generated via systemd-pcrlock lock-firmware-code. @@ -104,7 +104,7 @@ 250-firmware-config-early.pcrlock Firmware configuration measurements, as recorded to PCR 1 and 3, up to the separator - measurement (see 400-secureboot-separator.pcrlock. below). May be generated via + measurement (see 400-secureboot-separator.pcrlock below). May be generated via systemd-pcrlock lock-firmware-config. @@ -140,7 +140,7 @@ 550-firmware-code-late.pcrlock Firmware code measurements, as recorded to PCR 0 and 2, after the separator - measurement (see 400-secureboot-separator.pcrlock. above). May be generated via + measurement (see 400-secureboot-separator.pcrlock above). May be generated via systemd-pcrlock lock-firmware-code. @@ -150,7 +150,7 @@ 550-firmware-config-late.pcrlock Firmware configuration measurements, as recorded to PCR 1 and 3, after the separator - measurement (see 400-secureboot-separator.pcrlock. above). May be generated via + measurement (see 400-secureboot-separator.pcrlock above). May be generated via systemd-pcrlock lock-firmware-config. @@ -178,7 +178,7 @@ 700-action-efi-exit-boot-services.pcrlock The EFI action generated when ExitBootServices() is generated, - i.e. the UEFI environment is left and the OS takes over. Covers the PCR 5 measurement. Statically + i.e. when the UEFI environment is left and the OS takes over. Covers the PCR 5 measurement. Statically defined. diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index 42f265c..5c61b74 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -749,6 +749,9 @@ CPUWeight=20 DisableControllers=cpu / \ The system default for this setting may be controlled with DefaultIPAccounting= in systemd-system.conf5. + Note that this functionality is currently only available for system services, not for + per-user services. + @@ -865,8 +868,10 @@ CPUWeight=20 DisableControllers=cpu / \ SocketBindDeny=bind-rule - Allow or deny binding a socket address to a socket by matching it with the bind-rule and - applying a corresponding action if there is a match. + Configures restrictions on the ability of unit processes to invoke bind2 on a + socket. Both allow and deny rules may defined that restrict which addresses a socket may be bound + to. bind-rule describes socket properties such as address-family, transport-protocol and ip-ports. @@ -913,6 +918,13 @@ CPUWeight=20 DisableControllers=cpu / \ The feature is implemented with cgroup/bind4 and cgroup/bind6 cgroup-bpf hooks. + + Note that these settings apply to any bind2 + system call invocation by the unit processes, regardless in which network namespace they are + placed. Or in other words: changing the network namespace is not a suitable mechanism for escaping + these restrictions on bind(). + Examples:… # Allow binding IPv6 socket addresses with a port greater than or equal to 10000. [Service] diff --git a/man/systemd.service.xml b/man/systemd.service.xml index a5f6179..86d7108 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1365,7 +1365,7 @@ : - If the executable path is prefixed with :, environment variable substitution (as described by the "Command Lines" section below) is not applied. + If the executable path is prefixed with :, environment variable substitution (as described below this table) is not applied. @@ -1719,7 +1719,7 @@ SystemdService=simple-dbus-service.service Description=Simple notifying service [Service] -Type=notify +Type=notify-reload ExecStart=/usr/sbin/simple-notifying-service [Install] @@ -1737,6 +1737,16 @@ WantedBy=multi-user.target systemd.kill5 for details on how you can influence the way systemd terminates the service. + + To avoid code duplication, it is preferable to use + sd_notify3 + when possible, especially when other APIs provided by + libsystemd3 are + also used, but note that the notification protocol is very simple and guaranteed to be stable as per + the Interface Portability and Stability + Promise, so it can be reimplemented by services with no external dependencies. For a + self-contained example, see + sd_notify3. diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 647b7db..73c8c5b 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -756,7 +756,7 @@ TCPCongestion= Takes a string value. Controls the TCP congestion algorithm used by this - socket. Should be one of westwood, veno, + socket. Should be one of westwood, reno, cubic, lp or any other available algorithm supported by the IP stack. This setting applies only to stream sockets. diff --git a/man/ukify.xml b/man/ukify.xml index 9b7e209..b882de8 100644 --- a/man/ukify.xml +++ b/man/ukify.xml @@ -476,8 +476,10 @@ SBAT metadata associated with the UKI or addon. SBAT policies are useful to revoke whole groups of UKIs or addons with a single, static policy update that does not take space in DBX/MOKX. If not specified manually, a default metadata entry consisting of - uki,1,UKI,uki,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html - will be used, to ensure it is always possible to revoke UKIs and addons. For more information on + uki,1,UKI,uki,1,https://uapi-group.org/specifications/specs/unified_kernel_image/ + for UKIs and + uki-addon,1,UKI Addon,addon,1,https://www.freedesktop.org/software/systemd/man/latest/systemd-stub.html + for addons will be used, to ensure it is always possible to revoke them. For more information on SBAT see Shim documentation. @@ -560,7 +562,7 @@ --initrd=early_cpio \ --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \ --sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md - uki.author.myimage,1,UKI for System,uki.author.myimage,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html' \ + uki.author.myimage,1,UKI for System,uki.author.myimage,1,https://uapi-group.org/specifications/specs/unified_kernel_image/' \ --pcr-private-key=pcr-private-initrd-key.pem \ --pcr-public-key=pcr-public-initrd-key.pem \ --phases='enter-initrd' \ @@ -633,7 +635,7 @@ $ ukify -c ukify.conf build \ --secureboot-certificate=sb.cert \ --cmdline='debug' \ --sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md - uki.addon.author,1,UKI Addon for System,uki.addon.author,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html' + uki-addon.author,1,UKI Addon for System,uki-addon.author,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html' --output=debug.cmdline diff --git a/man/varlinkctl.xml b/man/varlinkctl.xml index 7dec54c..08d2312 100644 --- a/man/varlinkctl.xml +++ b/man/varlinkctl.xml @@ -50,7 +50,7 @@ call ADDRESS METHOD - PARAMETERS + ARGUMENTS @@ -100,7 +100,7 @@ info ADDRESS Show brief information about the specified service, including vendor name and list of - implemented interfaces. Expects a service address in the formats described above. + implemented interfaces. Expects a service address in one of the formats described above. @@ -109,7 +109,7 @@ list-interfaces ADDRESS Show list of interfaces implemented by the specified service. Expects a service - address in the formats described above. + address in one of the formats described above. @@ -118,7 +118,7 @@ introspect ADDRESS INTERFACE Show interface definition of the specified interface provided by the specified - service. Expects a service address in the formats described above and a Varlink interface + service. Expects a service address in one of the formats described above and a Varlink interface name. -- cgit v1.2.3