diff options
Diffstat (limited to 'man')
45 files changed, 439 insertions, 134 deletions
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 @@ </varlistentry> </variablelist> + <para>Note that setting the regular <varname>$LESS</varname> environment variable has no effect + for <command>less</command> invocations by systemd tools.</para> + <para>See <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more discussion.</para></listitem> @@ -146,7 +149,10 @@ <term><varname>$SYSTEMD_LESSCHARSET</varname></term> <listitem><para>Override the charset passed to <command>less</command> (by default <literal>utf-8</literal>, if - the invoking terminal is determined to be UTF-8 compatible).</para></listitem> + the invoking terminal is determined to be UTF-8 compatible).</para> + + <para>Note that setting the regular <varname>$LESSCHARSET</varname> environment variable has no effect + for <command>less</command> invocations by systemd tools.</para></listitem> </varlistentry> <varlistentry id='lesssecure'> 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 @@ <para>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 <filename>/etc/crypttab</filename> line, but may also - configured in <filename>/etc/cryptsetup-keys.d/</filename> and + be configured in <filename>/etc/cryptsetup-keys.d/</filename> and <filename>/run/cryptsetup-keys.d/</filename> (see above) or in the LUKS2 JSON token header (in case of the latter three). Use the <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> @@ -923,7 +923,7 @@ is acquired by connecting to the socket and reading the key from the connection. The connection is made from an <constant>AF_UNIX</constant> socket name in the abstract namespace, see <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry> for - details. The source socket name is chosen according the following format:</para> + details. The source socket name is chosen according to the following format:</para> <programlisting><constant>NUL</constant> <replaceable>RANDOM</replaceable> /cryptsetup/ <replaceable>VOLUME</replaceable></programlisting> 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 @@ <!ENTITY DEFAULT_TIMEOUT "{{DEFAULT_TIMEOUT_SEC}} s"> <!ENTITY DEFAULT_USER_TIMEOUT "{{DEFAULT_USER_TIMEOUT_SEC}} s"> <!ENTITY DEFAULT_KEYMAP "{{SYSTEMD_DEFAULT_KEYMAP}}"> -<!ENTITY fedora_latest_version "38"> +<!ENTITY fedora_latest_version "40"> <!ENTITY fedora_cloud_release "1.6"> 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 @@ <xsl:template match="citerefentry[@project='archlinux']"> <a> <xsl:attribute name="href"> - <xsl:text>https://www.archlinux.org/</xsl:text> - <xsl:value-of select="refentrytitle"/> - <xsl:text>/</xsl:text> + <xsl:text>https://man.archlinux.org/man/</xsl:text> <xsl:value-of select="refentrytitle"/> <xsl:text>.</xsl:text> <xsl:value-of select="manvolnum"/> - <xsl:text>.html</xsl:text> + <xsl:text>.en.html</xsl:text> </xsl:attribute> <xsl:call-template name="inline.charseq"/> </a> 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.</para></listitem> <listitem><para>In the child, call <function>fork()</function> 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.)</para></listitem> @@ -228,7 +228,7 @@ <listitem><para>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 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> with - <varname>FDSTORE=1</varname>..</para></listitem> + <varname>FDSTORE=1</varname>.</para></listitem> <listitem><para>Instead of using the <function>syslog()</function> 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 <assert.h> #include <stdio.h> #include <unistd.h> -#include <sd-event.h> +#include <systemd/sd-event.h> 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 <stdio.h> #include <stdint.h> -#include <sd-hwdb.h> +#include <systemd/sd-hwdb.h> 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 @@ <refsect1> <title>Commands</title> - <para>The following commands are understood. If none is specified the default is to display journal records.</para> + <para>The following commands are understood. If none is specified the default is to display journal records:</para> <variablelist> <varlistentry> 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 @@ <xi:include href="version-info.xml" xpointer="v254"/></listitem> </varlistentry> + + <varlistentry> + <term><varname>systemd.battery_check=</varname></term> + + <listitem><para>Accepts a boolean argument. If false the boot-time battery charge check implemented + by + <citerefentry><refentrytitle>systemd-battery-check.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + is disabled.</para> + + <xi:include href="version-info.xml" xpointer="v254"/></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ifname=</varname></term> + <term><varname>net.ifname_policy=</varname></term> + + <listitem><para>Controls interface naming policies, implemented by + <citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <xi:include href="version-info.xml" xpointer="v245"/></listitem> + </varlistentry> + </variablelist> </refsect1> 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 <errno.h> +#include <inttypes.h> +#include <signal.h> +#include <stdbool.h> +#include <stddef.h> +#include <stdlib.h> +#include <stdio.h> +#include <sys/socket.h> +#include <sys/un.h> +#include <time.h> +#include <unistd.h> + +#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 { }; </programlisting> - <!--method RegisterService is not documented!--> - - <!--method UnregisterService is not documented!--> - - <!--method FlushCaches is not documented!--> - - <!--method ResetServerFeatures is not documented!--> - - <!--property DNSSECNegativeTrustAnchors is not documented!--> - <!--Autogenerated cross-references for systemd.directives, do not edit--> <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Manager"/> @@ -433,6 +423,30 @@ node /org/freedesktop/resolve1 { <para>The <function>RevertLink()</function> method may be used to revert all per-link settings described above to the defaults.</para> + <para>The <function>FlushCaches()</function> flushes all resource record caches maintained by the + resolver, and ensures that any subsequent lookups re-request their responses from their sources.</para> + + <para>The <function>ResetServerFeatures()</function> 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.</para> + + <para>The <function>RegisterService()</function> method may be used to register a DNS-SD service on the + host. This functionality is closely related to the functionality provided by + <citerefentry><refentrytitle>systemd.dnssd</refentrytitle><manvolnum>5</manvolnum></citerefentry> + 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 <filename>*.dnssd</filename> 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 <varname>Name=</varname> setting in <filename>*.dnssd</filename> 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.</para> + + <para>The <function>UnregisterService()</function> method undoes the effect of + <function>RegisterService()</function> and deletes a DNS-SD service previously created via IPC + again.</para> + <refsect3> <title>The Flags Parameter</title> @@ -635,6 +649,9 @@ node /org/freedesktop/resolve1 { enabled. Possible values are <literal>yes</literal> (enabled), <literal>no</literal> (disabled), <literal>udp</literal> (only the UDP listener is enabled), and <literal>tcp</literal> (only the TCP listener is enabled).</para> + + <para>The <varname>DNSSECNegativeTrustAnchors</varname> property contains a list of recognized DNSSEC + negative trust anchors and contains a list of domains.</para> </refsect2> </refsect1> @@ -689,8 +706,6 @@ node /org/freedesktop/resolve1/link/_1 { }; </programlisting> - <!--property DNSSECNegativeTrustAnchors is not documented!--> - <!--Autogenerated cross-references for systemd.directives, do not edit--> <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Link"/> 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 <stdio.h> #include <stdlib.h> -#include <sd-path.h> +#include <systemd/sd-path.h> 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.</para> <para>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 <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services Documentation</ulink>.</para> - <para>Specifically portable service images may be of the following kind:</para> + <para>Portable service images may be of the following kinds:</para> <itemizedlist> <listitem><para>Directory trees containing an OS, including the top-level directories <filename>/usr/</filename>, @@ -397,7 +397,7 @@ multiple times, in which case the order in which images are laid down follows the rules specified in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for the <varname>ExtensionImages=</varname> directive and for the - <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> and. + <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> and <citerefentry><refentrytitle>systemd-confext</refentrytitle><manvolnum>8</manvolnum></citerefentry> tools. The images must contain an <filename>extension-release</filename> file with metadata that matches what is defined in the <filename>os-release</filename> of <replaceable>IMAGE</replaceable>. 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 @@ <para>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 <varname>SizeMin=</varname> value configured above.</para> @@ -406,7 +406,7 @@ <literal>squashfs</literal> or the special value <literal>swap</literal>. 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).</para> 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 <errno.h> #include <string.h> #include <unistd.h> -#include <sd-bus.h> +#include <systemd/sd-bus.h> 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).</para> - <para><function>sd_event_source_set_io_fd()</function> - changes the UNIX file descriptor of an I/O event source created - previously with <function>sd_event_add_io()</function>. It takes - the event source object and the new file descriptor.</para> - - <para><function>sd_event_source_set_io_fd_own()</function> 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 - <parameter>b</parameter> parameter is a boolean parameter: if zero, the file descriptor is not closed automatically - when the event source is freed, otherwise it is closed.</para> + <para><function>sd_event_source_set_io_fd()</function> changes the UNIX file descriptor of an I/O event + source created previously with <function>sd_event_add_io()</function>. 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, <function>sd_event_source_set_io_fd_own()</function> 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.</para> + + <para><function>sd_event_source_set_io_fd_own()</function> 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 <function>sd_event_source_set_io_fd()</function>), 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 <parameter>b</parameter> parameter is a + boolean parameter: if zero, the file descriptor is not closed automatically when the event source is + freed, otherwise it is closed.</para> <para><function>sd_event_source_get_io_fd_own()</function> may be used to query the current setting of the file descriptor ownership boolean flag as set with <function>sd_event_source_set_io_fd_own()</function>. 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 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - <para>Note that <function>sd_journal_get_cursor()</function> will - not work before - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> - (or related call) has been called at least once, in order to - position the read pointer at a valid entry.</para> - <para><function>sd_journal_test_cursor()</function> 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 - <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, whether the entry being sought to was actually found in the journal or the next closest entry was used instead.</para> + + <para>Note that <function>sd_journal_get_cursor()</function> + and <function>sd_journal_test_cursor()</function> + will not work before + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + (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.</para> </refsect1> <refsect1> 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 <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 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 - <citerefentry><refentrytitle>sd_journal_test_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + of time) instead.</para> <para>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 <citerefentry><refentrytitle>sd_journal_previous</refentrytitle><manvolnum>3</manvolnum></citerefentry> is used the closest preceding entry is sought to.</para> + + <para>After the seek is done, and + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or a similar call has been made, + <citerefentry><refentrytitle>sd_journal_test_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry> + may be used to verify whether the newly selected entry actually matches the cursor. + </para> </refsect1> <refsect1> 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.</para> + + <para>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: + <programlisting><xi:include href="notify-selfcontained-example.c" parse="text"/></programlisting></para> </refsect1> <refsect1> 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 <term><command>show-environment</command></term> <listitem> - <para>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 - <literal>VARIABLE=value</literal>. If whitespace or characters which have - special meaning to the shell are present, dollar-single-quote escaping is - used, and assignments have the form <literal>VARIABLE=$'value'</literal>. - This syntax is known to be supported by - <citerefentry project='die-net'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>zsh</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>ksh</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - and - <citerefentry project='die-net'><refentrytitle>busybox</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <citerefentry project='die-net'><refentrytitle>ash</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - but not - <citerefentry project='die-net'><refentrytitle>dash</refentrytitle><manvolnum>1</manvolnum></citerefentry> - or - <citerefentry project='die-net'><refentrytitle>fish</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + <para>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 + <literal>VARIABLE=value</literal>. If whitespace or characters which have special meaning to the + shell are present, dollar-single-quote escaping is used, and assignments have the form + <literal>VARIABLE=$'value'</literal>. This syntax is known to be supported by <citerefentry + project='die-net'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry + project='die-net'><refentrytitle>zsh</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry + project='die-net'><refentrytitle>ksh</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and + <citerefentry + project='die-net'><refentrytitle>busybox</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <citerefentry + project='die-net'><refentrytitle>ash</refentrytitle><manvolnum>1</manvolnum></citerefentry>, but + not <citerefentry + project='die-net'><refentrytitle>dash</refentrytitle><manvolnum>1</manvolnum></citerefentry> or + <citerefentry + project='die-net'><refentrytitle>fish</refentrytitle><manvolnum>1</manvolnum></citerefentry>. </para> + + <para>Note that this shows the <emphasis>effective</emphasis> block, i.e. the combination of + environment variables configured via configuration files, environment generators and via IPC + (i.e. via the <command>set-environment</command> 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.</para> </listitem> </varlistentry> <varlistentry> <term><command>set-environment <replaceable>VARIABLE=VALUE</replaceable>…</command></term> <listitem> - <para>Set one or more systemd manager environment variables, as specified on the command + <para>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.</para> + <para>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 <command>show-environment</command> verb will show the combination of the + blocks, see above.</para> + <xi:include href="version-info.xml" xpointer="v233"/> </listitem> </varlistentry> @@ -1355,11 +1368,16 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err <term><command>unset-environment <replaceable>VARIABLE</replaceable>…</command></term> <listitem> - <para>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.</para> + <para>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.</para> + + <para>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 <command>show-environment</command> 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.</para> <xi:include href="version-info.xml" xpointer="v233"/> </listitem> 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.</para> <para>Internally, the service operates based on the <varname>LoaderBootCountPath</varname> EFI variable (of the - vendor UUID <constant>4a67b082-0a4c-41cf-b6c7-440b29bb8c4</constant>), which is passed from the boot loader to the + vendor UUID <constant>4a67b082-0a4c-41cf-b6c7-440b29bb8c4f</constant>), which is passed from the boot loader to the OS. It contains a file system path (relative to the EFI system partition) of the <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> 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 @@ <refnamediv> <refname>systemd-bsod.service</refname> <refname>systemd-bsod</refname> - <refpurpose>Displays boot-time emergency log message in full screen.</refpurpose> + <refpurpose>Displays boot-time emergency log message in full screen</refpurpose> </refnamediv> <refsynopsisdiv> 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 @@ <para><filename>systemd-cryptsetup</filename> is used to set up (with <command>attach</command>) and tear down (with <command>detach</command>) access to an encrypted block device. It is primarily used via <filename>systemd-cryptsetup@.service</filename> during early boot, but may also be be called manually. - The positional arguments <parameter>VOLUME</parameter>, <parameter>SOURCEDEVICE</parameter>, + The positional arguments <parameter>VOLUME</parameter>, <parameter>SOURCE-DEVICE</parameter>, <parameter>KEY-FILE</parameter>, and <parameter>CRYPTTAB-OPTIONS</parameter> have the same meaning as the fields in <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> 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 @@ <refsect1> <title>Description</title> - <para><command>systemd-hibernate-resume-generator</command> is a - generator that initiates the procedure to resume the system from hibernation. - It creates the + <para><command>systemd-hibernate-resume-generator</command> is a generator that initiates the procedure + to resume the system from hibernation. When <option>resume=</option> kernel command line option or + <varname>HibernateLocation</varname> EFI variable is detected, it enables the <citerefentry><refentrytitle>systemd-hibernate-resume.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - unit according to the value of <option>resume=</option> parameter - specified on the kernel command line, or the value of EFI variable - <varname>HibernateLocation</varname>, which will instruct the kernel - to resume the system from the hibernation image on that device.</para> + unit, which will instruct the kernel to resume the system from the hibernation image.</para> </refsect1> <refsect1> 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 @@ <para><command>systemd-hibernate-resume</command> only supports the in-kernel hibernation implementation, see <ulink url="https://docs.kernel.org/power/swsusp.html">Swap suspend</ulink>. - 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 <filename>/sys/power/resume</filename>, along with the offset in memory pages (<filename>/sys/power/resume_offset</filename>) if supported.</para> 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</programlisting> </listitem> </varlistentry> + + <varlistentry> + <term><varname>systemd.journald.max_level_store=</varname></term> + <term><varname>systemd.journald.max_level_syslog=</varname></term> + <term><varname>systemd.journald.max_level_kmsg=</varname></term> + <term><varname>systemd.journald.max_level_console=</varname></term> + <term><varname>systemd.journald.max_level_wall=</varname></term> + <term><varname>systemd.journald.max_level_socket=</varname></term> + + <listitem><para>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 + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + file.</para> + + <xi:include href="version-info.xml" xpointer="v232"/> + </listitem> + </varlistentry> </variablelist> <para>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</programlisting> <para>In order to embed binary data into the credential data for <option>--set-credential=</option>, use C-style escaping (i.e. <literal>\n</literal> to embed a newline, or <literal>\x00</literal> to embed a <constant>NUL</constant> byte). Note that the invoking shell might already apply unescaping - once, hence this might require double escaping!.</para> + once, hence this might require double escaping!</para> <para>The <citerefentry><refentrytitle>systemd-sysusers.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 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 @@ <listitem><para>Generates/removes a <filename>.pcrlock</filename> 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 - <option>--pcrs=</option> is specified. The generated pcrlock file is written to the file specified + <option>--pcrs=</option> is specified. The generated .pcrlock file is written to the file specified via <option>--pcrlock=</option> or to STDOUT (if none is specified).</para> <xi:include href="version-info.xml" xpointer="v255"/> @@ -436,7 +436,7 @@ <varlistentry> <term><option>--nv-index=</option></term> - <listitem><para>Specifies to NV index to store the policy in. Honoured by + <listitem><para>Specifies the NV index to store the policy in. Honoured by <command>make-policy</command>. If not specified the command will automatically pick a free NV index.</para> 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 @@ <literal>kexec</literal>, 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 <emphasis>after</emphasis> all services have been shut down, and after most - mounts have been detached (the root file system as well as <filename>/run/</filename> and various API + mounts have been unmounted (the root file system as well as <filename>/run/</filename> 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 <filename>/var/</filename> to be around (or writable).</para> 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 @@ <title>Generate a configuration extension image</title> <para>The following creates a configuration extension DDI (confext) for an - <filename>/etc/motd</filename> update.</para> + <filename>/etc/motd</filename> update:</para> <programlisting>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 @@ <literal>Accept=no</literal> and an event-driven design that scales better with the number of connections.</para> + + <para>Note that <command>systemd-socket-proxyd</command> will not forward socket side channel + information, i.e. will not forward <constant>SCM_RIGHTS</constant>, <constant>SCM_CREDENTIALS</constant>, + <constant>SCM_SECURITY</constant>, <constant>SO_PEERCRED</constant>, <constant>SO_PEERPIDFD</constant>, + <constant>SO_PEERSEC</constant>, <constant>SO_PEERGROUPS</constant> and similar.</para> </refsect1> <refsect1> <title>Options</title> 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 <varname>SurviveFinalKillSignal=yes</varname>, and also be configured to avoid being stopped on isolate via <varname>IgnoreOnIsolate=yes</varname>. They also have to be configured to be stopped on normal shutdown, reboot and maintenance mode. Finally, they have to be ordered after - <constant>basic.target</constant> to ensure correct ordeering on boot. Note that in case any new or + <constant>basic.target</constant> 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:</para> 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 <ulink url="https://nvmexpress.org/wp-content/uploads/NVM-Express-Base-Specification-2.0c-2022.10.04-Ratified.pdf">NVM Express Base Specification 2.0c</ulink>, 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 <literal>nqn.2023-10.io.systemd:storagetm.<replaceable>ID</replaceable></literal>, 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 <varname>ConditionArchitecture=</varname> described in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. <varname>EXTENSION_RELOAD_MANAGER=</varname> 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: <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> 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 @@ <refsect1> <title>List of network time synchronization services</title> - <para><command>systemd-timesyncd</command> will look for files with a <literal>.list</literal> extension + <para><command>systemd-timedated</command> will look for files with a <literal>.list</literal> extension in <filename>ntp-units.d/</filename> directories. Each file is parsed as a list of unit names, one per line. Empty lines and lines with comments (<literal>#</literal>) are ignored. Files are read from <filename>/usr/lib/systemd/ntp-units.d/</filename> and the corresponding directories under @@ -82,7 +82,7 @@ systemd-timesyncd.service </example> <para>If the environment variable <varname>$SYSTEMD_TIMEDATED_NTP_SERVICES</varname> is set, - <command>systemd-timesyncd</command> will parse the contents of that variable as a colon-separated list + <command>systemd-timedated</command> 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.</para> <example> 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 @@ <para>The services will store the public key of the SRK key pair in a PEM file in <filename>/run/systemd/tpm2-srk-public-key.pem</filename> and - <filename>/var/lib/systemd/tpm2-srk-public-key.pem</filename>. It will also store it in TPM2B_PUBLIC + <filename>/var/lib/systemd/tpm2-srk-public-key.pem</filename>. They will also store it in TPM2B_PUBLIC format in <filename>/run/systemd/tpm2-srk-public-key.tpm2_public</filename> and <filename>/var/lib/systemd/tpm2-srk-public-key.tpm2b_public</filename>.</para> 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 @@ <refnamediv> <refname>systemd-vmspawn</refname> - <refpurpose>Spawn an OS in a virtual machine.</refpurpose> + <refpurpose>Spawn an OS in a virtual machine</refpurpose> </refnamediv> <refsynopsisdiv> @@ -171,7 +171,7 @@ <para>In order to embed binary data into the credential data for <option>--set-credential=</option>, use C-style escaping (i.e. <literal>\n</literal> to embed a newline, or <literal>\x00</literal> to embed a <constant>NUL</constant> byte). Note that the invoking shell might already apply unescaping - once, hence this might require double escaping!.</para> + once, hence this might require double escaping!</para> <xi:include href="version-info.xml" xpointer="v255"/></listitem> </varlistentry> 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</programlisting> 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 <varname>PrivateUsers=</varname><option>true</option>.</para> + <para>Note that the various options that turn directories read-only (such as + <varname>ProtectSystem=</varname>, <varname>ReadOnlyPaths=</varname>, …) do not affect the ability for + programs to connect to and communicate with <constant>AF_UNIX</constant> sockets in these + directores. These options cannot be used to lock down access to IPC services hence.</para> + <variablelist class='unit-directives'> <varlistentry> @@ -1382,14 +1387,16 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting> mounted read-only, except for the API file system subtrees <filename>/dev/</filename>, <filename>/proc/</filename> and <filename>/sys/</filename> (protect these directories using <varname>PrivateDevices=</varname>, <varname>ProtectKernelTunables=</varname>, - <varname>ProtectControlGroups=</varname>). 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, - <varname>ReadWritePaths=</varname> may be used to exclude specific directories from being made read-only. This - setting is implied if <varname>DynamicUser=</varname> is set. This setting cannot ensure protection in all - cases. In general it has the same limitations as <varname>ReadOnlyPaths=</varname>, see below. Defaults to - off.</para> + <varname>ProtectControlGroups=</varname>). 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, <varname>ReadWritePaths=</varname> may be used to exclude specific directories from being + made read-only. Similar, <varname>StateDirectory=</varname>, <varname>LogsDirectory=</varname>, … and + related directory settings (see below) also exclude the specific directories from the effect of + <varname>ProtectSystem=</varname>. This setting is implied if <varname>DynamicUser=</varname> is + set. This setting cannot ensure protection in all cases. In general it has the same limitations as + <varname>ReadOnlyPaths=</varname>, see below. Defaults to off.</para> <xi:include href="version-info.xml" xpointer="v214"/></listitem> </varlistentry> @@ -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.</para> + <para>Note that this functionality is currently only available in system services, not in per-user + services.</para> + <xi:include href="version-info.xml" xpointer="v236"/></listitem> </varlistentry> @@ -3176,6 +3186,9 @@ StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZX the kernel log buffer (kmsg), the systemd console, or sent as wall messages to all logged-in users.</para> + <para>Note that this functionality is currently only available in system services, not in per-user + services.</para> + <xi:include href="version-info.xml" xpointer="v253"/></listitem> </varlistentry> 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</programlisting></para> <varname>IPForward=</varname> to one of <literal>ipv4</literal>, <literal>ipv6</literal> or <literal>yes</literal>.</para> <para>Note. Any positive boolean values such as <literal>yes</literal> or - <literal>true</literal> are now deprecated. Please use one of the values in the above.</para> + <literal>true</literal> are now deprecated. Please use one of the values above.</para> <xi:include href="version-info.xml" xpointer="v219"/> </listitem> @@ -3494,7 +3494,7 @@ Address=192.168.0.1/24 Address=192.168.0.2/24 [DHCPServer] ServerAddress=192.168.0.1/24</programlisting> - are equivalent to the following. + are equivalent to the following: <programlisting>[Network] DHCPServer=yes Address=192.168.0.2/24 @@ -3856,7 +3856,7 @@ ServerAddress=192.168.0.1/24</programlisting> <listitem><para>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.</para> + An integer, the default unit is seconds, in the range 0…4294967295 msec. Defaults to 0.</para> <xi:include href="version-info.xml" xpointer="v255"/> </listitem> @@ -3945,8 +3945,8 @@ ServerAddress=192.168.0.1/24</programlisting> <varlistentry> <term><varname>HomeAgent=</varname></term> - <listitem><para>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 + <listitem><para>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 <ulink url="https://tools.ietf.org/html/rfc6275">RFC 6275</ulink> for further details.</para> <xi:include href="version-info.xml" xpointer="v255"/> @@ -3956,7 +3956,7 @@ ServerAddress=192.168.0.1/24</programlisting> <varlistentry> <term><varname>HomeAgentLifetimeSec=</varname></term> - <listitem><para>Takes a timespan. Specifies the lifetime of the Home Agent. An integer the default unit of seconds, + <listitem><para>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 <varname>RouterLifetimeSec=</varname>.</para> <xi:include href="version-info.xml" xpointer="v255"/> 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 @@ <term><filename>250-firmware-code-early.pcrlock</filename></term> <listitem><para>Firmware code measurements, as recorded to PCR 0 and 2, up to the separator - measurement (see <filename>400-secureboot-separator.pcrlock.</filename> below). May be generated via + measurement (see <filename>400-secureboot-separator.pcrlock</filename> below). May be generated via <command>systemd-pcrlock lock-firmware-code</command>.</para> <xi:include href="version-info.xml" xpointer="v255"/></listitem> @@ -104,7 +104,7 @@ <term><filename>250-firmware-config-early.pcrlock</filename></term> <listitem><para>Firmware configuration measurements, as recorded to PCR 1 and 3, up to the separator - measurement (see <filename>400-secureboot-separator.pcrlock.</filename> below). May be generated via + measurement (see <filename>400-secureboot-separator.pcrlock</filename> below). May be generated via <command>systemd-pcrlock lock-firmware-config</command>.</para> <xi:include href="version-info.xml" xpointer="v255"/></listitem> @@ -140,7 +140,7 @@ <term><filename>550-firmware-code-late.pcrlock</filename></term> <listitem><para>Firmware code measurements, as recorded to PCR 0 and 2, after the separator - measurement (see <filename>400-secureboot-separator.pcrlock.</filename> above). May be generated via + measurement (see <filename>400-secureboot-separator.pcrlock</filename> above). May be generated via <command>systemd-pcrlock lock-firmware-code</command>.</para> <xi:include href="version-info.xml" xpointer="v255"/></listitem> @@ -150,7 +150,7 @@ <term><filename>550-firmware-config-late.pcrlock</filename></term> <listitem><para>Firmware configuration measurements, as recorded to PCR 1 and 3, after the separator - measurement (see <filename>400-secureboot-separator.pcrlock.</filename> above). May be generated via + measurement (see <filename>400-secureboot-separator.pcrlock</filename> above). May be generated via <command>systemd-pcrlock lock-firmware-config</command>.</para> <xi:include href="version-info.xml" xpointer="v255"/></listitem> @@ -178,7 +178,7 @@ <term><filename>700-action-efi-exit-boot-services.pcrlock</filename></term> <listitem><para>The EFI action generated when <function>ExitBootServices()</function> 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.</para> <xi:include href="version-info.xml" xpointer="v255"/></listitem> 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 / \ <para>The system default for this setting may be controlled with <varname>DefaultIPAccounting=</varname> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + <para>Note that this functionality is currently only available for system services, not for + per-user services.</para> + <xi:include href="version-info.xml" xpointer="v235"/> </listitem> </varlistentry> @@ -865,8 +868,10 @@ CPUWeight=20 DisableControllers=cpu / \ <term><varname>SocketBindDeny=<replaceable>bind-rule</replaceable></varname></term> <listitem> - <para>Allow or deny binding a socket address to a socket by matching it with the <replaceable>bind-rule</replaceable> and - applying a corresponding action if there is a match.</para> + <para>Configures restrictions on the ability of unit processes to invoke <citerefentry + project='man-pages'><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry> on a + socket. Both allow and deny rules may defined that restrict which addresses a socket may be bound + to.</para> <para><replaceable>bind-rule</replaceable> describes socket properties such as <replaceable>address-family</replaceable>, <replaceable>transport-protocol</replaceable> and <replaceable>ip-ports</replaceable>.</para> @@ -913,6 +918,13 @@ CPUWeight=20 DisableControllers=cpu / \ </itemizedlist> <para>The feature is implemented with <constant>cgroup/bind4</constant> and <constant>cgroup/bind6</constant> cgroup-bpf hooks.</para> + + <para>Note that these settings apply to any <citerefentry + project='man-pages'><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry> + 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 <function>bind()</function>.</para> + <para>Examples:<programlisting>… # 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 @@ <row> <entry><literal>:</literal></entry> - <entry>If the executable path is prefixed with <literal>:</literal>, environment variable substitution (as described by the "Command Lines" section below) is not applied.</entry> + <entry>If the executable path is prefixed with <literal>:</literal>, environment variable substitution (as described below this table) is not applied.</entry> </row> <row> @@ -1719,7 +1719,7 @@ SystemdService=simple-dbus-service.service</programlisting> 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</programlisting> <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details on how you can influence the way systemd terminates the service.</para> + + <para>To avoid code duplication, it is preferable to use + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + when possible, especially when other APIs provided by + <citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry> are + also used, but note that the notification protocol is very simple and guaranteed to be stable as per + the <ulink url="https://systemd.io/PORTABILITY_AND_STABILITY/">Interface Portability and Stability + Promise</ulink>, so it can be reimplemented by services with no external dependencies. For a + self-contained example, see + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> </example> </refsect1> 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 @@ <varlistentry> <term><varname>TCPCongestion=</varname></term> <listitem><para>Takes a string value. Controls the TCP congestion algorithm used by this - socket. Should be one of <literal>westwood</literal>, <literal>veno</literal>, + socket. Should be one of <literal>westwood</literal>, <literal>reno</literal>, <literal>cubic</literal>, <literal>lp</literal> or any other available algorithm supported by the IP stack. This setting applies only to stream sockets.</para></listitem> </varlistentry> 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 @@ <listitem><para>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 - <literal>uki,1,UKI,uki,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html</literal> - will be used, to ensure it is always possible to revoke UKIs and addons. For more information on + <literal>uki,1,UKI,uki,1,https://uapi-group.org/specifications/specs/unified_kernel_image/</literal> + for UKIs and + <literal>uki-addon,1,UKI Addon,addon,1,https://www.freedesktop.org/software/systemd/man/latest/systemd-stub.html</literal> + for addons will be used, to ensure it is always possible to revoke them. For more information on SBAT see <ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">Shim documentation</ulink>. </para> @@ -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 </programlisting> 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 @@ <arg choice="plain">call</arg> <arg choice="plain"><replaceable>ADDRESS</replaceable></arg> <arg choice="plain"><replaceable>METHOD</replaceable></arg> - <arg choice="opt"><replaceable>PARAMETERS</replaceable></arg> + <arg choice="opt"><replaceable>ARGUMENTS</replaceable></arg> </cmdsynopsis> <cmdsynopsis> @@ -100,7 +100,7 @@ <term><command>info</command> <replaceable>ADDRESS</replaceable></term> <listitem><para>Show brief information about the specified service, including vendor name and list of - implemented interfaces. Expects a service address in the formats described above.</para> + implemented interfaces. Expects a service address in one of the formats described above.</para> <xi:include href="version-info.xml" xpointer="v255"/></listitem> </varlistentry> @@ -109,7 +109,7 @@ <term><command>list-interfaces</command> <replaceable>ADDRESS</replaceable></term> <listitem><para>Show list of interfaces implemented by the specified service. Expects a service - address in the formats described above.</para> + address in one of the formats described above.</para> <xi:include href="version-info.xml" xpointer="v255"/></listitem> </varlistentry> @@ -118,7 +118,7 @@ <term><command>introspect</command> <replaceable>ADDRESS</replaceable> <replaceable>INTERFACE</replaceable></term> <listitem><para>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.</para> <xi:include href="version-info.xml" xpointer="v255"/></listitem> |