Fixes #26761.
allows one to ship multiple sets of Secure Boot variables and choose which one to enroll at runtime.
</para>
- <para>Supported Secure Boot variables are one database for authorized images, one key exchange key
- (KEK) and one platform key (PK). For more information, refer to the <ulink
- url="https://uefi.org/specifications">UEFI specification</ulink>, under Secure Boot and Driver
+ <para>Supported Secure Boot variables are one database for authorized images, one for the key
+ exchange key (KEK) and one for the platform key (PK). For more information, refer to the
+ <ulink url="https://uefi.org/specifications">UEFI specification</ulink>, under Secure Boot and Driver
Signing. Another resource that describe the interplay of the different variables is the
<ulink url="https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/uefi_secure_boot">
EDK2 documentation</ulink>.</para>
<term><varname>$SYSTEMD_NSS_RESOLVE_CACHE</varname></term>
<listitem><para>Takes a boolean argument. When false, the cache of previously queried records will
- not be used by <command>systemd-resolved</command>.</para></listitem>
+ not be used by
+ <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+ </para></listitem>
</varlistentry>
</variablelist>
<term><varname>$SYSTEMD_NSS_RESOLVE_NETWORK</varname></term>
<listitem><para>Takes a boolean argument. When false, answers will be returned without using the
- network, i.e. either from local sources or the cache in <command>systemd-resolved</command>.
+ network, i.e. either from local sources or the cache in
+ <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
</variablelist>
only provided in a best effort fashion: it is not guaranteed to be set, and it is not guaranteed to be
the only trigger. It is only guaranteed to be a valid trigger that caused the activation job to be
enqueued and complete successfully. The key value pairs correspond (in lowercase) to the environment
- variables described in the <literal>Environment Variables Set on Triggered Units</literal> section in
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
- Note that new key value pair may be added at any time in future versions. Existing entries will not be
+ variables described in the <literal>Environment Variables Set or Propagated by the Service
+ Manager</literal> section in
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Note
+ that new key value pair may be added at any time in future versions. Existing entries will not be
removed.</para>
</refsect2>
<para>Note that <varname>CopyFiles=</varname> will skip copying files that aren't supported by the
target filesystem (e.g symlinks, fifos, sockets and devices on vfat). When an unsupported file type
- is encountered, repart will skip copying this file and write a log message about it.</para>
+ is encountered, <command>systemd-repart</command> will skip copying this file and write a log message
+ about it.</para>
<para>Note that <command>systemd-repart</command> does not change the UIDs/GIDs of any copied files
and directories. When running <command>systemd-repart</command> as an unprivileged user to build an
<para>Note that when populating XFS filesystems with <command>systemd-repart</command> and loop
devices are not available, populating XFS filesystems with files containing spaces, tabs or newlines
- will fail due to limitations of mkfs.xfs's protofile format.</para>
+ will fail due to limitations of <citerefentry
+ project='man-pages'><refentrytitle>mkfs.xfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ protofile format.</para>
<para>This option cannot be combined with <varname>CopyBlocks=</varname>.</para>
<term><varname>SplitName=</varname></term>
<listitem><para>Configures the suffix to append to split artifacts when the <option>--split</option>
- option of <command>systemd-repart</command> is used. Simple specifier expansion is supported, see
- below. Defaults to <literal>%t</literal>. To disable split artifact generation for a partition, set
- <varname>SplitName=</varname> to <literal>-</literal>.</para></listitem>
+ option of
+ <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry> is
+ used. Simple specifier expansion is supported, see below. Defaults to <literal>%t</literal>. To
+ disable split artifact generation for a partition, set <varname>SplitName=</varname> to
+ <literal>-</literal>.</para></listitem>
</varlistentry>
<varlistentry>
times. Specifically:</para>
<orderedlist>
- <listitem><para>In UEFI mode, the <filename>systemd-boot</filename> or
- <filename>systemd-stub</filename> components load the boot loader random seed off the ESP, hash it with
- available entropy and the system token, and then update it on disk. A derived seed is passed to the
- kernel which writes it to its entropy pool.</para></listitem>
+ <listitem><para>In UEFI mode, the
+ <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> or
+ <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ components load the boot loader random seed from the ESP, hash it with available entropy and the system
+ token, and then update it on disk. A derived seed is passed to the kernel which writes it to its
+ entropy pool.</para></listitem>
<listitem><para>In userspace the <filename>systemd-random-seed.service</filename> service loads the OS
random seed, writes it to the kernel entropy pool, and then updates it on disk with a new value derived
</refsect1>
<refsect1>
- <title>Using systemd-boot in virtual machines.</title>
+ <title>Using <command>systemd-boot</command> in virtual machines</title>
<para>When using qemu with OVMF (UEFI Firmware for virtual machines) the <option>-kernel</option> switch
works not only for linux kernels, but for any EFI binary, including sd-boot and unified linux
- kernels. Example command line for loading sd-boot on x64:</para>
+ kernels. Example command line for loading <command>systemd-boot</command> on x64:</para>
<para>
<command>qemu-system-x86_64 <replaceable>[ ... ]</replaceable>
<term><option>--mtree</option></term>
<term><option>-l</option></term>
- <listitem><para>Generates a BSD <citerefentry
- project='die-net'><refentrytitle>mtree</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ <listitem><para>Generates a BSD
+ <citerefentry project='die-net'><refentrytitle>mtree</refentrytitle><manvolnum>8</manvolnum></citerefentry>
compatible file manifest of the specified disk image. This is useful for comparing disk image
contents in detail, including inode information and other metadata. While the generated manifest will
contain detailed inode information, it currently excludes extended attributes, file system
- capabilities, MAC labels, <citerefentry
- project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry> file
- flags, btrfs subvolume information, and various other file metadata. File content information is
- shown via a SHA256 digest. Additional fields might be added in future. Note that inode information
- such as link counts, inode numbers and timestamps is excluded from the output on purpose, as it
- typically complicates reproducibility.</para></listitem>
+ capabilities, MAC labels,
+ <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ file flags,
+ <citerefentry project='url'><refentrytitle url='https://btrfs.wiki.kernel.org/index.php/Manpage/btrfs(5)'>btrfs</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ subvolume information, and various other file metadata. File content information is shown via a
+ SHA256 digest. Additional fields might be added in future. Note that inode information such as link
+ counts, inode numbers and timestamps is excluded from the output on purpose, as it typically
+ complicates reproducibility.</para></listitem>
</varlistentry>
<varlistentry>
cycle. This is equivalent to <command>systemd-notify RELOADING=1</command> (but implicitly also sets
a <varname>MONOTONIC_USEC=</varname> field as required for <varname>Type=notify-reload</varname>
services, see
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details). For details about the semantics of this option see
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
</varlistentry>
<option>0 … y</option> seen from inside of the container is mapped to <option>x + z</option> in the
<option>x … x + y</option> range on the host. Other host users are mapped to
<option>nobody</option> inside the container.</para></listitem>
+
<listitem><para>If <option>idmap</option> is used, any user <option>z</option> in the UID range
<option>0 … y</option> as seen from inside the container is mapped to the same <option>z</option>
- in the same <option>0 … y</option> range on the host. All host users outside of that range are
- mapped to <option>nobody</option> inside the container.</para></listitem>
+ in the same <option>0 … y</option> range on the host. Other host users are mapped to
+ <option>nobody</option> inside the container.</para></listitem>
+
<listitem><para>If <option>rootidmap</option> is used, the user <option>0</option> seen from inside
- of the container is mapped to <option>p</option> on the host. All host users outside of that range
- are mapped to <option>nobody</option> inside the container.</para></listitem>
+ of the container is mapped to <option>p</option> on the host. Other host users are mapped to
+ <option>nobody</option> inside the container.</para></listitem>
</itemizedlist></para>
<para>Whichever ID mapping option is used, the same mapping will be used for users and groups IDs. If
<listitem><para><literal>enter-initrd</literal> — early when the initrd initializes, before activating
system extension images for the initrd. It acts as a barrier between the time where the kernel
initializes and where the initrd starts operating and enables system extension images, i.e. code
- shipped outside of the UKI. (This extension happens when
- <filename>systemd-pcrphase-initrd.service</filename> is started.)</para></listitem>
+ shipped outside of the UKI. (This extension happens when the
+ <citerefentry><refentrytitle>systemd-pcrphase-initrd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ service is started.)</para></listitem>
<listitem><para><literal>leave-initrd</literal> — when the initrd is about to transition into the host
- file system. It acts as barrier between initrd code and host OS code. (This extension happens when
- <filename>systemd-pcrphase-initrd.service</filename> is stopped.)</para></listitem>
+ file system. It acts as barrier between initrd code and host OS code. (This extension happens when the
+ <filename>systemd-pcrphase-initrd.service</filename> service is stopped.)</para></listitem>
<listitem><para><literal>sysinit</literal> — when basic system initialization is complete (which
includes local file systems having been mounted), and the system begins starting regular system
- services. (This extension happens when <filename>systemd-pcrphase-sysinit.service</filename> is
- started.)</para></listitem>
+ services. (This extension happens when the
+ <citerefentry><refentrytitle>systemd-pcrphase-sysinit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ service is started.)</para></listitem>
<listitem><para><literal>ready</literal> — during later boot-up, after remote file systems have been
activated (i.e. after <filename>remote-fs.target</filename>), but before users are permitted to log in
(i.e. before <filename>systemd-user-sessions.service</filename>). It acts as barrier between the time
where unprivileged regular users are still prohibited to log in and where they are allowed to log in.
- (This extension happens when <filename>systemd-pcrphase.service</filename> is started.)
+ (This extension happens when the <filename>systemd-pcrphase.service</filename> service is started.)
</para></listitem>
<listitem><para><literal>shutdown</literal> — when the system shutdown begins. It acts as barrier
between the time the system is fully up and running and where it is about to shut down. (This extension
- happens when <filename>systemd-pcrphase.service</filename> is stopped.)</para></listitem>
+ happens when the <filename>systemd-pcrphase.service</filename> service is stopped.)</para></listitem>
<listitem><para><literal>final</literal> — at the end of system shutdown. It acts as barrier between
the time the service manager still runs and when it transitions into the final shutdown phase where
- service management is not available anymore. (This extension happens when
- <filename>systemd-pcrphase-sysinit.service</filename> is stopped.)</para></listitem>
+ service management is not available anymore. (This extension happens when the
+ <citerefentry><refentrytitle>systemd-pcrphase-sysinit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ service is stopped.)</para></listitem>
</orderedlist>
<para>During a regular system lifecycle, PCR 11 is extended with the strings
<listitem><para>This option specifies for which partition types <command>systemd-repart</command>
should defer. All partitions that are deferred using this option are still taken into account when
calculating the sizes and offsets of other partitions, but aren't actually written to the disk image.
- The net effect of this option is that if you run <command>systemd-repart</command> again without
- these options, the missing partitions will be added as if they had not been deferred the first time
+ The net effect of this option is that if you run <command>systemd-repart</command> again without this
+ option, the missing partitions will be added as if they had not been deferred the first time
<command>systemd-repart</command> was executed.</para></listitem>
</varlistentry>
<listitem><para>This option allows configuring the sector size of the image produced by
<command>systemd-repart</command>. It takes a value that is a power of <literal>2</literal> between
<literal>512</literal> and <literal>4096</literal>. This option is useful when building images for
- disks that use a different sector size as the disk on which the image is produced.</para></listitem>.
+ disks that use a different sector size as the disk on which the image is produced.</para></listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="help" />
<term><varname>LogRateLimitIntervalSec=</varname></term>
<term><varname>LogRateLimitBurst=</varname></term>
- <listitem><para>Configures the rate limiting that is applied to log messages generated by this
- unit. If, in the time interval defined by <varname>LogRateLimitIntervalSec=</varname>, more messages
- than specified in <varname>LogRateLimitBurst=</varname> are logged by a service, all further messages
+ <listitem><para>Configures the rate limiting that is applied to log messages generated by this unit.
+ If, in the time interval defined by <varname>LogRateLimitIntervalSec=</varname>, more messages than
+ specified in <varname>LogRateLimitBurst=</varname> are logged by a service, all further messages
within the interval are dropped until the interval is over. A message about the number of dropped
messages is generated. The time specification for <varname>LogRateLimitIntervalSec=</varname> may be
- specified in the following units: "s", "min", "h", "ms", "us" (see
+ specified in the following units: "s", "min", "h", "ms", "us". See
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
- details). The default settings are set by <varname>RateLimitIntervalSec=</varname> and
+ details. The default settings are set by <varname>RateLimitIntervalSec=</varname> and
<varname>RateLimitBurst=</varname> configured in
- <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note
- that this only applies to log messages that are processed by the logging subsystem, i.e. by
- <filename>systemd-journald.service</filename>. This means, if you connect a service's stderr directly
- to a file via <varname>StandardOutput=file:…</varname> or a similar setting the rate limiting will
- not be applied to messages written that way (but they will be enforced for messages generated via
- <function>syslog()</function> or similar).</para></listitem>
+ <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ Note that this only applies to log messages that are processed by the logging subsystem, i.e. by
+ <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ This means that if you connect a service's stderr directly to a file via
+ <varname>StandardOutput=file:…</varname> or a similar setting, the rate limiting will not be applied
+ to messages written that way (but it will be enforced for messages generated via
+ <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ and similar functions).</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>ID_NET_NAME_ONBOARD=<replaceable>prefix</replaceable><constant>d</constant><replaceable>number</replaceable></varname></term>
<listitem><para>This name is set based on the numeric ordering information given by the firmware
- for on-board devices. Different schemes are used depending on the firmware type, as described in the table below.</para>
+ for on-board devices. Different schemes are used depending on the firmware type, as described in
+ the table below.</para>
<table>
- <title>Onboard naming schemes</title>
+ <title>On-board naming schemes</title>
<tgroup cols='2'>
<thead>
<tbody>
<row>
<entry><replaceable>prefix</replaceable><constant>o</constant><replaceable>number</replaceable></entry>
- <entry>PCI onboard index</entry>
+ <entry>PCI on-board index</entry>
</row>
<row>
numbers, which could either result in an incorrect value of the <varname>ID_NET_NAME_SLOT</varname>
property or none at all.</para>
- <para>Some firmware and hypervisor implementations report unreasonably high numbers for the onboard
- index. To prevent the generation of bogus onbard interface names, index numbers greater than 16381
- (2¹⁴-1) were ignored. For s390 PCI devices index values up to 65535 (2¹⁶-1) are valid. To account
- for that, the limit was increased to 65535.</para>
+ <para>Some firmware and hypervisor implementations report unreasonably high numbers for the
+ on-board index. To prevent the generation of bogus onbard interface names, index numbers greater
+ than 16381 (2¹⁴-1) were ignored. For s390 PCI devices index values up to 65535 (2¹⁶-1) are valid.
+ To account for that, the limit was increased to 65535.</para>
<para>The udev rule <varname>NAME=</varname> replaces <literal>:</literal>,
<literal>/</literal>, and <literal>%</literal> with an underscore (<literal>_</literal>), and
<refsect1>
<title>See Also</title>
<para>Environment variables with details on the trigger will be set for triggered units. See the
- <literal>Environment Variables Set on Triggered Units</literal> section in
+ section <literal>Environment Variables Set or Propagated by the Service Manager</literal> in
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for more details.</para>
<para>
<option>notify</option>. However, it extends the logic in one way: the
<constant>SIGHUP</constant> UNIX process signal is sent to the service's main process when the
service is asked to reload. (The signal to send can be tweaked via
- <varname>ReloadSignal=</varname>, see below.). When
+ <varname>ReloadSignal=</varname>, see below.) When
initiating the reload process the service is then expected to reply with a notification message
via <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
that contains the <literal>RELOADING=1</literal> field in combination with
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details.</para>
- <para>This setting also applies to <command>systemd-oomd</command>. Similarly to the kernel OOM
- kills, this setting determines the state of the unit after <command>systemd-oomd</command> kills a
- cgroup associated with it.</para></listitem>
+ <para>This setting also applies to
+ <citerefentry><refentrytitle>systemd-oomd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+ Similarly to the kernel OOM kills performed by the kernel, this setting determines the state of the
+ unit after <command>systemd-oomd</command> kills a cgroup associated with it.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>vmm.notify_socket</varname></term>
<listitem>
- <para>This credential is parsed looking for an <constant>AF_VSOCK</constant> or
- <constant>AF_UNIX</constant> address where to send a <constant>READY=1</constant>
- notification datagram when the system has finished booting. See:
- <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- This is useful for hypervisors/VMMs or other processes on the host
- to receive a notification via VSOCK 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
- tried instead. The credential payload for <constant>AF_VSOCK</constant> should be
- in the form: <literal>vsock:CID:PORT</literal>.</para>
+ <para>Contains a <constant>AF_VSOCK</constant> or <constant>AF_UNIX</constant> address where to
+ send a <constant>READY=1</constant> notification datagram when the system has finished booting. See
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
+ more information. Note that in case the hypervisor does not support <constant>SOCK_DGRAM</constant>
+ over <constant>AF_VSOCK</constant>, <constant>SOCK_SEQPACKET</constant> will be tried instead. The
+ credential payload for <constant>AF_VSOCK</constant> should be in the form
+ <literal>vsock:CID:PORT</literal>.</para>
+
+ <para>This feature is useful for hypervisors/VMMs or other processes on the host to receive a
+ notification via VSOCK when a virtual machine has finished booting.</para>
</listitem>
</varlistentry>
<refsect1>
<title>See Also</title>
<para>Environment variables with details on the trigger will be set for triggered units. See the
- <literal>Environment Variables Set on Triggered Units</literal> section in
+ <literal>Environment Variables Set or Propagated by the Service Manager</literal> section in
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for more details.</para>
<para>
<constant>subvolume</constant>. For details about the resource types, see above. This option is
mandatory.</para>
- <para>Note that only some combinations of source and target resource types are supported, see
+ <para>Note that only certain combinations of source and target resource types are supported, see
above.</para></listitem>
</varlistentry>
</variablelist>
<term><option>--measure</option></term>
<term><option>--no-measure</option></term>
- <listitem><para>Enable or disable a call to <command>systemd-measure</command> to print
- pre-calculated PCR values. Defaults to false.</para></listitem>
+ <listitem><para>Enable or disable a call to
+ <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ to print pre-calculated PCR values. Defaults to false.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>SigningEngine=<replaceable>ENGINE</replaceable></varname></term>
<term><option>--signing-engine=<replaceable>ENGINE</replaceable></option></term>
- <listitem><para>An "engine" to for signing of the resulting binary. This option is currently passed
+ <listitem><para>An "engine" for signing of the resulting binary. This option is currently passed
verbatim to the <option>--engine=</option> option of
<citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para></listitem>
projects / thirdparty / systemd.git / commitdiff
