diff options
Diffstat (limited to 'man')
44 files changed, 1465 insertions, 447 deletions
diff --git a/man/bootctl.xml b/man/bootctl.xml index a6f1fc1c4c..5f98486343 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -305,6 +305,8 @@ switch of the same name.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="image-policy-open" /> + <varlistentry> <term><option>--install-source=</option></term> <listitem><para>When installing binaries with <option>--root=</option> or diff --git a/man/common-variables.xml b/man/common-variables.xml index 0e220b3f9e..81425e57e2 100644 --- a/man/common-variables.xml +++ b/man/common-variables.xml @@ -81,6 +81,14 @@ </listitem> </varlistentry> + <varlistentry id='log-ratelimit-kmsg'> + <term><varname>$SYSTEMD_LOG_RATELIMIT_KMSG</varname></term> + + <listitem><para id='log-ratelimit-kmsg-body'> Whether to ratelimit kmsg or not. Takes a boolean. + Defaults to <literal>true</literal>. If disabled, systemd will not ratelimit messages written to kmsg. + </para></listitem> + </varlistentry> + <varlistentry id='pager'> <term><varname>$SYSTEMD_PAGER</varname></term> diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml index 79632eb2d4..0f4a2e83e6 100644 --- a/man/coredumpctl.xml +++ b/man/coredumpctl.xml @@ -268,6 +268,8 @@ switch of the same name.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="image-policy-open" /> + <varlistentry> <term><option>-q</option></term> <term><option>--quiet</option></term> diff --git a/man/custom-entities.ent.in b/man/custom-entities.ent.in index 0376e0feb9..aa0e1ef1ae 100644 --- a/man/custom-entities.ent.in +++ b/man/custom-entities.ent.in @@ -17,5 +17,5 @@ <!ENTITY DEFAULT_DNS_OVER_TLS_MODE "{{DEFAULT_DNS_OVER_TLS_MODE_STR}}"> <!ENTITY DEFAULT_TIMEOUT "{{DEFAULT_TIMEOUT_SEC}} s"> <!ENTITY DEFAULT_USER_TIMEOUT "{{DEFAULT_USER_TIMEOUT_SEC}} s"> -<!ENTITY fedora_latest_version "36"> -<!ENTITY fedora_cloud_release "1.5"> +<!ENTITY fedora_latest_version "37"> +<!ENTITY fedora_cloud_release "1.7"> diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml index 4961f019f0..9e91af9060 100644 --- a/man/file-hierarchy.xml +++ b/man/file-hierarchy.xml @@ -737,7 +737,7 @@ </row> <row> <entry><filename>/var/log/<replaceable>package</replaceable>/</filename></entry> - <entry>Persistent log data of the package. As above, the package should make sure to create this directory if necessary, possibly using <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> or <varname>LogsDirectory=</varname> (see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>), as it might be missing.</entry> + <entry>Persistent log data of the package. As above, the package should make sure to create this directory if necessary, possibly using <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> or <varname>LogsDirectory=</varname> (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>), as it might be missing.</entry> </row> <row> <entry><filename>/var/spool/<replaceable>package</replaceable>/</filename></entry> diff --git a/man/iocost.conf.xml b/man/iocost.conf.xml new file mode 100644 index 0000000000..be74244267 --- /dev/null +++ b/man/iocost.conf.xml @@ -0,0 +1,76 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="iocost.conf" xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>iocost.conf</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>iocost.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>iocost.conf</refname> + <refpurpose>Configuration files for the iocost solution manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para> + <filename>/etc/systemd/iocost.conf</filename> + <filename>/etc/systemd/iocost.conf.d/*.conf</filename> + </para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>This file configures the behavior of <literal>iocost</literal>, a tool mostly used by + <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry> rules + to automatically apply I/O cost solutions to <filename>/sys/fs/cgroup/io.cost.*</filename>.</para> + + <para>The qos and model values are calculated based on benchmarks collected on the + <ulink url="https://github.com/iocost-benchmark/iocost-benchmarks">iocost-benchmark</ulink> + project and turned into a set of solutions that go from most to least isolated. + Isolation allows the system to remain responsive in face of high I/O load. + Which solutions are available for a device can be queried from the udev metadata attached to it. By + default the naive solution is used, which provides the most bandwidth.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the [IOCost] section:</para> + + <variablelist class='config-directives'> + + <varlistentry> + <term><varname>TargetSolution=</varname></term> + + <listitem><para>Chooses which I/O cost solution (identified by named string) should be used + for the devices in this system. The known solutions can be queried from the udev metadata + attached to the devices. If a device does not have the specified solution, the first one + listed in <varname>IOCOST_SOLUTIONS</varname> is used instead.</para> + + <para>E.g. <literal>TargetSolution=isolated-bandwidth</literal>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <ulink url="https://github.com/iocost-benchmark/iocost-benchmarks">The iocost-benchmarks github project</ulink>, + <ulink url="https://github.com/facebookexperimental/resctl-demo/tree/main/resctl-bench/doc">The resctl-bench + documentation details how the values are obtained</ulink> + </para> + </refsect1> + +</refentry> diff --git a/man/journalctl.xml b/man/journalctl.xml index ae86c50d62..aa124dd98f 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -182,6 +182,8 @@ switch of the same name.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="image-policy-open" /> + <varlistentry> <term><option>--namespace=<replaceable>NAMESPACE</replaceable></option></term> diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index 6f026318d8..09f8ace4de 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -66,6 +66,7 @@ <term><varname>systemd.log_level=</varname></term> <term><varname>systemd.log_location=</varname></term> <term><varname>systemd.log_color</varname></term> + <term><varname>systemd.log_ratelimit_kmsg</varname></term> <term><varname>systemd.default_standard_output=</varname></term> <term><varname>systemd.default_standard_error=</varname></term> <term><varname>systemd.setenv=</varname></term> @@ -396,13 +397,23 @@ <term><varname>rd.systemd.gpt_auto=</varname></term> <listitem> - <para>Configures whether GPT based partition auto-discovery - shall be attempted. For details, see + <para>Configures whether GPT-based partition auto-discovery shall be attempted. For details, see <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> + <term><varname>systemd.image_policy=</varname></term> + <term><varname>rd.systemd.image_policy=</varname></term> + + <listitem><para>When GPT-based partition auto-discovery is used, configures the image dissection + policy string to apply, as per + <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. For + details see + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>systemd.default_timeout_start_sec=</varname></term> <listitem> diff --git a/man/logcontrol-example.c b/man/logcontrol-example.c new file mode 100644 index 0000000000..734318da93 --- /dev/null +++ b/man/logcontrol-example.c @@ -0,0 +1,232 @@ +/* SPDX-License-Identifier: MIT-0 */ + +/* Implements the LogControl1 interface as per specification: + * https://www.freedesktop.org/software/systemd/man/org.freedesktop.LogControl1.html + * + * Compile with 'cc logcontrol-example.c $(pkg-config --libs --cflags libsystemd)' + * + * To get and set properties via busctl: + * + * $ busctl --user get-property org.freedesktop.Example \ + * /org/freedesktop/LogControl1 \ + * org.freedesktop.LogControl1 \ + * SyslogIdentifier + * s "example" + * $ busctl --user get-property org.freedesktop.Example \ + * /org/freedesktop/LogControl1 \ + * org.freedesktop.LogControl1 \ + * LogTarget + * s "journal" + * $ busctl --user get-property org.freedesktop.Example \ + * /org/freedesktop/LogControl1 \ + * org.freedesktop.LogControl1 \ + * LogLevel + * s "info" + * $ busctl --user set-property org.freedesktop.Example \ + * /org/freedesktop/LogControl1 \ + * org.freedesktop.LogControl1 \ + * LogLevel \ + * "s" debug + * $ busctl --user get-property org.freedesktop.Example \ + * /org/freedesktop/LogControl1 \ + * org.freedesktop.LogControl1 \ + * LogLevel + * s "debug" + */ + +#include <errno.h> +#include <stdlib.h> +#include <stdio.h> +#include <syslog.h> +#include <systemd/sd-bus.h> +#include <systemd/sd-journal.h> + +#define _cleanup_(f) __attribute__((cleanup(f))) + +#define check(log_level, x) ({ \ + int _r = (x); \ + errno = _r < 0 ? -_r : 0; \ + sd_journal_print((log_level), #x ": %m"); \ + if (_r < 0) \ + return EXIT_FAILURE; \ + }) + +typedef enum LogTarget { + LOG_TARGET_JOURNAL, + LOG_TARGET_KMSG, + LOG_TARGET_SYSLOG, + LOG_TARGET_CONSOLE, + _LOG_TARGET_MAX, +} LogTarget; + +static const char* const log_target_table[_LOG_TARGET_MAX] = { + [LOG_TARGET_JOURNAL] = "journal", + [LOG_TARGET_KMSG] = "kmsg", + [LOG_TARGET_SYSLOG] = "syslog", + [LOG_TARGET_CONSOLE] = "console", +}; + +static const char* const log_level_table[LOG_DEBUG + 1] = { + [LOG_EMERG] = "emerg", + [LOG_ALERT] = "alert", + [LOG_CRIT] = "crit", + [LOG_ERR] = "err", + [LOG_WARNING] = "warning", + [LOG_NOTICE] = "notice", + [LOG_INFO] = "info", + [LOG_DEBUG] = "debug", +}; + +typedef struct object { + const char *syslog_identifier; + LogTarget log_target; + int log_level; +} object; + +static int property_get( + sd_bus *bus, + const char *path, + const char *interface, + const char *property, + sd_bus_message *reply, + void *userdata, + sd_bus_error *error) { + + object *o = userdata; + + if (strcmp(property, "LogLevel") == 0) + return sd_bus_message_append(reply, "s", log_level_table[o->log_level]); + + if (strcmp(property, "LogTarget") == 0) + return sd_bus_message_append(reply, "s", log_target_table[o->log_target]); + + if (strcmp(property, "SyslogIdentifier") == 0) + return sd_bus_message_append(reply, "s", o->syslog_identifier); + + return sd_bus_error_setf(error, + SD_BUS_ERROR_UNKNOWN_PROPERTY, + "Unknown property '%s'", + property); +} + +static int property_set( + sd_bus *bus, + const char *path, + const char *interface, + const char *property, + sd_bus_message *message, + void *userdata, + sd_bus_error *error) { + + object *o = userdata; + const char *value; + int r; + + r = sd_bus_message_read(message, "s", &value); + if (r < 0) + return r; + + if (strcmp(property, "LogLevel") == 0) { + for (int i = 0; i < LOG_DEBUG + 1; i++) + if (strcmp(value, log_level_table[i]) == 0) { + o->log_level = i; + return 0; + } + + return sd_bus_error_setf(error, + SD_BUS_ERROR_INVALID_ARGS, + "Invalid value for LogLevel: '%s'", + value); + } + + if (strcmp(property, "LogTarget") == 0) { + for (LogTarget i = 0; i < _LOG_TARGET_MAX; i++) + if (strcmp(value, log_target_table[i]) == 0) { + o->log_target = i; + return 0; + } + + return sd_bus_error_setf(error, + SD_BUS_ERROR_INVALID_ARGS, + "Invalid value for LogTarget: '%s'", + value); + } + + return sd_bus_error_setf(error, + SD_BUS_ERROR_UNKNOWN_PROPERTY, + "Unknown property '%s'", + property); +} + +/* https://www.freedesktop.org/software/systemd/man/sd_bus_add_object.html + */ +static const sd_bus_vtable vtable[] = { + SD_BUS_VTABLE_START(0), + SD_BUS_WRITABLE_PROPERTY( + "LogLevel", "s", + property_get, property_set, + 0, + 0), + SD_BUS_WRITABLE_PROPERTY( + "LogTarget", "s", + property_get, property_set, + 0, + 0), + SD_BUS_PROPERTY( + "SyslogIdentifier", "s", + property_get, + 0, + SD_BUS_VTABLE_PROPERTY_CONST), + SD_BUS_VTABLE_END +}; + +int main(int argc, char **argv) { + /* The bus should be relinquished before the program terminates. The cleanup + * attribute allows us to do it nicely and cleanly whenever we exit the + * block. + */ + _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL; + + object o = { + .log_level = LOG_INFO, + .log_target = LOG_TARGET_JOURNAL, + .syslog_identifier = "example", + }; + + /* Acquire a connection to the bus, letting the library work out the details. + * https://www.freedesktop.org/software/systemd/man/sd_bus_default.html + */ + check(o.log_level, sd_bus_default(&bus)); + + /* Publish an interface on the bus, specifying our well-known object access + * path and public interface name. + * https://www.freedesktop.org/software/systemd/man/sd_bus_add_object.html + * https://dbus.freedesktop.org/doc/dbus-tutorial.html + */ + check(o.log_level, sd_bus_add_object_vtable(bus, NULL, + "/org/freedesktop/LogControl1", + "org.freedesktop.LogControl1", + vtable, + &o)); + + /* By default the service is assigned an ephemeral name. Also add a fixed + * one, so that clients know whom to call. + * https://www.freedesktop.org/software/systemd/man/sd_bus_request_name.html + */ + check(o.log_level, sd_bus_request_name(bus, "org.freedesktop.Example", 0)); + + for (;;) { + /* https://www.freedesktop.org/software/systemd/man/sd_bus_wait.html + */ + check(o.log_level, sd_bus_wait(bus, UINT64_MAX)); + /* https://www.freedesktop.org/software/systemd/man/sd_bus_process.html + */ + check(o.log_level, sd_bus_process(bus, NULL)); + } + + /* https://www.freedesktop.org/software/systemd/man/sd_bus_release_name.html + */ + check(o.log_level, sd_bus_release_name(bus, "org.freedesktop.Example")); + + return 0; +} diff --git a/man/networkctl.xml b/man/networkctl.xml index f67ad99adf..94ec3dc631 100644 --- a/man/networkctl.xml +++ b/man/networkctl.xml @@ -18,7 +18,7 @@ <refnamediv> <refname>networkctl</refname> - <refpurpose>Query the status of network links</refpurpose> + <refpurpose>Query or modify the status of network links</refpurpose> </refnamediv> <refsynopsisdiv> @@ -33,7 +33,7 @@ <refsect1> <title>Description</title> - <para><command>networkctl</command> may be used to introspect the + <para><command>networkctl</command> may be used to query or modify the state of the network links as seen by <command>systemd-networkd</command>. Please refer to <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> diff --git a/man/org.freedesktop.LogControl1.xml b/man/org.freedesktop.LogControl1.xml index da6dd7628e..1694453baf 100644 --- a/man/org.freedesktop.LogControl1.xml +++ b/man/org.freedesktop.LogControl1.xml @@ -117,6 +117,20 @@ node /org/freedesktop/LogControl1 { </refsect1> <refsect1> + <title>Example</title> + + <example> + <title>Create a simple listener on the bus that implements LogControl1</title> + + <programlisting><xi:include href="logcontrol-example.c" parse="text"/></programlisting> + + <para>This creates a simple server on the bus. It implements the LogControl1 interface by providing + the required properties and allowing to set the writable ones. It logs at the configured log level using + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </example> + </refsect1> + + <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml index 50680e6b37..e462c60636 100644 --- a/man/org.freedesktop.systemd1.xml +++ b/man/org.freedesktop.systemd1.xml @@ -2501,7 +2501,7 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { condition is a trigger condition, whether the condition is reversed, the right hand side of the condition (e.g. the path in case of <varname>ConditionPathExists</varname>), and the status. The status can be 0, in which case the condition hasn't been checked yet, a positive value, in which case the - condition passed, or a negative value, in which case the condition failed. Currently only 0, +1, and -1 + condition passed, or a negative value, in which case the condition is not met. Currently only 0, +1, and -1 are used, but additional values may be used in the future, retaining the meaning of zero/positive/negative values.</para> @@ -2619,6 +2619,8 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { readonly u FileDescriptorStoreMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u NFileDescriptorStore = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s FileDescriptorStorePreserve = '...'; readonly s StatusText = '...'; readonly i StatusErrno = ...; readonly s Result = '...'; @@ -3167,6 +3169,12 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IPCNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RootImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s MountImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s ExtensionImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @@ -3238,6 +3246,8 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { <!--property NFileDescriptorStore is not documented!--> + <!--property FileDescriptorStorePreserve is not documented!--> + <!--property StatusErrno is not documented!--> <!--property ReloadResult is not documented!--> @@ -3724,6 +3734,12 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { <!--property IPCNamespacePath is not documented!--> + <!--property RootImagePolicy is not documented!--> + + <!--property MountImagePolicy is not documented!--> + + <!--property ExtensionImagePolicy is not documented!--> + <!--property KillMode is not documented!--> <!--property KillSignal is not documented!--> @@ -3818,6 +3834,8 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { <variablelist class="dbus-property" generated="True" extra-ref="NFileDescriptorStore"/> + <variablelist class="dbus-property" generated="True" extra-ref="FileDescriptorStorePreserve"/> + <variablelist class="dbus-property" generated="True" extra-ref="StatusText"/> <variablelist class="dbus-property" generated="True" extra-ref="StatusErrno"/> @@ -4380,6 +4398,12 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { <variablelist class="dbus-property" generated="True" extra-ref="IPCNamespacePath"/> + <variablelist class="dbus-property" generated="True" extra-ref="RootImagePolicy"/> + + <variablelist class="dbus-property" generated="True" extra-ref="MountImagePolicy"/> + + <variablelist class="dbus-property" generated="True" extra-ref="ExtensionImagePolicy"/> + <variablelist class="dbus-property" generated="True" extra-ref="KillMode"/> <variablelist class="dbus-property" generated="True" extra-ref="KillSignal"/> @@ -5147,6 +5171,12 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IPCNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RootImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s MountImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s ExtensionImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @@ -5718,6 +5748,12 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { <!--property IPCNamespacePath is not documented!--> + <!--property RootImagePolicy is not documented!--> + + <!--property MountImagePolicy is not documented!--> + + <!--property ExtensionImagePolicy is not documented!--> + <!--property KillMode is not documented!--> <!--property KillSignal is not documented!--> @@ -6356,6 +6392,12 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { <variablelist class="dbus-property" generated="True" extra-ref="IPCNamespacePath"/> + <variablelist class="dbus-property" generated="True" extra-ref="RootImagePolicy"/> + + <variablelist class="dbus-property" generated="True" extra-ref="MountImagePolicy"/> + + <variablelist class="dbus-property" generated="True" extra-ref="ExtensionImagePolicy"/> + <variablelist class="dbus-property" generated="True" extra-ref="KillMode"/> <variablelist class="dbus-property" generated="True" extra-ref="KillSignal"/> @@ -7002,6 +7044,12 @@ node /org/freedesktop/systemd1/unit/home_2emount { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IPCNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RootImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s MountImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s ExtensionImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @@ -7501,6 +7549,12 @@ node /org/freedesktop/systemd1/unit/home_2emount { <!--property IPCNamespacePath is not documented!--> + <!--property RootImagePolicy is not documented!--> + + <!--property MountImagePolicy is not documented!--> + + <!--property ExtensionImagePolicy is not documented!--> + <!--property KillMode is not documented!--> <!--property KillSignal is not documented!--> @@ -8057,6 +8111,12 @@ node /org/freedesktop/systemd1/unit/home_2emount { <variablelist class="dbus-property" generated="True" extra-ref="IPCNamespacePath"/> + <variablelist class="dbus-property" generated="True" extra-ref="RootImagePolicy"/> + + <variablelist class="dbus-property" generated="True" extra-ref="MountImagePolicy"/> + + <variablelist class="dbus-property" generated="True" extra-ref="ExtensionImagePolicy"/> + <variablelist class="dbus-property" generated="True" extra-ref="KillMode"/> <variablelist class="dbus-property" generated="True" extra-ref="KillSignal"/> @@ -8830,6 +8890,12 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IPCNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RootImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s MountImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s ExtensionImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @@ -9315,6 +9381,12 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { <!--property IPCNamespacePath is not documented!--> + <!--property RootImagePolicy is not documented!--> + + <!--property MountImagePolicy is not documented!--> + + <!--property ExtensionImagePolicy is not documented!--> + <!--property KillMode is not documented!--> <!--property KillSignal is not documented!--> @@ -9857,6 +9929,12 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { <variablelist class="dbus-property" generated="True" extra-ref="IPCNamespacePath"/> + <variablelist class="dbus-property" generated="True" extra-ref="RootImagePolicy"/> + + <variablelist class="dbus-property" generated="True" extra-ref="MountImagePolicy"/> + + <variablelist class="dbus-property" generated="True" extra-ref="ExtensionImagePolicy"/> + <variablelist class="dbus-property" generated="True" extra-ref="KillMode"/> <variablelist class="dbus-property" generated="True" extra-ref="KillSignal"/> diff --git a/man/os-release.xml b/man/os-release.xml index e74f27b990..6cc786acf9 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -443,6 +443,17 @@ </varlistentry> <varlistentry> + <term><varname>CONFEXT_LEVEL=</varname></term> + + <listitem><para>Semantically the same as <varname>SYSEXT_LEVEL=</varname> but for confext images. + See <filename>/etc/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename> + for more information.</para> + + <para>Examples: <literal>CONFEXT_LEVEL=2</literal>, <literal>CONFEXT_LEVEL=15.14</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> <term><varname>SYSEXT_SCOPE=</varname></term> <listitem><para>Takes a space-separated list of one or more of the strings <literal>system</literal>, <literal>initrd</literal> and <literal>portable</literal>. This field is @@ -454,6 +465,12 @@ </varlistentry> <varlistentry> + <term><varname>CONFEXT_SCOPE=</varname></term> + + <listitem><para>Semantically the same as <varname>SYSEXT_SCOPE=</varname> but for confext images.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>PORTABLE_PREFIXES=</varname></term> <listitem><para>Takes a space-separated list of one or more valid prefix match strings for the <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services Documentation</ulink> logic. diff --git a/man/rules/meson.build b/man/rules/meson.build index 63a68c3211..ca3b471281 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -24,6 +24,7 @@ manpages = [ ['hostnamectl', '1', [], 'ENABLE_HOSTNAMED'], ['hwdb', '7', [], 'ENABLE_HWDB'], ['integritytab', '5', [], 'HAVE_LIBCRYPTSETUP'], + ['iocost.conf', '5', [], ''], ['journal-remote.conf', '5', ['journal-remote.conf.d'], 'HAVE_MICROHTTPD'], ['journal-upload.conf', '5', ['journal-upload.conf.d'], 'HAVE_MICROHTTPD'], ['journalctl', '1', [], ''], @@ -1043,7 +1044,10 @@ manpages = [ 'systemd-suspend-then-hibernate.service'], ''], ['systemd-sysctl.service', '8', ['systemd-sysctl'], ''], - ['systemd-sysext', '8', ['systemd-sysext.service'], ''], + ['systemd-sysext', + '8', + ['systemd-confext', 'systemd-confext.service', 'systemd-sysext.service'], + ''], ['systemd-system-update-generator', '8', [], ''], ['systemd-system.conf', '5', @@ -1104,6 +1108,7 @@ manpages = [ ['systemd.environment-generator', '7', [], 'ENABLE_ENVIRONMENT_D'], ['systemd.exec', '5', [], ''], ['systemd.generator', '7', [], ''], + ['systemd.image-policy', '7', [], ''], ['systemd.journal-fields', '7', [], ''], ['systemd.kill', '5', [], ''], ['systemd.link', '5', [], ''], diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml index 48d9c9a108..8be4254be1 100644 --- a/man/sd_bus_default.xml +++ b/man/sd_bus_default.xml @@ -110,13 +110,14 @@ <title>Description</title> <para><function>sd_bus_default()</function> acquires a bus - connection object to the user bus when invoked in user context, or - to the system bus otherwise. The connection object is associated - with the calling thread. Each time the function is invoked from - the same thread, the same object is returned, but its reference - count is increased by one, as long as at least one reference is - kept. When the last reference to the connection is dropped (using - the + connection object to the user bus when invoked from within a user + slice (any session under <literal>user-*.slice</literal>, e.g.: + <literal>user@1000.service</literal>), or to the system bus + otherwise. The connection object is associated with the calling + thread. Each time the function is invoked from the same thread, + the same object is returned, but its reference count is increased + by one, as long as at least one reference is kept. When the last + reference to the connection is dropped (using the <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> call), the connection is terminated. Note that the connection is not automatically terminated when the associated thread ends. It diff --git a/man/sd_notify.xml b/man/sd_notify.xml index cb07add95e..f93542e329 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -77,25 +77,20 @@ <refsect1> <title>Description</title> - <para><function>sd_notify()</function> may be called by a service - to notify the service manager about state changes. It can be used - to send arbitrary information, encoded in an - environment-block-like string. Most importantly, it can be used for - start-up completion notification.</para> - - <para>If the <parameter>unset_environment</parameter> parameter is - non-zero, <function>sd_notify()</function> will unset the - <varname>$NOTIFY_SOCKET</varname> environment variable before - returning (regardless of whether the function call itself - succeeded or not). Further calls to - <function>sd_notify()</function> will then fail, but the variable - is no longer inherited by child processes.</para> - - <para>The <parameter>state</parameter> parameter should contain a - newline-separated list of variable assignments, similar in style - to an environment block. A trailing newline is implied if none is - specified. The string may contain any kind of variable - assignments, but the following shall be considered + + <para><function>sd_notify()</function> may be called by a service to notify the service manager about + state changes. It can be used to send arbitrary information, encoded in an environment-block-like + string. Most importantly, it can be used for start-up completion notification.</para> + + <para>If the <parameter>unset_environment</parameter> parameter is non-zero, + <function>sd_notify()</function> will unset the <varname>$NOTIFY_SOCKET</varname> environment variable + before returning (regardless of whether the function call itself succeeded or not). Further calls to + <function>sd_notify()</function> will then fail, but the variable is no longer inherited by child + processes.</para> + + <para>The <parameter>state</parameter> parameter should contain a newline-separated list of variable + assignments, similar in style to an environment block. A trailing newline is implied if none is + specified. The string may contain any kind of variable assignments, but the following shall be considered well-known:</para> <variablelist> @@ -136,159 +131,167 @@ <varlistentry> <term>STOPPING=1</term> - <listitem><para>Tells the service manager that the service is - beginning its shutdown. This is useful to allow the service - manager to track the service's internal state, and present it - to the user.</para></listitem> + <listitem><para>Tells the service manager that the service is beginning its shutdown. This is useful + to allow the service manager to track the service's internal state, and present it to the + user.</para></listitem> </varlistentry> <varlistentry> <term>STATUS=…</term> - <listitem><para>Passes a single-line UTF-8 status string back - to the service manager that describes the service state. This - is free-form and can be used for various purposes: general - state feedback, fsck-like programs could pass completion - percentages and failing programs could pass a human-readable - error message. Example: <literal>STATUS=Completed 66% of file - system check…</literal></para></listitem> + <listitem><para>Passes a single-line UTF-8 status string back to the service manager that describes + the service state. This is free-form and can be used for various purposes: general state feedback, + fsck-like programs could pass completion percentages and failing programs could pass a human-readable + error message. Example: <literal>STATUS=Completed 66% of file system + check…</literal></para></listitem> </varlistentry> <varlistentry> <term>NOTIFYACCESS=…</term> - <listitem><para>Reset the access to the service status notification - socket during runtime, overriding <varname>NotifyAccess=</varname> setting - in the service unit file. See <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details, specifically <literal>NotifyAccess=</literal> for a list of - accepted values.</para></listitem> + <listitem><para>Reset the access to the service status notification socket during runtime, overriding + <varname>NotifyAccess=</varname> setting in the service unit file. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details, specifically <literal>NotifyAccess=</literal> for a list of accepted + values.</para></listitem> </varlistentry> <varlistentry> <term>ERRNO=…</term> - <listitem><para>If a service fails, the errno-style error - code, formatted as string. Example: <literal>ERRNO=2</literal> - for ENOENT.</para></listitem> + <listitem><para>If a service fails, the errno-style error code, formatted as string. Example: + <literal>ERRNO=2</literal> for ENOENT.</para></listitem> </varlistentry> <varlistentry> <term>BUSERROR=…</term> - <listitem><para>If a service fails, the D-Bus error-style - error code. Example: + <listitem><para>If a service fails, the D-Bus error-style error code. Example: <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem> </varlistentry> <varlistentry> + <term>EXIT_STATUS=…</term> + + <listitem><para>If a service exits, the return value of its <function>main()</function> function. + </para></listitem> + </varlistentry> + + <varlistentry> <term>MAINPID=…</term> - <listitem><para>The main process ID (PID) of the service, in - case the service manager did not fork off the process itself. - Example: <literal>MAINPID=4711</literal></para></listitem> + <listitem><para>The main process ID (PID) of the service, in case the service manager did not fork + off the process itself. Example: <literal>MAINPID=4711</literal></para></listitem> </varlistentry> <varlistentry> <term>WATCHDOG=1</term> - <listitem><para>Tells the service manager to update the - watchdog timestamp. This is the keep-alive ping that services - need to issue in regular intervals if - <varname>WatchdogSec=</varname> is enabled for it. See + <listitem><para>Tells the service manager to update the watchdog timestamp. This is the keep-alive + ping that services need to issue in regular intervals if <varname>WatchdogSec=</varname> is enabled + for it. See <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for information how to enable this functionality and <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for the details of how the service can check whether the - watchdog is enabled. </para></listitem> + for the details of how the service can check whether the watchdog is enabled. </para></listitem> </varlistentry> <varlistentry> <term>WATCHDOG=trigger</term> - <listitem><para>Tells the service manager that the service detected an internal error that should be handled by - the configured watchdog options. This will trigger the same behaviour as if <varname>WatchdogSec=</varname> is - enabled and the service did not send <literal>WATCHDOG=1</literal> in time. Note that - <varname>WatchdogSec=</varname> does not need to be enabled for <literal>WATCHDOG=trigger</literal> to trigger - the watchdog action. See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for - information about the watchdog behavior. </para></listitem> + <listitem><para>Tells the service manager that the service detected an internal error that should be + handled by the configured watchdog options. This will trigger the same behaviour as if + <varname>WatchdogSec=</varname> is enabled and the service did not send <literal>WATCHDOG=1</literal> + in time. Note that <varname>WatchdogSec=</varname> does not need to be enabled for + <literal>WATCHDOG=trigger</literal> to trigger the watchdog action. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the watchdog behavior. </para></listitem> </varlistentry> <varlistentry> <term>WATCHDOG_USEC=…</term> - <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime. - Notice that this is not available when using <function>sd_event_set_watchdog()</function> - or <function>sd_watchdog_enabled()</function>. - Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem> + <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime. Notice that this is not + available when using <function>sd_event_set_watchdog()</function> or + <function>sd_watchdog_enabled()</function>. Example : + <literal>WATCHDOG_USEC=20000000</literal></para></listitem> </varlistentry> <varlistentry> <term>EXTEND_TIMEOUT_USEC=…</term> <listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout - corresponding the current state. The value specified is a time in microseconds during which the service must - send a new message. A service timeout will occur if the message isn't received, but only if the runtime of the - current state is beyond the original maximum times of <varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>, - and <varname>TimeoutStopSec=</varname>. - See <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + corresponding the current state. The value specified is a time in microseconds during which the + service must send a new message. A service timeout will occur if the message isn't received, but only + if the runtime of the current state is beyond the original maximum times of + <varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>, and + <varname>TimeoutStopSec=</varname>. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for effects on the service timeouts.</para></listitem> </varlistentry> <varlistentry> <term>FDSTORE=1</term> - <listitem><para>Stores additional file descriptors in the service manager. File descriptors sent this way will - be maintained per-service by the service manager and will later be handed back using the usual file descriptor - passing logic at the next invocation of the service (e.g. when it is restarted), see - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This is - useful for implementing services that can restart after an explicit request or a crash without losing - state. Any open sockets and other file descriptors which should not be closed during the restart may be stored - this way. Application state can either be serialized to a file in <filename>/run/</filename>, or better, stored - in a <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory - file descriptor. Note that the service manager will accept messages for a service only if its + <listitem><para>Stores additional file descriptors in the service manager. File descriptors sent this + way will be maintained per-service by the service manager and will later be handed back using the + usual file descriptor passing logic at the next invocation of the service (e.g. when it is + restarted), see + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This is useful for implementing services that can restart after an explicit request or a crash + without losing state. Any open sockets and other file descriptors which should not be closed during + the restart may be stored this way. Application state can either be serialized to a file in + <filename>/run/</filename>, or better, stored in a + <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> + memory file descriptor. Note that the service manager will accept messages for a service only if its <varname>FileDescriptorStoreMax=</varname> setting is non-zero (defaults to zero, see <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If <varname>FDPOLL=0</varname> is not set and the file descriptors sent are pollable (see - <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then any - <constant>EPOLLHUP</constant> or <constant>EPOLLERR</constant> event seen on them will result in their - automatic removal from the store. Multiple arrays of file descriptors may be sent in separate messages, in - which case the arrays are combined. Note that the service manager removes duplicate (pointing to the same - object) file descriptors before passing them to the service. When a service is stopped, its file descriptor - store is discarded and all file descriptors in it are closed. Use <function>sd_pid_notify_with_fds()</function> - to send messages with <literal>FDSTORE=1</literal>, see below.</para></listitem> + <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then + any <constant>EPOLLHUP</constant> or <constant>EPOLLERR</constant> event seen on them will result in + their automatic removal from the store. Multiple arrays of file descriptors may be sent in separate + messages, in which case the arrays are combined. Note that the service manager removes duplicate + (pointing to the same object) file descriptors before passing them to the service. When a service is + stopped, its file descriptor store is discarded and all file descriptors in it are closed. Use + <function>sd_pid_notify_with_fds()</function> to send messages with <literal>FDSTORE=1</literal>, see + below. The service manager will set the <varname>$FDSTORE</varname> environment variable for services + that have the file descriptor store enabled.</para></listitem> </varlistentry> <varlistentry> <term>FDSTOREREMOVE=1</term> - <listitem><para>Removes file descriptors from the file descriptor store. This field needs to be combined with - <varname>FDNAME=</varname> to specify the name of the file descriptors to remove.</para></listitem> + <listitem><para>Removes file descriptors from the file descriptor store. This field needs to be + combined with <varname>FDNAME=</varname> to specify the name of the file descriptors to + remove.</para></listitem> </varlistentry> <varlistentry> <term>FDNAME=…</term> - <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, specifies a name for the submitted - file descriptors. When used with <varname>FDSTOREREMOVE=1</varname>, specifies the name for the file - descriptors to remove. This name is passed to the service during activation, and may be queried using + <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, specifies a name for the + submitted file descriptors. When used with <varname>FDSTOREREMOVE=1</varname>, specifies the name for + the file descriptors to remove. This name is passed to the service during activation, and may be + queried using <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File descriptors submitted without this field set, will implicitly get the name <literal>stored</literal> - assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be assigned to - all of them. In order to assign different names to submitted file descriptors, submit them in separate - invocations of <function>sd_pid_notify_with_fds()</function>. The name may consist of arbitrary ASCII - characters except control characters or <literal>:</literal>. It may not be longer than 255 characters. If a - submitted name does not follow these restrictions, it is ignored.</para></listitem> + assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be + assigned to all of them. In order to assign different names to submitted file descriptors, submit + them in separate invocations of <function>sd_pid_notify_with_fds()</function>. The name may consist + of arbitrary ASCII characters except control characters or <literal>:</literal>. It may not be longer + than 255 characters. If a submitted name does not follow these restrictions, it is + ignored.</para></listitem> </varlistentry> <varlistentry> <term>FDPOLL=0</term> - <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, disables polling of the stored - file descriptors regardless of whether or not they are pollable. As this option disables automatic cleanup - of the stored file descriptors on EPOLLERR and EPOLLHUP, care must be taken to ensure proper manual cleanup. - Use of this option is not generally recommended except for when automatic cleanup has unwanted behavior such - as prematurely discarding file descriptors from the store.</para></listitem> + <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, disables polling of the + stored file descriptors regardless of whether or not they are pollable. As this option disables + automatic cleanup of the stored file descriptors on EPOLLERR and EPOLLHUP, care must be taken to + ensure proper manual cleanup. Use of this option is not generally recommended except for when + automatic cleanup has unwanted behavior such as prematurely discarding file descriptors from the + store.</para></listitem> </varlistentry> <varlistentry> @@ -305,23 +308,22 @@ </varlistentry> </variablelist> - <para>It is recommended to prefix variable names that are not - listed above with <varname>X_</varname> to avoid namespace - clashes.</para> - - <para>Note that systemd will accept status data sent from a - service only if the <varname>NotifyAccess=</varname> option is - correctly set in the service definition file. See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - - <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either - the sending process is still around at the time PID 1 processes the message, or if the sending process is - explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked - off the process, i.e. on all processes that match <varname>NotifyAccess=</varname><option>main</option> or - <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an - <function>sd_notify()</function> message and immediately exits, the service manager might not be able to properly - attribute the message to the unit, and thus will ignore it, even if + <para>It is recommended to prefix variable names that are not listed above with <varname>X_</varname> to + avoid namespace clashes.</para> + + <para>Note that systemd will accept status data sent from a service only if the + <varname>NotifyAccess=</varname> option is correctly set in the service definition file. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details.</para> + + <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only + if either the sending process is still around at the time PID 1 processes the message, or if the sending + process is explicitly runtime-tracked by the service manager. The latter is the case if the service + manager originally forked off the process, i.e. on all processes that match + <varname>NotifyAccess=</varname><option>main</option> or + <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit + sends an <function>sd_notify()</function> message and immediately exits, the service manager might not be + able to properly attribute the message to the unit, and thus will ignore it, even if <varname>NotifyAccess=</varname><option>all</option> is set for it.</para> <para>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications @@ -331,41 +333,28 @@ service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the unit.</para> - <para><function>sd_notifyf()</function> is similar to - <function>sd_notify()</function> but takes a - <function>printf()</function>-like format string plus - arguments.</para> - - <para><function>sd_pid_notify()</function> and - <function>sd_pid_notifyf()</function> are similar to - <function>sd_notify()</function> and - <function>sd_notifyf()</function> but take a process ID (PID) to - use as originating PID for the message as first argument. This is - useful to send notification messages on behalf of other processes, - provided the appropriate privileges are available. If the PID - argument is specified as 0, the process ID of the calling process - is used, in which case the calls are fully equivalent to - <function>sd_notify()</function> and - <function>sd_notifyf()</function>.</para> - - <para><function>sd_pid_notify_with_fds()</function> is similar to - <function>sd_pid_notify()</function> but takes an additional array - of file descriptors. These file descriptors are sent along the - notification message to the service manager. This is particularly - useful for sending <literal>FDSTORE=1</literal> messages, as - described above. The additional arguments are a pointer to the - file descriptor array plus the number of file descriptors in the - array. If the number of file descriptors is passed as 0, the call - is fully equivalent to <function>sd_pid_notify()</function>, i.e. - no file descriptors are passed. Note that sending file descriptors - to the service manager on messages that do not expect them (i.e. - without <literal>FDSTORE=1</literal>) they are immediately closed - on reception.</para> - - <para><function>sd_notify_barrier()</function> allows the caller to - synchronize against reception of previously sent notification messages - and uses the <varname>BARRIER=1</varname> command. It takes a relative - <varname>timeout</varname> value in microseconds which is passed to + <para><function>sd_notifyf()</function> is similar to <function>sd_notify()</function> but takes a + <function>printf()</function>-like format string plus arguments.</para> + + <para><function>sd_pid_notify()</function> and <function>sd_pid_notifyf()</function> are similar to + <function>sd_notify()</function> and <function>sd_notifyf()</function> but take a process ID (PID) to use + as originating PID for the message as first argument. This is useful to send notification messages on + behalf of other processes, provided the appropriate privileges are available. If the PID argument is + specified as 0, the process ID of the calling process is used, in which case the calls are fully + equivalent to <function>sd_notify()</function> and <function>sd_notifyf()</function>.</para> + + <para><function>sd_pid_notify_with_fds()</function> is similar to <function>sd_pid_notify()</function> + but takes an additional array of file descriptors. These file descriptors are sent along the notification + message to the service manager. This is particularly useful for sending <literal>FDSTORE=1</literal> + messages, as described above. The additional arguments are a pointer to the file descriptor array plus + the number of file descriptors in the array. If the number of file descriptors is passed as 0, the call + is fully equivalent to <function>sd_pid_notify()</function>, i.e. no file descriptors are passed. Note + that file descriptors sent to the service manager on a message without <literal>FDSTORE=1</literal> are + immediately closed on reception.</para> + + <para><function>sd_notify_barrier()</function> allows the caller to synchronize against reception of + previously sent notification messages and uses the <varname>BARRIER=1</varname> command. It takes a + relative <varname>timeout</varname> value in microseconds which is passed to <citerefentry><refentrytitle>ppoll</refentrytitle><manvolnum>2</manvolnum> </citerefentry>. A value of UINT64_MAX is interpreted as infinite timeout. </para> @@ -374,14 +363,15 @@ <refsect1> <title>Return Value</title> - <para>On failure, these calls return a negative errno-style error code. If <varname>$NOTIFY_SOCKET</varname> was - not set and hence no status message could be sent, 0 is returned. If the status was sent, these functions return a - positive value. In order to support both service managers that implement this scheme and those which do not, it is - generally recommended to ignore the return value of this call. Note that the return value simply indicates whether - the notification message was enqueued properly, it does not reflect whether the message could be processed + <para>On failure, these calls return a negative errno-style error code. If + <varname>$NOTIFY_SOCKET</varname> was not set and hence no status message could be sent, 0 is + returned. If the status was sent, these functions return a positive value. In order to support both + service managers that implement this scheme and those which do not, it is generally recommended to ignore + the return value of this call. Note that the return value simply indicates whether the notification + message was enqueued properly, it does not reflect whether the message could be processed successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using - <varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file descriptors (see - above).</para> + <varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file + descriptors (see above).</para> </refsect1> <refsect1> @@ -390,27 +380,21 @@ <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> <xi:include href="threads-aware.xml" xpointer="getenv"/> - <para>These functions send a single datagram with the - state string as payload to the socket referenced in the - <varname>$NOTIFY_SOCKET</varname> environment variable. If the - first character of <varname>$NOTIFY_SOCKET</varname> is - <literal>/</literal> or <literal>@</literal>, the string is understood - as an <constant>AF_UNIX</constant> or Linux abstract namespace socket - (respectively), and in both cases the datagram is accompanied by the - process credentials of the sending service, using SCM_CREDENTIALS. If - the string starts with <literal>vsock:</literal> then the string is - understood as an <constant>AF_VSOCK</constant> address, which is useful - for hypervisors/VMMs or other processes on the host to receive a - notification when a virtual machine has finished booting. Note that in - case the hypervisor does not support <constant>SOCK_DGRAM</constant> - over <constant>AF_VSOCK</constant>, <constant>SOCK_SEQPACKET</constant> - will be used instead. The address should be in the form: - <literal>vsock:CID:PORT</literal>. Note that unlike other uses of vsock, - the CID is mandatory and cannot be <literal>VMADDR_CID_ANY</literal>. - Note that PID1 will send the VSOCK packets from a privileged port - (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>These functions send a single datagram with the state string as payload to the socket referenced in + the <varname>$NOTIFY_SOCKET</varname> environment variable. If the first character of + <varname>$NOTIFY_SOCKET</varname> is <literal>/</literal> or <literal>@</literal>, the string is + understood as an <constant>AF_UNIX</constant> or Linux abstract namespace socket (respectively), and in + both cases the datagram is accompanied by the process credentials of the sending service, using + SCM_CREDENTIALS. If the string starts with <literal>vsock:</literal> then the string is understood as an + <constant>AF_VSOCK</constant> address, which is useful for hypervisors/VMMs or other processes on the + host to receive a notification when a virtual machine has finished booting. Note that in case the + hypervisor does not support <constant>SOCK_DGRAM</constant> over <constant>AF_VSOCK</constant>, + <constant>SOCK_SEQPACKET</constant> will be used instead. The address should be in the form: + <literal>vsock:CID:PORT</literal>. Note that unlike other uses of vsock, the CID is mandatory and cannot + be <literal>VMADDR_CID_ANY</literal>. Note that PID1 will send the VSOCK packets from a privileged port + (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> </refsect1> <refsect1> @@ -420,11 +404,9 @@ <varlistentry> <term><varname>$NOTIFY_SOCKET</varname></term> - <listitem><para>Set by the service manager for supervised - processes for status and start-up completion notification. - This environment variable specifies the socket - <function>sd_notify()</function> talks to. See above for - details.</para></listitem> + <listitem><para>Set by the service manager for supervised processes for status and start-up + completion notification. This environment variable specifies the socket + <function>sd_notify()</function> talks to. See above for details.</para></listitem> </varlistentry> </variablelist> </refsect1> @@ -435,8 +417,8 @@ <example> <title>Start-up Notification</title> - <para>When a service finished starting up, it might issue the - following call to notify the service manager:</para> + <para>When a service finished starting up, it might issue the following call to notify the service + manager:</para> <programlisting>sd_notify(0, "READY=1");</programlisting> </example> @@ -444,8 +426,7 @@ <example> <title>Extended Start-up Notification</title> - <para>A service could send the following after completing - initialization:</para> + <para>A service could send the following after completing initialization:</para> <programlisting> sd_notifyf(0, "READY=1\n" @@ -469,9 +450,8 @@ sd_notifyf(0, "STATUS=Failed to start up: %s\n" <example> <title>Store a File Descriptor in the Service Manager</title> - <para>To store an open file descriptor in the service manager, - in order to continue operation after a service restart without - losing state, use <literal>FDSTORE=1</literal>:</para> + <para>To store an open file descriptor in the service manager, in order to continue operation after a + service restart without losing state, use <literal>FDSTORE=1</literal>:</para> <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting> </example> @@ -479,12 +459,10 @@ sd_notifyf(0, "STATUS=Failed to start up: %s\n" <example> <title>Eliminating race conditions</title> - <para>When the client sending the notifications is not spawned - by the service manager, it may exit too quickly and the service - manager may fail to attribute them correctly to the unit. To - prevent such races, use <function>sd_notify_barrier()</function> - to synchronize against reception of all notifications sent before - this call is made.</para> + <para>When the client sending the notifications is not spawned by the service manager, it may exit too + quickly and the service manager may fail to attribute them correctly to the unit. To prevent such + races, use <function>sd_notify_barrier()</function> to synchronize against reception of all + notifications sent before this call is made.</para> <programlisting> sd_notify(0, "READY=1"); diff --git a/man/standard-options.xml b/man/standard-options.xml index d42f3296ca..71c84958ab 100644 --- a/man/standard-options.xml +++ b/man/standard-options.xml @@ -86,4 +86,15 @@ numerical signal numbers and the program will exit immediately.</para> </listitem> </varlistentry> + + <varlistentry id='image-policy-open'> + <term><option>--image-policy=<replaceable>policy</replaceable></option></term> + + <listitem><para>Takes an image policy string as argument, as per + <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The + policy is enforced when operating on the disk image specified via <option>--image=</option>, see + above. If not specified defaults to the <literal>*</literal> policy, i.e. all recognized file systems + in the image are used.</para></listitem> + </varlistentry> + </variablelist> diff --git a/man/system-or-user-ns.xml b/man/system-or-user-ns.xml index 7a302d5980..532c1ef64e 100644 --- a/man/system-or-user-ns.xml +++ b/man/system-or-user-ns.xml @@ -8,9 +8,13 @@ <refsect1> <para id="singular">This option is only available for system services, or for services running in per-user - instances of the service manager when <varname>PrivateUsers=</varname> is enabled.</para> + instances of the service manager in which case <varname>PrivateUsers=</varname> is implicitly enabled + (requires unprivileged user namespaces support to be enabled in the kernel via the + <literal>kernel.unprivileged_userns_clone=</literal> sysctl).</para> <para id="plural">These options are only available for system services, or for services running in per-user - instances of the service manager when <varname>PrivateUsers=</varname> is enabled.</para> + instances of the service manager in which case <varname>PrivateUsers=</varname> is implicitly enabled + (requires unprivileged user namespaces support to be enabled in the kernel via the + <literal>kernel.unprivileged_userns_clone=</literal> sysctl).</para> </refsect1> diff --git a/man/systemctl.xml b/man/systemctl.xml index f930034cb1..639c888110 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -538,12 +538,16 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err <varname>StateDirectory=</varname>, <varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname> and <varname>RuntimeDirectory=</varname>, see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. For timer units this may be used to clear out the persistent timestamp data if + for details. It may also be used to clear the file descriptor store as enabled via + <varname>FileDescriptorStoreMax=</varname>, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. For timer units this may be used to clear out the persistent timestamp data if <varname>Persistent=</varname> is used and <option>--what=state</option> is selected, see <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This command only applies to units that use either of these settings. If <option>--what=</option> is - not specified, both the cache and runtime data are removed (as these two types of data are - generally redundant and reproducible on the next invocation of the unit).</para> + not specified, the cache and runtime data as well as the file descriptor store are removed (as + these three types of resources are generally redundant and reproducible on the next invocation of + the unit). Note that the specified units must be stopped to invoke this operation.</para> </listitem> </varlistentry> <varlistentry> @@ -2193,13 +2197,17 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err <listitem> <para>Select what type of per-unit resources to remove when the <command>clean</command> command is - invoked, see below. Takes one of <constant>configuration</constant>, <constant>state</constant>, - <constant>cache</constant>, <constant>logs</constant>, <constant>runtime</constant> to select the - type of resource. This option may be specified more than once, in which case all specified resource - types are removed. Also accepts the special value <constant>all</constant> as a shortcut for - specifying all five resource types. If this option is not specified defaults to the combination of - <constant>cache</constant> and <constant>runtime</constant>, i.e. the two kinds of resources that - are generally considered to be redundant and can be reconstructed on next invocation.</para> + invoked, see above. Takes one of <constant>configuration</constant>, <constant>state</constant>, + <constant>cache</constant>, <constant>logs</constant>, <constant>runtime</constant>, + <constant>fdstore</constant> to select the type of resource. This option may be specified more than + once, in which case all specified resource types are removed. Also accepts the special value + <constant>all</constant> as a shortcut for specifying all six resource types. If this option is not + specified defaults to the combination of <constant>cache</constant>, <constant>runtime</constant> + and <constant>fdstore</constant>, i.e. the three kinds of resources that are generally considered + to be redundant and can be reconstructed on next invocation. Note that the explicit removal of the + <constant>fdstore</constant> resource type is only useful if the + <varname>FileDescriptorStorePreserve=</varname> option is enabled, since the file descriptor store + is otherwise cleaned automatically when the unit is stopped.</para> </listitem> </varlistentry> @@ -2276,6 +2284,8 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err switch of the same name.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="image-policy-open" /> + <varlistentry> <term><option>--runtime</option></term> diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml index 9fd28e6f45..7176e3c046 100644 --- a/man/systemd-analyze.xml +++ b/man/systemd-analyze.xml @@ -162,6 +162,12 @@ <arg choice="plain">fdstore</arg> <arg choice="opt" rep="repeat"><replaceable>UNIT</replaceable></arg> </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">image-policy</arg> + <arg choice="plain" rep="repeat"><replaceable>POLICY</replaceable></arg> + </cmdsynopsis> </refsynopsisdiv> <refsect1> @@ -840,6 +846,39 @@ stored sock 0:8 4213190 - socket:[4213190] ro "DEVNO".</para> </refsect2> + <refsect2> + <title><command>systemd-analyze image-policy <optional><replaceable>POLICY</replaceable>…</optional></command></title> + + <para>This command analyzes the specified image policy string, as per + <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The + policy is normalized and simplified. For each currently defined partition identifier (as per the <ulink + url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable + Partitions Specification</ulink> the effect of the image policy string is shown in tabular form.</para> + + <example> + <title>Example Output</title> + + <programlisting>$ systemd-analyze image-policy swap=encrypted:usr=read-only-on+verity:root=encrypted +Analyzing policy: root=encrypted:usr=verity+read-only-on:swap=encrypted + Long form: root=encrypted:usr=verity+read-only-on:swap=encrypted:=unused+absent + +PARTITION MODE READ-ONLY GROWFS +root encrypted - - +usr verity yes - +home ignore - - +srv ignore - - +esp ignore - - +xbootldr ignore - - +swap encrypted - - +root-verity ignore - - +usr-verity unprotected yes - +root-verity-sig ignore - - +usr-verity-sig ignore - - +tmp ignore - - +var ignore - - +default ignore - -</programlisting> + </example> + </refsect2> </refsect1> <refsect1> @@ -967,6 +1006,8 @@ stored sock 0:8 4213190 - socket:[4213190] ro operate on files inside the specified image path <replaceable>PATH</replaceable>.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="image-policy-open" /> + <varlistentry> <term><option>--offline=<replaceable>BOOL</replaceable></option></term> diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml index 8af75d1523..6ca850e0ef 100644 --- a/man/systemd-cryptenroll.xml +++ b/man/systemd-cryptenroll.xml @@ -58,6 +58,162 @@ <para>The tool supports only LUKS2 volumes, as it stores token meta-information in the LUKS2 JSON token area, which is not available in other encryption formats.</para> + + <refsect2> + <title>TPM2 PCRs and policies</title> + + <para>PCRs allow binding of the encryption of secrets to specific software versions and system state, + so that the enrolled key is only accessible (may be "unsealed") if specific trusted software and/or + configuration is used. Such bindings may be created with the option <option>--tpm2-pcrs=</option> + described below.</para> + + <para>Secrets may also be bound indirectly: a signed policy for a state of some combination of PCR + values is provided, and the secret is bound to the public part of the key used to sign this policy. + This means that the owner of a key can generate a sequence of signed policies, for specific software + versions and system states, and the secret can be decrypted as long as the machine state matches one of + those policies. For example, a vendor may provide such a policy for each kernel+initrd update, allowing + users to encrypt secrets so that they can be decrypted when running any kernel+initrd signed by the + vendor. Such bindings may be created with the options <option>--tpm2-public-key=</option>, + <option>--tpm2-public-key-pcrs=</option>, <option>--tpm2-signature=</option> described below. + </para> + + <para>See <ulink url="https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/">Linux TPM + PCR Registry</ulink> for an authoritative list of PCRs and how they are updated. The table below + contains a quick reference, describing in particular the PCRs modified by systemd.</para> + + <table> + <title>Well-known PCR Definitions</title> + + <!-- See: https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/ --> + <!-- See: https://github.com/rhboot/shim/blob/main/README.tpm --> + <!-- See: https://www.gnu.org/software/grub/manual/grub/html_node/Measured-Boot.html --> + <!-- See: https://sourceforge.net/p/linux-ima/wiki/Home/ --> + <!-- See: https://github.com/tianocore-docs/edk2-TrustedBootChain/blob/main/4_Other_Trusted_Boot_Chains.md --> + <!-- See: https://wiki.archlinux.org/title/Trusted_Platform_Module#Accessing_PCR_registers --> + + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname="pcr" /> + <colspec colname="name" /> + <colspec colname="definition" /> + + <thead> + <row> + <entry>PCR</entry> + <entry>name</entry> + <entry>Explanation</entry> + </row> + </thead> + + <tbody> + <row> + <entry>0</entry> + <entry>platform-code</entry> + <entry>Core system firmware executable code; changes on firmware updates</entry> + </row> + + <row> + <entry>1</entry> + <entry>platform-config</entry> + <entry>Core system firmware data/host platform configuration; typically contains serial and model numbers, changes on basic hardware/CPU/RAM replacements</entry> + </row> + + <row> + <entry>2</entry> + <entry>external-code</entry> + <entry>Extended or pluggable executable code; includes option ROMs on pluggable hardware</entry> + </row> + + <row> + <entry>3</entry> + <entry>external-config</entry> + <entry>Extended or pluggable firmware data; includes information about pluggable hardware</entry> + </row> + + <row> + <entry>4</entry> + <entry>boot-loader-code</entry> + <entry>Boot loader and additional drivers, PE binaries invoked by the boot loader; changes on boot loader updates. <citerefentry><refentrytitle>sd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures system extension images read from the ESP here too (see <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>).</entry> + </row> + + <row> + <entry>5</entry> + <entry>boot-loader-config</entry> + <entry>GPT/Partition table; changes when the partitions are added, modified, or removed</entry> + </row> + + <row> + <entry>7</entry> + <entry>secure-boot-policy</entry> + <entry>Secure Boot state; changes when UEFI SecureBoot mode is enabled/disabled, or firmware certificates (PK, KEK, db, dbx, …) changes.</entry> + </row> + + <row> + <entry>9</entry> + <entry>kernel-initrd</entry> + <entry>The Linux kernel measures all initrds it receives into this PCR.</entry> + <!-- Strictly speaking only Linux >= 5.17 using the LOAD_FILE2 protocol, see https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f046fff8bc4c4d8f8a478022e76e40b818f692df --> + </row> + + <row> + <entry>10</entry> + <entry>ima</entry> + <entry>The IMA project measures its runtime state into this PCR.</entry> + </row> + + <row> + <entry>11</entry> + <entry>kernel-boot</entry> + <entry><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures the ELF kernel image, embedded initrd and other payload of the PE image it is placed in into this PCR. <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures boot phase strings into this PCR at various milestones of the boot process.</entry> + </row> + + <row> + <entry>12</entry> + <entry>kernel-config</entry> + <entry><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures the kernel command line into this PCR. <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures any manually specified kernel command line (i.e. a kernel command line that overrides the one embedded in the unified PE image) and loaded credentials into this PCR.</entry> + </row> + + <row> + <entry>13</entry> + <entry>sysexts</entry> + <entry><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures any <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> images it passes to the booted kernel into this PCR.</entry> + </row> + + <row> + <entry>14</entry> + <entry>shim-policy</entry> + <entry>The shim project measures its "MOK" certificates and hashes into this PCR.</entry> + </row> + + <row> + <entry>15</entry> + <entry>system-identity</entry> + <entry><citerefentry><refentrytitle>systemd-cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> optionally measures the volume key of activated LUKS volumes into this PCR. <citerefentry><refentrytitle>systemd-pcrmachine.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures the <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> into this PCR. <citerefentry><refentrytitle>systemd-pcrfs@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures mount points, file system UUIDs, labels, partition UUIDs of the root and <filename>/var/</filename> filesystems into this PCR.</entry> + </row> + + <row> + <entry>16</entry> + <entry>debug</entry> + <entry>Debug</entry> + </row> + + <row> + <entry>23</entry> + <entry>application-support</entry> + <entry>Application Support</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>In general, encrypted volumes would be bound to some combination of PCRs 7, 11, and 14 (if + shim/MOK is used). In order to allow firmware and OS version updates, it is typically not advisable to + use PCRs such as 0 and 2, since the program code they cover should already be covered indirectly + through the certificates measured into PCR 7. Validation through certificates hashes is typically + preferable over validation through direct measurements as it is less brittle in context of OS/firmware + updates: the measurements will change on every update, but signatures should remain unchanged. See the + <ulink url="https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/">Linux TPM PCR + Registry</ulink> for more discussion.</para> + </refsect2> </refsect1> <refsect1> @@ -234,126 +390,15 @@ <varlistentry> <term><option>--tpm2-pcrs=</option><arg rep="repeat">PCR</arg></term> - <listitem><para>Configures the TPM2 PCRs (Platform Configuration Registers) to bind the enrollment - requested via <option>--tpm2-device=</option> to. Takes a <literal>+</literal> separated list of - numeric PCR indexes in the range 0…23. If not used, defaults to PCR 7 only. If an empty string is - specified, binds the enrollment to no PCRs at all. PCRs allow binding the enrollment to specific - software versions and system state, so that the enrolled unlocking key is only accessible (may be - "unsealed") if specific trusted software and/or configuration is used.</para> - - <table> - <title>Well-known PCR Definitions</title> - - <!-- See: https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/ --> - <!-- See: https://github.com/rhboot/shim/blob/main/README.tpm --> - <!-- See: https://www.gnu.org/software/grub/manual/grub/html_node/Measured-Boot.html --> - <!-- See: https://sourceforge.net/p/linux-ima/wiki/Home/ --> - <!-- See: https://github.com/tianocore-docs/edk2-TrustedBootChain/blob/main/4_Other_Trusted_Boot_Chains.md --> - <!-- See: https://wiki.archlinux.org/title/Trusted_Platform_Module#Accessing_PCR_registers --> - - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname="pcr" /> - <colspec colname="definition" /> - - <thead> - <row> - <entry>PCR</entry> - <entry>Explanation</entry> - </row> - </thead> - - <tbody> - <row> - <entry>0</entry> - <entry>Core system firmware executable code; changes on firmware updates</entry> - </row> - - <row> - <entry>1</entry> - <entry>Core system firmware data/host platform configuration; typically contains serial and model numbers, changes on basic hardware/CPU/RAM replacements</entry> - </row> - - <row> - <entry>2</entry> - <entry>Extended or pluggable executable code; includes option ROMs on pluggable hardware</entry> - </row> - - <row> - <entry>3</entry> - <entry>Extended or pluggable firmware data; includes information about pluggable hardware</entry> - </row> - - <row> - <entry>4</entry> - <entry>Boot loader and additional drivers; changes on boot loader updates. The shim project will measure the PE binary it chain loads into this PCR. If the Linux kernel is invoked as UEFI PE binary, it is measured here, too. <citerefentry><refentrytitle>sd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures system extension images read from the ESP here too (see <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>).</entry> - </row> - - <row> - <entry>5</entry> - <entry>GPT/Partition table; changes when the partitions are added, modified or removed</entry> - </row> - - <row> - <entry>6</entry> - <entry>Power state events; changes on system suspend/sleep</entry> - </row> - - <row> - <entry>7</entry> - <entry>Secure Boot state; changes when UEFI SecureBoot mode is enabled/disabled, or firmware certificates (PK, KEK, db, dbx, …) changes. The shim project will measure most of its (non-MOK) certificates and SBAT data into this PCR.</entry> - </row> - - <!-- Grub measures all its commands and the kernel command line into PCR 8… --> - <!-- Grub measures all files it reads (including kernel image, initrd, …) into PCR 9… --> - - <row> - <entry>9</entry> - <entry>The Linux kernel measures all initrds it receives into this PCR.</entry> - <!-- Strictly speaking only Linux >= 5.17 using the LOAD_FILE2 protocol, see https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f046fff8bc4c4d8f8a478022e76e40b818f692df --> - </row> - - <row> - <entry>10</entry> - <entry>The IMA project measures its runtime state into this PCR.</entry> - </row> - - <row> - <entry>11</entry> - <entry><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures the ELF kernel image, embedded initrd and other payload of the PE image it is placed in into this PCR. Unlike PCR 4 (where the same data should be measured into), this PCR value should be easy to pre-calculate, as this only contains static parts of the PE binary. Use this PCR to bind TPM policies to a specific kernel image, possibly with an embedded initrd. <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures boot phase strings into this PCR at various milestones of the boot process.</entry> - </row> - - <row> - <entry>12</entry> - <entry><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures the kernel command line into this PCR. <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures any manually specified kernel command line (i.e. a kernel command line that overrides the one embedded in the unified PE image) and loaded credentials into this PCR. (Note that if <command>systemd-boot</command> and <command>systemd-stub</command> are used in combination the command line might be measured twice!)</entry> - </row> - - <row> - <entry>13</entry> - <entry><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures any <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> images it loads and passed to the booted kernel into this PCR.</entry> - </row> - - <row> - <entry>14</entry> - <entry>The shim project measures its "MOK" certificates and hashes into this PCR.</entry> - </row> - - <row> - <entry>15</entry> - <entry><citerefentry><refentrytitle>systemd-cryptsetup</refentrytitle><manvolnum>7</manvolnum></citerefentry> optionally measures the volume key of activated LUKS volumes into this PCR.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>For most applications it should be sufficient to bind against PCR 7 (and possibly PCR 14, if - shim/MOK is desired), as this includes measurements of the trusted certificates (and possibly hashes) - that are used to validate all components of the boot process up to and including the OS kernel. In - order to simplify firmware and OS version updates it's typically not advisable to include PCRs such - as 0 and 2 in the binding of the enrollment, since the program code they cover should already be - protected indirectly through the certificates measured into PCR 7. Validation through these - certificates is typically preferable over validation through direct measurements as it is less - brittle in context of OS/firmware updates: the measurements will change on every update, but code - signatures likely will validate against pre-existing certificates.</para></listitem> + <listitem><para>Configures the TPM2 PCRs (Platform Configuration Registers) to bind to when + enrollment is requested via <option>--tpm2-device=</option>. Takes a list of PCR names or numeric + indices in the range 0…23. Multiple PCR indexes are separated by <literal>+</literal>. If not + specified, the default is to use PCR 7 only. If an empty string is specified, binds the enrollment to + no PCRs at all. See the table above for a list of available PCRs.</para> + + <para>Example: <option>--tpm2-pcrs=boot-loader-code+platform-config+boot-loader-config</option> + specifies that PCR registers 4, 1, and 5 should be used.</para> + </listitem> </varlistentry> <varlistentry> @@ -394,18 +439,21 @@ <option>--tpm2-public-key-pcrs=</option>: the former binds decryption to the current, specific PCR values; the latter binds decryption to any set of PCR values for which a signature by the specified public key can be provided. The latter is hence more useful in scenarios where software updates shell - be possible without losing access to all previously encrypted LUKS2 volumes.</para> + be possible without losing access to all previously encrypted LUKS2 volumes. Like with + <option>--tpm2-pcrs=</option>, names defined in the table above can also be used to specify the + registers, for instance + <option>--tpm2-public-key-pcrs=boot-loader-code+system-identity</option>.</para> - <para>The <option>--tpm2-signature=</option> option takes a path to a TPM2 PCR signature file - as generated by the + <para>The <option>--tpm2-signature=</option> option takes a path to a TPM2 PCR signature file as + generated by the <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool. If this is not specified explicitly a suitable signature file + tool. If this is not specified explicitly, a suitable signature file <filename>tpm2-pcr-signature.json</filename> is searched for in <filename>/etc/systemd/</filename>, - <filename>/run/systemd/</filename>, <filename>/usr/lib/systemd/</filename> (in this order) and - used. If a signature file is specified or found it is used to verify if the volume can be unlocked - with it given the current PCR state, before the new slot is written to disk. This is intended as - safety net to ensure that access to a volume is not lost if a public key is enrolled for which no - valid signature for the current PCR state is available. If the supplied signature does not unlock the + <filename>/run/systemd/</filename>, <filename>/usr/lib/systemd/</filename> (in this order) and used. + If a signature file is specified or found it is used to verify if the volume can be unlocked with it + given the current PCR state, before the new slot is written to disk. This is intended as safety net + to ensure that access to a volume is not lost if a public key is enrolled for which no valid + signature for the current PCR state is available. If the supplied signature does not unlock the current PCR state and public key combination, no slot is enrolled and the operation will fail. If no signature file is specified or found no such safety verification is done.</para></listitem> </varlistentry> diff --git a/man/systemd-dissect.xml b/man/systemd-dissect.xml index 06c57a22ec..06ee0717f8 100644 --- a/man/systemd-dissect.xml +++ b/man/systemd-dissect.xml @@ -274,13 +274,27 @@ <term><option>--discover</option></term> <listitem><para>Show a list of DDIs in well-known directories. This will show machine, portable - service and system extension disk images in the usual directories + service and system/configuration extension disk images in the usual directories <filename>/usr/lib/machines/</filename>, <filename>/usr/lib/portables/</filename>, - <filename>/usr/lib/extensions/</filename>, <filename>/var/lib/machines/</filename>, + <filename>/usr/lib/confexts/</filename>, <filename>/var/lib/machines/</filename>, <filename>/var/lib/portables/</filename>, <filename>/var/lib/extensions/</filename> and so on.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--validate</option></term> + + <listitem><para>Validates the partition arrangement of a disk image (DDI), and ensures it matches the + image policy specified via <option>--image-policy=</option>, if one is specified. This parses the + partition table and probes the file systems in the image, but does not attempt to mount them (nor to + set up disk encryption/authentication via LUKS/Verity). It does this taking the configured image + dissection policy into account. Since this operation does not mount file systems, this command – + unlike all other commands implemented by this tool – requires no privileges other than the ability to + access the specified file. Prints "OK" and returns zero if the image appears to be in order and + matches the specified image dissection policy. Otherwise prints an error message and returns + non-zero.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -405,6 +419,7 @@ <command>cfdisk /dev/loop/by-ref/quux</command>.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="image-policy-open" /> <xi:include href="standard-options.xml" xpointer="no-pager" /> <xi:include href="standard-options.xml" xpointer="no-legend" /> <xi:include href="standard-options.xml" xpointer="json" /> diff --git a/man/systemd-fsck@.service.xml b/man/systemd-fsck@.service.xml index e928aebdb3..403286829e 100644 --- a/man/systemd-fsck@.service.xml +++ b/man/systemd-fsck@.service.xml @@ -51,17 +51,17 @@ <para><filename>systemd-fsck</filename> does not know any details about specific filesystems, and simply executes file system checkers specific to each filesystem type - (<filename>/sbin/fsck.<replaceable>type</replaceable></filename>). These checkers will decide if + (<filename>fsck.<replaceable>type</replaceable></filename>). These checkers will decide if the filesystem should actually be checked based on the time since last check, number of mounts, unclean unmount, etc.</para> <para><filename>systemd-fsck-root.service</filename> and <filename>systemd-fsck-usr.service</filename> - will activate <filename>reboot.target</filename> if <filename>/sbin/fsck</filename> returns the "System - should reboot" condition, or <filename>emergency.target</filename> if <filename>/sbin/fsck</filename> + will activate <filename>reboot.target</filename> if <filename>fsck</filename> returns the "System + should reboot" condition, or <filename>emergency.target</filename> if <filename>fsck</filename> returns the "Filesystem errors left uncorrected" condition.</para> <para><filename>systemd-fsck@.service</filename> will fail if - <filename>/sbin/fsck</filename> returns with either "System should reboot" + <filename>fsck</filename> returns with either "System should reboot" or "Filesystem errors left uncorrected" conditions. For filesystems listed in <filename>/etc/fstab</filename> without <literal>nofail</literal> or <literal>noauto</literal> options, <literal>local-fs.target</literal> diff --git a/man/systemd-gpt-auto-generator.xml b/man/systemd-gpt-auto-generator.xml index bd542cb7f7..1730039b62 100644 --- a/man/systemd-gpt-auto-generator.xml +++ b/man/systemd-gpt-auto-generator.xml @@ -250,6 +250,16 @@ </varlistentry> <varlistentry> + <term><varname>systemd.image_policy=</varname></term> + <term><varname>rd.systemd.image_policy=</varname></term> + + <listitem><para>Takes an image dissection policy string as argument (as per + <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>), + and allows enforcing a policy on dissection and use of the automatically discovered GPT partition + table entries.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>root=</varname></term> <term><varname>rootfstype=</varname></term> <term><varname>rootflags=</varname></term> diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml index f1695b6ddb..c07a853418 100644 --- a/man/systemd-machine-id-setup.xml +++ b/man/systemd-machine-id-setup.xml @@ -95,6 +95,8 @@ tree.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="image-policy-open" /> + <varlistentry> <term><option>--commit</option></term> <listitem><para>Commit a transient machine ID to disk. This diff --git a/man/systemd-mount.xml b/man/systemd-mount.xml index 1cde3ab00c..e25d5c435e 100644 --- a/man/systemd-mount.xml +++ b/man/systemd-mount.xml @@ -227,7 +227,7 @@ <listitem><para>This option only has an effect in automount mode, and controls whether the automount unit shall be bound to the backing device's lifetime. If set, the - automount point will be removed automatically when the backing device vanishes. By default the automount point + automount unit will be stopped automatically when the backing device vanishes. By default the automount unit stays around, and subsequent accesses will block until backing device is replugged. This option has no effect in case of non-device mounts, such as network or virtual file system mounts.</para> diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index e2c751692f..ded8e3cd71 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -311,6 +311,17 @@ </varlistentry> <varlistentry> + <term><option>--image-policy=<replaceable>policy</replaceable></option></term> + + <listitem><para>Takes an image policy string as argument, as per + <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The + policy is enforced when operating on the disk image specified via <option>--image=</option>, see + above. If not specified defaults to + <literal>root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent:home=encrypted+unprotected+absent:srv=encrypted+unprotected+absent:esp=unprotected+absent:xbootldr=unprotected+absent:tmp=encrypted+unprotected+absent:var=encrypted+unprotected+absent</literal>, + i.e. all recognized file systems in the image are used, but not the swap partition.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--oci-bundle=</option></term> <listitem><para>Takes the path to an OCI runtime bundle to invoke, as specified in the <ulink @@ -841,11 +852,13 @@ <varlistentry> <term><option>--network-interface=</option></term> - <listitem><para>Assign the specified network interface to the container. This will remove the - specified interface from the calling namespace and place it in the container. When the container - terminates, it is moved back to the calling namespace. Note that - <option>--network-interface=</option> implies <option>--private-network</option>. This option may be - used more than once to add multiple network interfaces to the container.</para> + <listitem><para>Assign the specified network interface to the container. Either takes a single + interface name, referencing the name on the host, or a colon-separated pair of interfaces, in which + case the first one references the name on the host, and the second one the name in the container. + When the container terminates, the interface is moved back to the calling namespace and renamed to + its original name. Note that <option>--network-interface=</option> implies + <option>--private-network</option>. This option may be used more than once to add multiple network + interfaces to the container.</para> <para>Note that any network interface specified this way must already exist at the time the container is started. If the container shall be started automatically at boot via a @@ -869,9 +882,12 @@ After=sys-subsystem-net-devices-ens1.device</programlisting> <term><option>--network-macvlan=</option></term> <listitem><para>Create a <literal>macvlan</literal> interface of the specified Ethernet network - interface and add it to the container. A <literal>macvlan</literal> interface is a virtual interface - that adds a second MAC address to an existing physical Ethernet link. The interface in the container - will be named after the interface on the host, prefixed with <literal>mv-</literal>. Note that + interface and add it to the container. Either takes a single interface name, referencing the name + on the host, or a colon-separated pair of interfaces, in which case the first one references the name + on the host, and the second one the name in the container. A <literal>macvlan</literal> interface is + a virtual interface that adds a second MAC address to an existing physical Ethernet link. If the + container interface name is not defined, the interface in the container will be named after the + interface on the host, prefixed with <literal>mv-</literal>. Note that <option>--network-macvlan=</option> implies <option>--private-network</option>. This option may be used more than once to add multiple network interfaces to the container.</para> @@ -884,9 +900,13 @@ After=sys-subsystem-net-devices-ens1.device</programlisting> <term><option>--network-ipvlan=</option></term> <listitem><para>Create an <literal>ipvlan</literal> interface of the specified Ethernet network - interface and add it to the container. An <literal>ipvlan</literal> interface is a virtual interface, + interface and add it to the container. Either takes a single interface name, referencing the name on + the host, or a colon-separated pair of interfaces, in which case the first one references the name + on the host, and the second one the name in the container. An <literal>ipvlan</literal> interface is + a virtual interface, similar to a <literal>macvlan</literal> interface, which uses the same MAC address as the underlying - interface. The interface in the container will be named after the interface on the host, prefixed + interface. If the container interface name is not defined, the interface in the container will be + named after the interface on the host, prefixed with <literal>iv-</literal>. Note that <option>--network-ipvlan=</option> implies <option>--private-network</option>. This option may be used more than once to add multiple network interfaces to the container.</para> @@ -1657,7 +1677,7 @@ After=sys-subsystem-net-devices-ens1.device</programlisting> <programlisting># dnf -y --releasever=&fedora_latest_version; --installroot=/var/lib/machines/f&fedora_latest_version; \ --repo=fedora --repo=updates --setopt=install_weak_deps=False install \ - passwd dnf fedora-release vim-minimal systemd systemd-networkd + passwd dnf fedora-release vim-minimal util-linux systemd systemd-networkd # systemd-nspawn -bD /var/lib/machines/f&fedora_latest_version;</programlisting> <para>This installs a minimal Fedora distribution into the diff --git a/man/systemd-poweroff.service.xml b/man/systemd-poweroff.service.xml index 9adfcc5af0..98c20471da 100644 --- a/man/systemd-poweroff.service.xml +++ b/man/systemd-poweroff.service.xml @@ -36,41 +36,34 @@ <refsect1> <title>Description</title> - <para><filename>systemd-poweroff.service</filename> is a system - service that is pulled in by <filename>poweroff.target</filename> and - is responsible for the actual system power-off operation. Similarly, - <filename>systemd-halt.service</filename> is pulled in by - <filename>halt.target</filename>, - <filename>systemd-reboot.service</filename> by - <filename>reboot.target</filename> and - <filename>systemd-kexec.service</filename> by - <filename>kexec.target</filename> to execute the respective - actions.</para> + <para><filename>systemd-poweroff.service</filename> is a system service that is pulled in by + <filename>poweroff.target</filename> and is responsible for the actual system power-off + operation. Similarly, <filename>systemd-halt.service</filename> is pulled in by + <filename>halt.target</filename>, <filename>systemd-reboot.service</filename> by + <filename>reboot.target</filename> and <filename>systemd-kexec.service</filename> by + <filename>kexec.target</filename> to execute the respective actions.</para> - <para>When these services are run, they ensure that PID 1 is - replaced by the - <filename>/usr/lib/systemd/systemd-shutdown</filename> tool which - is then responsible for the actual shutdown. Before shutting down, - this binary will try to unmount all remaining file systems, - disable all remaining swap devices, detach all remaining storage - devices and kill all remaining processes.</para> + <para>When these services are run, they ensure that PID 1 is replaced by the + <filename>/usr/lib/systemd/systemd-shutdown</filename> tool which is then responsible for the actual + shutdown. Before shutting down, this binary will try to unmount all remaining file systems (or at least + remount them read-only), disable all remaining swap devices, detach all remaining storage devices and + kill all remaining processes.</para> - <para>It is necessary to have this code in a separate binary - because otherwise rebooting after an upgrade might be broken — the - running PID 1 could still depend on libraries which are not - available any more, thus keeping the file system busy, which then - cannot be re-mounted read-only.</para> + <para>It is necessary to have this code in a separate binary because otherwise rebooting after an upgrade + might be broken — the running PID 1 could still depend on libraries which are not available any more, + thus keeping the file system busy, which then cannot be re-mounted read-only.</para> - <para>Immediately before executing the actual system - power-off/halt/reboot/kexec <filename>systemd-shutdown</filename> - will run all executables in - <filename>/usr/lib/systemd/system-shutdown/</filename> and pass - one arguments to them: either <literal>poweroff</literal>, - <literal>halt</literal>, <literal>reboot</literal>, or - <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.</para> + <para>Shortly before executing the actual system power-off/halt/reboot/kexec + <filename>systemd-shutdown</filename> will run all executables in + <filename>/usr/lib/systemd/system-shutdown/</filename> and pass one arguments to them: either + <literal>poweroff</literal>, <literal>halt</literal>, <literal>reboot</literal>, or + <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 + 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> <para>Note that <filename>systemd-poweroff.service</filename> (and the related units) should never be executed directly. Instead, trigger system shutdown with a command such as <literal>systemctl diff --git a/man/systemd-repart.xml b/man/systemd-repart.xml index 9033ef76d6..98ca1c431a 100644 --- a/man/systemd-repart.xml +++ b/man/systemd-repart.xml @@ -269,6 +269,8 @@ <option>--root=</option>, see above.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="image-policy-open" /> + <varlistentry> <term><option>--seed=</option></term> diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml index 96e40ddf95..5e8d11ef3d 100644 --- a/man/systemd-sysext.xml +++ b/man/systemd-sysext.xml @@ -19,6 +19,8 @@ <refnamediv> <refname>systemd-sysext</refname> <refname>systemd-sysext.service</refname> + <refname>systemd-confext</refname> + <refname>systemd-confext.service</refname> <refpurpose>Activates System Extension Images</refpurpose> </refnamediv> @@ -31,6 +33,14 @@ <para><literallayout><filename>systemd-sysext.service</filename></literallayout></para> + <cmdsynopsis> + <command>systemd-confext</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">COMMAND</arg> + </cmdsynopsis> + + <para><literallayout><filename>systemd-confext.service</filename></literallayout></para> + </refsynopsisdiv> <refsect1> @@ -89,7 +99,12 @@ carrying large binary images, however are still useful for carrying symlinks to them. The primary place for installing system extensions is <filename>/var/lib/extensions/</filename>. Any directories found in these search directories are considered directory based extension images; any files with the - <filename>.raw</filename> suffix are considered disk image based extension images.</para> + <filename>.raw</filename> suffix are considered disk image based extension images. When invoked in the + initrd, the additional directory <filename>/.extra/sysext/</filename> is included in the directories that + are searched for extension images. Note however, that by default a tighter image policy applies to images + found there, though, see below. This directory is populated by + <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> with + extension images found in the system's EFI System Partition.</para> <para>During boot OS extension images are activated automatically, if the <filename>systemd-sysext.service</filename> is enabled. Note that this service runs only after the @@ -129,6 +144,30 @@ The <filename>extension-release</filename> file follows the same format and semantics, and carries the same content, as the <filename>os-release</filename> file of the OS, but it describes the resources carried in the extension image.</para> + + <para>The <command>systemd-confext</command> concept follows the same principle as the + <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>1</manvolnum></citerefentry> + functionality but instead of working on <filename>/usr</filename> and <filename>/opt</filename>, + <command>confext</command> will extend only <filename>/etc</filename>. Files and directories contained + in the confext images outside of the <filename>/etc/</filename> hierarchy are <emphasis>not</emphasis> + merged, and hence have no effect when included in the image. Formats for these images are of the + same as sysext images. The merged hierarchy will be mounted with <literal>nosuid</literal> and + (if not disabled via <option>--noexec=false</option>) <literal>noexec</literal>.</para> + + <para>Confexts are looked for in the directories <filename>/run/confexts/</filename>, + <filename>/var/lib/confexts/</filename>, <filename>/usr/lib/confexts/</filename> and + <filename>/usr/local/lib/confexts/</filename>. The first two listed directories are not suitable for + carrying large binary images, however are still useful for carrying symlinks to them. The primary place + for installing system extensions is <filename>/var/lib/confexts/</filename>. Any directories found in + these search directories are considered directory based confext images, any files with the + <filename>.raw</filename> suffix are considered disk image based confext images.</para> + + <para>Again, just like sysext images, the confext images will contain a + <filename>/etc/extension-release.d/extension-release.<replaceable>$name</replaceable></filename> + file, which must match the image name (with the usual escape hatch of xattr), and again with content + being one or more of <varname>ID=</varname>, <varname>VERSION_ID=</varname>, and + <varname>CONFEXT_LEVEL</varname>. Confext images will then be checked and matched against the + base OS layer.</para> </refsect1> <refsect1> @@ -153,20 +192,25 @@ <filename>/usr/</filename> as if it was installed in the OS image itself.) This case works regardless if the underlying host <filename>/usr/</filename> is managed as immutable disk image or is a traditional package manager controlled (i.e. writable) tree.</para> - </refsect1> + + <para>For the confext case, the OSConfig project aims to perform runtime reconfiguration of OS services. + Sometimes, there is a need to swap certain configuration parameter values or restart only a specific + service without deployment of new code or a complete OS deployment. In other words, we want to be able + to tie the most frequently configured options to runtime updateable flags that can be changed without a + system reboot. This will help reduce servicing times when there is a need for changing the OS configuration.</para></refsect1> <refsect1> <title>Commands</title> - <para>The following commands are understood:</para> + <para>The following commands are understood by both the sysext and confext concepts:</para> <variablelist> <varlistentry> <term><option>status</option></term> <listitem><para>When invoked without any command verb, or when <option>status</option> is specified - the current merge status is shown, separately for both <filename>/usr/</filename> and - <filename>/opt/</filename>.</para></listitem> + the current merge status is shown, separately (for both <filename>/usr/</filename> and + <filename>/opt/</filename> of sysext and for <filename>/etc/</filename> of confext).</para></listitem> </varlistentry> <varlistentry> @@ -174,14 +218,15 @@ <listitem><para>Merges all currently installed system extension images into <filename>/usr/</filename> and <filename>/opt/</filename>, by overmounting these hierarchies with an <literal>overlayfs</literal> file system combining the underlying hierarchies with those included in - the extension images. This command will fail if the hierarchies are already merged.</para></listitem> + the extension images. This command will fail if the hierarchies are already merged. For confext, the merge + happens into the <filename>/etc/</filename> directory instead.</para></listitem> </varlistentry> <varlistentry> <term><option>unmerge</option></term> <listitem><para>Unmerges all currently installed system extension images from - <filename>/usr/</filename> and <filename>/opt/</filename>, by unmounting the - <literal>overlayfs</literal> file systems created by <option>merge</option> + <filename>/usr/</filename> and <filename>/opt/</filename> for sysext and <filename>/etc/</filename>, + for confext, by unmounting the <literal>overlayfs</literal> file systems created by <option>merge</option> prior.</para></listitem> </varlistentry> @@ -191,11 +236,11 @@ mounted the existing <literal>overlayfs</literal> instance is unmounted temporarily, and then replaced by a new version. This command is useful after installing/removing system extension images, in order to update the <literal>overlayfs</literal> file system accordingly. If no system extensions - are installed when this command is executed, the equivalent of <option>unmerge</option> is - executed, without establishing any new <literal>overlayfs</literal> instance. Note that currently - there's a brief moment where neither the old nor the new <literal>overlayfs</literal> file system is - mounted. This implies that all resources supplied by a system extension will briefly disappear — even - if it exists continuously during the refresh operation.</para></listitem> + are installed when this command is executed, the equivalent of <option>unmerge</option> is executed, + without establishing any new <literal>overlayfs</literal> instance. + Note that currently there's a brief moment where neither the old nor the new <literal>overlayfs</literal> + file system is mounted. This implies that all resources supplied by a system extension will briefly + disappear — even if it exists continuously during the refresh operation.</para></listitem> </varlistentry> <varlistentry> @@ -218,16 +263,40 @@ <listitem><para>Operate relative to the specified root directory, i.e. establish the <literal>overlayfs</literal> mount not on the top-level host <filename>/usr/</filename> and - <filename>/opt/</filename> hierarchies, but below some specified root directory.</para></listitem> + <filename>/opt/</filename> hierarchies for sysext or <filename>/etc/</filename> for confext, + but below some specified root directory.</para></listitem> </varlistentry> <varlistentry> <term><option>--force</option></term> <listitem><para>When merging system extensions into <filename>/usr/</filename> and - <filename>/opt/</filename>, ignore version incompatibilities, i.e. force merging regardless of - whether the version information included in the extension images matches the host or - not.</para></listitem> + <filename>/opt/</filename> for sysext and <filename>/etc/</filename> for confext, + ignore version incompatibilities, i.e. force merging regardless of + whether the version information included in the images matches the host or not.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--image-policy=<replaceable>policy</replaceable></option></term> + + <listitem><para>Takes an image policy string as argument, as per + <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The + policy is enforced when operating on system extension disk images. If not specified defaults to + <literal>root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent</literal> + for system extensions, i.e. only the root and <filename>/usr/</filename> file systems in the image + are used. For configuration extensions defaults to + <literal>root=verity+signed+encrypted+unprotected+absent</literal>. When run in the initrd and + operating on a system extension image stored in the <filename>/.extra/sysext/</filename> directory a + slightly stricter policy is used by default: <literal>root=signed+absent:usr=signed+absent</literal>, + see above for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--noexec=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>When merging configuration extensions into <filename>/etc/</filename> the + <literal>MS_NOEXEC</literal> mount flag is used by default. This option can be used to disable + it.</para></listitem> </varlistentry> <xi:include href="standard-options.xml" xpointer="no-pager" /> @@ -246,7 +315,8 @@ <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd-sysupdate.xml b/man/systemd-sysupdate.xml index 77c1635b9d..409281c19f 100644 --- a/man/systemd-sysupdate.xml +++ b/man/systemd-sysupdate.xml @@ -229,6 +229,8 @@ inside the specified disk image.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="image-policy-open" /> + <varlistentry> <term><option>--instances-max=</option></term> <term><option>-m</option></term> diff --git a/man/systemd-sysusers.xml b/man/systemd-sysusers.xml index aba275024f..f7ee5e79d9 100644 --- a/man/systemd-sysusers.xml +++ b/man/systemd-sysusers.xml @@ -80,6 +80,8 @@ switch of the same name.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="image-policy-open" /> + <varlistentry> <term><option>--replace=<replaceable>PATH</replaceable></option></term> <listitem><para>When this option is given, one or more positional arguments diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml index 49eda985b4..5612b4803d 100644 --- a/man/systemd-tmpfiles.xml +++ b/man/systemd-tmpfiles.xml @@ -202,6 +202,8 @@ <para>Implies <option>-E</option>.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="image-policy-open" /> + <varlistentry> <term><option>--replace=<replaceable>PATH</replaceable></option></term> <listitem><para>When this option is given, one or more positional arguments diff --git a/man/systemd-veritysetup-generator.xml b/man/systemd-veritysetup-generator.xml index 37ded91a93..71bc1fda64 100644 --- a/man/systemd-veritysetup-generator.xml +++ b/man/systemd-veritysetup-generator.xml @@ -85,8 +85,17 @@ <term><varname>systemd.verity_root_options=</varname></term> <listitem><para>Takes a comma-separated list of dm-verity options. Expects the following options + <option>superblock=<replaceable>BOOLEAN</replaceable></option>, + <option>format=<replaceable>NUMBER</replaceable></option>, + <option>data-block-size=<replaceable>BYTES</replaceable></option>, + <option>hash-block-size=<replaceable>BYTES</replaceable></option>, + <option>data-blocks=<replaceable>BLOCKS</replaceable></option>, + <option>hash-offset=<replaceable>BYTES</replaceable></option>, + <option>salt=<replaceable>HEX</replaceable></option>, <option>uuid=<replaceable>UUID</replaceable></option>, <option>ignore-corruption</option>, <option>restart-on-corruption</option>, <option>ignore-zero-blocks</option>, - <option>check-at-most-once</option>, <option>panic-on-corruption</option> and + <option>check-at-most-once</option>, <option>panic-on-corruption</option>, + <option>hash=<replaceable>HASH</replaceable></option>, <option>fec-device=<replaceable>PATH</replaceable></option>, + <option>fec-offset=<replaceable>BYTES</replaceable></option>, <option>fec-roots=<replaceable>NUM</replaceable></option> and <option>root-hash-signature=<replaceable>PATH</replaceable>|base64:<replaceable>HEX</replaceable></option>. See <citerefentry project='die-net'><refentrytitle>veritysetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for more details.</para></listitem> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 17be33c56a..795e26e792 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -261,6 +261,30 @@ </varlistentry> <varlistentry> + <term><varname>RootImagePolicy=</varname></term> + <term><varname>MountImagePolicy=</varname></term> + <term><varname>ExtensionImagePolicy=</varname></term> + + <listitem><para>Takes an image policy string as per + <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry> + to use when mounting the disk images (DDI) specified in <varname>RootImage=</varname>, + <varname>MountImage=</varname>, <varname>ExtensionImage=</varname>, respectively. If not specified + the following policy string is the default for <varname>RootImagePolicy=</varname> and <varname>MountImagePolicy</varname>:</para> + + <programlisting>root=verity+signed+encrypted+unprotected+absent: \ + usr=verity+signed+encrypted+unprotected+absent: \ + home=encrypted+unprotected+absent: \ + srv=encrypted+unprotected+absent: \ + tmp=encrypted+unprotected+absent: \ + var=encrypted+unprotected+absent</programlisting> + + <para>The default policy for <varname>ExtensionImagePolicy=</varname> is:</para> + + <programlisting>root=verity+signed+encrypted+unprotected+absent: \ + usr=verity+signed+encrypted+unprotected+absent</programlisting></listitem> + </varlistentry> + + <varlistentry> <term><varname>MountAPIVFS=</varname></term> <listitem><para>Takes a boolean argument. If on, a private mount namespace for the unit's processes is created @@ -3476,8 +3500,7 @@ StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZX <varlistentry> <term><varname>$NOTIFY_SOCKET</varname></term> - <listitem><para>The socket - <function>sd_notify()</function> talks to. See + <listitem><para>The socket <function>sd_notify()</function> talks to. See <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. </para></listitem> </varlistentry> @@ -3799,6 +3822,19 @@ StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZX convey.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>$FDSTORE</varname></term> + + <listitem><para>If the file descriptor store is enabled for a service + (i.e. <varname>FileDescriptorStoreMax=</varname> is set to a non-zero value, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details), this environment variable will be set to the maximum number of permitted entries, as + per the setting. Applications may check this environment variable before sending file descriptors + to the service manager via <function>sd_pid_notify_with_fds()</function> (see + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> for + details).</para></listitem> + </varlistentry> + </variablelist> <para>For system services, when <varname>PAMName=</varname> is enabled and <command>pam_systemd</command> is part diff --git a/man/systemd.image-policy.xml b/man/systemd.image-policy.xml new file mode 100644 index 0000000000..5ea9e46ec2 --- /dev/null +++ b/man/systemd.image-policy.xml @@ -0,0 +1,191 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="systemd.image-policy"> + + <refentryinfo> + <title>systemd.image-policy</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.image-policy</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.image-policy</refname> + <refpurpose>Disk Image Dissection Policy</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>In systemd, whenever a disk image (DDI) implementing the <ulink + url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable + Partitions Specification</ulink> is activated, a policy may be specified controlling which partitions to + mount and what kind of cryptographic protection to require. Such a disk image dissection policy is a + string that contains per-partition-type rules, separated by colons (<literal>:</literal>). The individual + rules consist of a partition identifier, an equal sign (<literal>=</literal>), and one or more flags + which may be set per partition. If multiple flags are specified per partition they are separated by a + plus sign (<literal>+</literal>).</para> + + <para>The partition identifiers currently defined are: <option>root</option>, <option>usr</option>, + <option>home</option>, <option>srv</option>, <option>esp</option>, <option>xbootldr</option>, + <option>swap</option>, <option>root-verity</option>, <option>root-verity-sig</option>, + <option>usr-verity</option>, <option>usr-verity-sig</option>, <option>tmp</option>, + <option>var</option>. These identifiers match the relevant partition types in the Discoverable Partitions + Specification, but are agnostic to CPU architectures. If the partition identifier is left empty it + defines the <emphasis>default</emphasis> policy for partitions defined in the Discoverable Partitions + Specification for which no policy flags are explicitly listed in the policy string.</para> + + <para>The following partition policy flags are defined that dictate the existence/absence, the use, and + the protection level of partitions:</para> + + <itemizedlist> + <listitem><para><option>unprotected</option> for partitions that shall exist and be used, but shall + come without cryptographic protection, lacking both Verity authentication and LUKS + encryption.</para></listitem> + + <listitem><para><option>verity</option> for partitions that shall exist and be used, with Verity + authentication. (Note: if a DDI image carries a data partition, along with a Verity partition and a + signature partition for it, and only the <option>verity</option> flag is set – and + <option>signed</option> is not –, then the image will be set up with Verity, but the signature data will + not be used. Or in other words: any DDI with a set of partitions that qualify for + <option>signature</option> also implicitly qualifies for <option>verity</option>, and in fact + <option>unprotected</option>).</para></listitem> + + <listitem><para><option>signed</option> for partitions that shall exist and be used, with Verity + authentication, which are also accompanied by a PKCS#7 signature of the Verity root + hash.</para></listitem> + + <listitem><para><option>encrypted</option> for partitions which shall exist and be used and are + encrypted with LUKS.</para></listitem> + + <listitem><para><option>unused</option> for partitions that shall exist but shall not be + used.</para></listitem> + + <listitem><para><option>absent</option> for partitions that shall not exist on the + image.</para></listitem> + </itemizedlist> + + <para>By setting a combination of the flags above, alternatives can be declared. For example the + combination <literal>unused+absent</literal> means: the partition may exist (in which case it shall not + be used) or may be absent. The combination of + <literal>unprotected+verity+signed+encrypted+unused+absent</literal> may be specified via the special + shortcut <literal>open</literal>, and indicates that the partition may exist or may be absent, but if it + exists is used, regardless of the protection level.</para> + + <para>As special rule: if none of the flags above are set for a listed partition identifier, the default + policy of <option>open</option> is implied, i.e. setting none of these flags listed above means + effectively all flags listed above will be set.</para> + + <para>The following partition policy flags are defined that dictate the state of specific GPT partition + flags:</para> + + <itemizedlist> + <listitem><para><option>read-only-off</option>, <option>read-only-on</option> to require that the + partitions have the read-only partition flag off or on.</para></listitem> + + <listitem><para><option>growfs-off</option>, <option>growfs-on</option> to require that the + partitions have the growfs partition flag off or on.</para></listitem> + </itemizedlist> + + <para>If both <option>read-only-off</option> and <option>read-only-on</option> are set for a partition, + then the state of the read-only flag on the partition is not dictated by the policy. Setting neither flag + is equivalent to setting both, i.e. setting neither of these two flags means effectively both will be + set. A similar logic applies to <option>growfs-off</option>/<option>growfs-on</option>.</para> + + <para>If partitions are not listed within an image policy string, the default policy flags are applied + (configurable via an empty partition identifier, see above). If no default policy flags are configured in + the policy string, it is implied to be <literal>absent+unused</literal>, except for the Verity partition + and their signature partitions where the policy is automatically derived from minimal protection level of + the data partition they protect, as encoded in the policy.</para> + </refsect1> + + <refsect1> + <title>Special Policies</title> + + <para>The special image policy string <literal>*</literal> is short for "use everything", i.e. is + equivalent to:</para> + + <programlisting>=verity+signed+encrypted+unprotected+unused+absent</programlisting> + + <para>The special image policy string <literal>-</literal> is short for "use nothing", i.e. is equivalent + to:</para> + + <programlisting>=unused+absent</programlisting> + + <para>The special image policy string <literal>~</literal> is short for "everything must be absent", + i.e. is equivalent to:</para> + + <programlisting>=absent</programlisting> + + </refsect1> + + <refsect1> + <title>Use</title> + + <para>Most systemd components that support operating with disk images support a + <option>--image-policy=</option> command line option to specify the image policy to use, and default to + relatively open policies by default (typically the <literal>*</literal> policy, as described above), + under the assumption that trust in disk images is established before the images are passed to the program + in question.</para> + + <para>For the host image itself + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + is responsible for processing the GPT partition table and making use of the included discoverable + partitions. It accepts an image policy via the kernel command line option + <option>systemd.image-policy=</option>.</para> + + <para>Note that image policies do not dictate how the components will mount and use disk images — they + only dictate which parts to avoid and which protection level and arrangement to require while + mounting/using them. For example, + <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> only + cares for the <filename>/usr/</filename> and <filename>/opt/</filename> trees inside a disk image, and + thus ignores any <filename>/home/</filename> partitions (and similar) in all cases, which might be + included in the image, regardless whether the configured image policy would allow access to it or + not. Similar, + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> is not + going to make use of any discovered swap device, regardless if the policy would allow that or not.</para> + + <para>Use the <command>image-policy</command> command of the + <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>8</manvolnum></citerefentry> tool + to analyze image policy strings, and determine what a specific policy string means for a specific + partition.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>The following image policy string dictates one read-only Verity-enabled <filename>/usr/</filename> + partition must exist, plus encrypted root and swap partitions. All other partitions are ignored:</para> + + <programlisting>usr=verity+read-only-on:root=encrypted:swap=encrypted</programlisting> + + <para>The following image policy string dictates an encrypted, writable root file system, and optional + <filename>/srv/</filename> file system that must be encrypted if it exists and no swap partition may + exist:</para> + + <programlisting>root=encrypted+read-only-off:srv=encrypted+absent:swap=absent</programlisting> + + <para>The following image policy string dictates a single root partition that may be encrypted, but + doesn't have to be, and ignores swap partitions, and uses all other partitions if they are available, possibly with encryption.</para> + + <programlisting>root=unprotected+encrypted:swap=absent+unused:=unprotected+encrypted+absent</programlisting> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.link.xml b/man/systemd.link.xml index 546a6a006b..cc851d31f9 100644 --- a/man/systemd.link.xml +++ b/man/systemd.link.xml @@ -1143,7 +1143,7 @@ Name=dmz0</programlisting> <example> <title>(Re-)applying a .link file to an interface</title> - <para>After a new .link file has been created, or an exisiting .link file modified, the new settings + <para>After a new .link file has been created, or an existing .link file modified, the new settings may be applied to the matching interface with the following commands:</para> <programlisting>$ sudo udevadm control --reload diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index b71cedfa26..7e6a52c711 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -829,7 +829,7 @@ <varlistentry> <term><varname>InheritInnerProtocol=</varname></term> <listitem> - <para>Takes a boolean. When true, inner Layer 3 protcol is set as Protocol Type in the GENEVE + <para>Takes a boolean. When true, inner Layer 3 protocol is set as Protocol Type in the GENEVE header instead of Ethernet. Defaults to false.</para> </listitem> </varlistentry> @@ -1718,7 +1718,9 @@ <term><varname>Endpoint=</varname></term> <listitem> <para>Sets an endpoint IP address or hostname, followed by a colon, and then - a port number. This endpoint will be updated automatically once to + a port number. IPv6 address must be in the square brackets. For example, + <literal>111.222.333.444:51820</literal> for IPv4 and <literal>[1111:2222::3333]:51820</literal> + for IPv6 address. This endpoint will be updated automatically once to the most recent source IP address and port of correctly authenticated packets from the peer at configuration time.</para> </listitem> diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml index c1eef7853b..ec94176c01 100644 --- a/man/systemd.nspawn.xml +++ b/man/systemd.nspawn.xml @@ -531,8 +531,11 @@ <varlistentry> <term><varname>Interface=</varname></term> - <listitem><para>Takes a space-separated list of interfaces to - add to the container. This option corresponds to the + <listitem><para>Takes a space-separated list of interfaces to add to the container. + The interface object is defined either by a single interface name, referencing the name on the host, + or a colon-separated pair of interfaces, in which case the first one references the name on the host, + and the second one the name in the container. + This option corresponds to the <option>--network-interface=</option> command line switch and implies <varname>Private=yes</varname>. This option is privileged (see above).</para></listitem> @@ -544,7 +547,9 @@ <listitem><para>Takes a space-separated list of interfaces to add MACLVAN or IPVLAN interfaces to, which are then added to - the container. These options correspond to the + the container. The interface object is defined either by a single interface name, referencing the name + on the host, or a colon-separated pair of interfaces, in which case the first one references the name + on the host, and the second one the name in the container. These options correspond to the <option>--network-macvlan=</option> and <option>--network-ipvlan=</option> command line switches and imply <varname>Private=yes</varname>. These options are diff --git a/man/systemd.preset.xml b/man/systemd.preset.xml index ab730d2cc2..5d46a88c3e 100644 --- a/man/systemd.preset.xml +++ b/man/systemd.preset.xml @@ -62,23 +62,23 @@ <refsect1> <title>Preset File Format</title> - <para>The preset files contain a list of directives consisting of - either the word <literal>enable</literal> or - <literal>disable</literal> followed by a space and a unit name - (possibly with shell style wildcards), separated by newlines. - Empty lines and lines whose first non-whitespace character is <literal>#</literal> or - <literal>;</literal> are ignored. Multiple instance names for unit - templates may be specified as a space separated list at the end of - the line instead of the customary position between <literal>@</literal> - and the unit suffix.</para> + <para>The preset files contain a list of directives, one per line. Empty lines and lines whose first + non-whitespace character is <literal>#</literal> or <literal>;</literal> are ignored. Each directive + consists of one of the words <literal>enable</literal>, <literal>disable</literal>, or + <literal>ignore</literal>, followed by whitespace and a unit name. The unit name may contain shell-style + wildcards.</para> + + <para>For the enable directive for template units, one or more instance names may be specified as a + space-separated list after the unit name. In this case, those instances will be enabled instead of the + instance specified via DefaultInstance= in the unit.</para> <para>Presets must refer to the "real" unit file, and not to any aliases. See <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a description of unit aliasing.</para> - <para>Two different directives are understood: - <literal>enable</literal> may be used to enable units by default, - <literal>disable</literal> to disable units by default.</para> + <para>Three different directives are understood: <literal>enable</literal> may be used to enable units by + default, <literal>disable</literal> to disable units by default, and <literal>ignore</literal> to ignore + units and leave existing configuration intact.</para> <para>If multiple lines apply to a unit name, the first matching one takes precedence over all others.</para> diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index f24822e605..f4e4a492a0 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -112,7 +112,7 @@ CPUWeight=20 DisableControllers=cpu / \ configuration for <filename>system.slice</filename> and <filename>user.slice</filename>, CPU resources will be split equally between them. Similarly, resources are allocated equally between children of <filename>user.slice</filename> and between the child slices beneath - <filename>user@1000.service</filename>. Assuming that there is no futher configuration of resources + <filename>user@1000.service</filename>. Assuming that there is no further configuration of resources or delegation below slices <filename>app.slice</filename> or <filename>session.slice</filename>, the <option>cpu</option> controller would not be enabled for units in those slices and CPU resources would be further allocated using other mechanisms, e.g. based on nice levels. The manager for user diff --git a/man/systemd.service.xml b/man/systemd.service.xml index f64a8e538f..7de1350a59 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1066,7 +1066,7 @@ <literal>FDSTORE=1</literal> messages. This is useful for implementing services that can restart after an explicit request or a crash without losing state. Any open sockets and other file descriptors which should not be closed during the restart may be stored this way. Application state - can either be serialized to a file in <filename>/run/</filename>, or better, stored in a + can either be serialized to a file in <varname>RuntimeDirectory=</varname>, or stored in a <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory file descriptor. Defaults to 0, i.e. no file descriptors may be stored in the service manager. All file descriptors passed to the service manager from a specific service are passed back @@ -1075,7 +1075,8 @@ details about the precise protocol used and the order in which the file descriptors are passed). Any file descriptors passed to the service manager are automatically closed when <constant>POLLHUP</constant> or <constant>POLLERR</constant> is seen on them, or when the service is - fully stopped and no job is queued or being executed for it. If this option is used, + fully stopped and no job is queued or being executed for it (the latter can be tweaked with + <varname>FileDescriptorStorePreserve=</varname>, see below). If this option is used, <varname>NotifyAccess=</varname> (see above) should be set to open access to the notification socket provided by systemd. If <varname>NotifyAccess=</varname> is not set, it will be implicitly set to <option>main</option>.</para> @@ -1089,7 +1090,28 @@ allow unprivileged clients to query the list of currently open file descriptors of a service. Sensitive data may hence be safely placed inside the referenced files, but should not be attached to the metadata (e.g. included in filenames) of the stored file - descriptors.</para></listitem> + descriptors.</para> + + <para>If this option is set to a non-zero value the <varname>$FDSTORE</varname> environment variable + will be set for processes invoked for this service. See + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FileDescriptorStorePreserve=</varname></term> + <listitem><para>Takes one of <constant>no</constant>, <constant>yes</constant>, + <constant>restart</constant> and controls when to release the service's file descriptor store + (i.e. when to close the contained file descriptors, if any). If set to <constant>no</constant> the + file descriptor store is automatically released when the service is stopped; if + <constant>restart</constant> (the default) it is kept around as long as the unit is neither inactive + nor failed, or a job is queued for the service, or the service is expected to be restarted. If + <constant>yes</constant> the file descriptor store is kept around until the unit is removed from + memory (i.e. is not referenced anymore and inactive). The latter is useful to keep entries in the + file descriptor store pinned until the service manage exits.</para> + + <para>Use <command>systemctl clean --what=fdstore …</command> to release the file descriptor store + explicitly.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/systemd.xml b/man/systemd.xml index 1a68301d50..ca9e4e9988 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -681,6 +681,11 @@ </varlistentry> <varlistentry> + <term><varname>$SYSTEMD_LOG_RATELIMIT_KMSG</varname></term> + <listitem><xi:include href="common-variables.xml" xpointer="log-ratelimit-kmsg" /></listitem> + </varlistentry> + + <varlistentry> <term><varname>$XDG_CONFIG_HOME</varname></term> <term><varname>$XDG_CONFIG_DIRS</varname></term> <term><varname>$XDG_DATA_HOME</varname></term> @@ -865,13 +870,16 @@ <term><varname>systemd.log_target=</varname></term> <term><varname>systemd.log_time</varname></term> <term><varname>systemd.log_tid</varname></term> + <term><varname>systemd.log_ratelimit_kmsg</varname></term> <listitem><para>Controls log output, with the same effect as the <varname>$SYSTEMD_LOG_COLOR</varname>, <varname>$SYSTEMD_LOG_LEVEL</varname>, <varname>$SYSTEMD_LOG_LOCATION</varname>, <varname>$SYSTEMD_LOG_TARGET</varname>, - <varname>$SYSTEMD_LOG_TIME</varname>, and <varname>$SYSTEMD_LOG_TID</varname> environment variables - described above. <varname>systemd.log_color</varname>, <varname>systemd.log_location</varname>, - <varname>systemd.log_time</varname>, and <varname>systemd.log_tid=</varname> can be specified without + <varname>$SYSTEMD_LOG_TIME</varname>, <varname>$SYSTEMD_LOG_TID</varname> and + <varname>$SYSTEMD_LOG_RATELIMIT_KMSG</varname> environment variables described above. + <varname>systemd.log_color</varname>, <varname>systemd.log_location</varname>, + <varname>systemd.log_time</varname>, <varname>systemd.log_tid</varname> and + <varname>systemd.log_ratelimit_kmsg</varname> can be specified without an argument, with the same effect as a positive boolean.</para></listitem> </varlistentry> diff --git a/man/veritytab.xml b/man/veritytab.xml index dc2f11c31e..557d13e1ed 100644 --- a/man/veritytab.xml +++ b/man/veritytab.xml @@ -61,6 +61,62 @@ This is based on crypttab(5). <variablelist class='fstab-options'> <varlistentry> + <term><option>superblock=<replaceable>BOOL</replaceable></option></term> + + <listitem><para>Use dm-verity with or without permanent on-disk superblock.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>format=<replaceable>NUMBER</replaceable></option></term> + + <listitem><para>Specifies the hash version type. Format type 0 is original Chrome OS version. Format type 1 is + modern version.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>data-block-size=<replaceable>BYTES</replaceable></option></term> + + <listitem><para>Used block size for the data device. (Note kernel supports only page-size as maximum + here; Multiples of 512 bytes.) </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>hash-block-size=<replaceable>BYTES</replaceable></option></term> + + <listitem><para>Used block size for the hash device. (Note kernel supports only page-size as maximum + here; Multiples of 512 bytes.)</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>data-blocks=<replaceable>BLOCKS</replaceable></option></term> + + <listitem><para>Number of blocks of data device used in verification. If not specified, the whole device is + used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>hash-offset=<replaceable>BYTES</replaceable></option></term> + + <listitem><para>Offset of hash area/superblock on <literal>hash-device</literal>. (Multiples of 512 bytes.) + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>salt=<replaceable>HEX</replaceable></option></term> + + <listitem><para>Salt used for format or verification. Format is a hexadecimal string; 256 bytes long maximum; + <literal>-</literal>is the special value for empty.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>uuid=<replaceable>UUID</replaceable></option></term> + + <listitem><para>Use the provided UUID for format command instead of generating new one. The UUID must be + provided in standard UUID format, e.g. 12345678-1234-1234-1234-123456789abc.</para></listitem> + <listitem><para></para></listitem> + </varlistentry> + + <varlistentry> <term><option>ignore-corruption</option></term> <term><option>restart-on-corruption</option></term> <term><option>panic-on-corruption</option></term> @@ -95,6 +151,37 @@ This is based on crypttab(5). </varlistentry> <varlistentry> + <term><option>hash=<replaceable>HASH</replaceable></option></term> + + <listitem><para>Hash algorithm for dm-verity. This should be the name of the algorithm, like "sha1". For default + see <command>veritysetup --help</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>fec-device=<replaceable>PATH</replaceable></option></term> + + <listitem><para>Use forward error correction (FEC) to recover from corruption if hash verification fails. Use + encoding data from the specified device. The fec device argument can be block device or file image. For format, + if fec device path doesn't exist, it will be created as file. Note: block sizes for data and hash devices must + match. Also, if the verity data_device is encrypted the fec_device should be too.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>fec-offset=<replaceable>BYTES</replaceable></option></term> + + <listitem><para>This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding + data. (Aligned on 512 bytes.)</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>fec-roots=<replaceable>NUM</replaceable></option></term> + + <listitem><para>Number of generator roots. This equals to the number of parity bytes in the encoding data. In + RS(M, N) encoding, the number of roots is M-N. M is 255 and M-N is between 2 and 24 (including).</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>root-hash-signature=<replaceable>PATH</replaceable>|base64:<replaceable>HEX</replaceable></option></term> <listitem><para>A base64 string encoding the root hash signature prefixed by <literal>base64:</literal> or a |