system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-07-08 20:15:55 +00:00
Code Issues Projects Releases Wiki Activity
3001339dc5
systemd/man/sysupdate.d.xml

954 lines
49 KiB
XML
Raw Normal View History

man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: use same version in public and system ident.
2023-12-25 14:48:33 +00:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="sysupdate.d" conditional='ENABLE_SYSUPDATE'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sysupdate.d</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sysupdate.d</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>sysupdate.d</refname>
<refpurpose>Transfer Definition Files for Automatic Updates</refpurpose>
</refnamediv>
<refsynopsisdiv>
man: use <simplelist> for file lists in synopsis With <para><filename>…</filename></para>, we get a separate "paragraph" for each line, i.e. entries separated by empty lines. This uses up a lot of space and was only done because docbook makes it hard to insert a newline. In some other places, <literallayout> was used, but then we cannot indent the source text (because the whitespace would end up in the final page). We can get the desired result with <simplelist>. With <simplelist> the items are indented in roff output, but not in html output. In some places this looks better then no indentation, and in others it would probably be better to have no indent. But this is a minor issue and we cannot control that. (I didn't convert all spots. There's a bunch of other man pages which have two lines, e.g. an executable and service file, and it doesn't matter there so much.)
2023-12-14 11:52:03 +00:00
<para><simplelist>
<member><filename>/etc/sysupdate.d/*.conf</filename></member>
<member><filename>/run/sysupdate.d/*.conf</filename></member>
man: document /usr/local/lib in search paths
2024-06-05 15:08:57 +00:00
<member><filename>/usr/local/lib/sysupdate.d/*.conf</filename></member>
man: use <simplelist> for file lists in synopsis With <para><filename>…</filename></para>, we get a separate "paragraph" for each line, i.e. entries separated by empty lines. This uses up a lot of space and was only done because docbook makes it hard to insert a newline. In some other places, <literallayout> was used, but then we cannot indent the source text (because the whitespace would end up in the final page). We can get the desired result with <simplelist>. With <simplelist> the items are indented in roff output, but not in html output. In some places this looks better then no indentation, and in others it would probably be better to have no indent. But this is a minor issue and we cannot control that. (I didn't convert all spots. There's a bunch of other man pages which have two lines, e.g. an executable and service file, and it doesn't matter there so much.)
2023-12-14 11:52:03 +00:00
<member><filename>/usr/lib/sysupdate.d/*.conf</filename></member>
</simplelist></para>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><filename>sysupdate.d/*.conf</filename> files describe how specific resources on the local system
shall be updated from a remote source. Each such file defines one such transfer: typically a remote
HTTP/HTTPS resource as source; and a local file, directory or partition as target. This may be used as a
simple, automatic, atomic update mechanism for the OS itself, for containers, portable services or system
extension images — but in fact may be used to update any kind of file from a remote source.</para>
<para>The
<citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>
command reads these files and uses them to determine which local resources should be updated, and then
executes the update.</para>
<para>Both the remote HTTP/HTTPS source and the local target typically exist in multiple, concurrent
versions, in order to implement flexible update schemes, e.g. A/B updating (or a superset thereof,
e.g. A/B/C, A/B/C/D, …).</para>
<para>Each <filename>*.conf</filename> file defines one transfer, i.e. describes one resource to
update. Typically, multiple of these files (i.e. multiple of such transfers) are defined together, and
are bound together by a common version identifier in order to update multiple resources at once on each
update operation, for example to update a kernel, a root file system and a Verity partition in a single,
combined, synchronized operation, so that only a combined update of all three together constitutes a
complete update.</para>
<para>Each <filename>*.conf</filename> file contains three sections: [Transfer], [Source] and [Target].</para>
</refsect1>
<refsect1>
<title>Basic Mode of Operation</title>
<para>Disk-image based OS updates typically consist of multiple different resources that need to be
updated together, for example a secure OS update might consist of a root file system image to drop into a
partition, a matching Verity integrity data partition image, and a kernel image prepared to boot into the
combination of the two partitions. The first two resources are files that are downloaded and placed in a
disk partition, the latter is a file that is downloaded and placed in a regular file in the boot file
system (e.g. EFI system partition). Hence, during an update of a hypothetical operating system "foobarOS"
to a hypothetical version 47 the following operations should take place:</para>
<orderedlist>
<listitem><para>A file <literal>https://download.example.com/foobarOS_47.root.xz</literal> should be
downloaded, decompressed and written to a previously unused partition with GPT partition type UUID
4f68bce3-e8cd-4db1-96e7-fbcaf984b709 for x86-64, as per <ulink
tree-wide: BLS and DPS are now on uapi-group website
2022-11-14 08:44:39 +00:00
url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
Specification</ulink>.</para></listitem>
<listitem><para>Similarly, a file <literal>https://download.example.com/foobarOS_47.verity.xz</literal>
should be downloaded, decompressed and written to a previously empty partition with GPT partition type
man: Miscellaneous fixes Fixes: #24056
2022-07-19 08:57:33 +00:00
UUID of 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5 (i.e. the partition type for Verity integrity information
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
for x86-64 root file systems).</para></listitem>
<listitem><para>Finally, a file <literal>https://download.example.com/foobarOS_47.efi.xz</literal> (a
tree-wide: BLS and DPS are now on uapi-group website
2022-11-14 08:44:39 +00:00
unified kernel, as per <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
sysupdate.d: Add way to drop binaries into $BOOT As described in the BLS, we should place binaries into the XBOOTLDR directory if it is available, otherwise into the ESP. Thus, we might need to put binaries into /boot or into /efi depending on the existence of the XBOOTLDR partition. With this change, we introduce a new PathRelativeTo= config option that makes this functionality possible
2023-05-26 04:47:47 +00:00
Specification</ulink> Type #2) should be downloaded, decompressed and written to the $BOOT file system,
i.e. to <filename>EFI/Linux/foobarOS_47.efi</filename> in the ESP or XBOOTLDR partition.</para></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</orderedlist>
<para>The version-independent generalization of this would be (using the special marker
<literal>@v</literal> as wildcard for the version identifier):</para>
<orderedlist>
<listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.root.xz</literal>
→ a local, previously empty GPT partition of type 4f68bce3-e8cd-4db1-96e7-fbcaf984b709, with the label to
be set to <literal>foobarOS_@v</literal>.</para></listitem>
<listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.verity.xz</literal>
→ a local, previously empty GPT partition of type 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5, with the label to be
set to <literal>foobarOS_@v_verity</literal>.</para></listitem>
<listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.efi.xz</literal>
sysupdate.d: Add way to drop binaries into $BOOT As described in the BLS, we should place binaries into the XBOOTLDR directory if it is available, otherwise into the ESP. Thus, we might need to put binaries into /boot or into /efi depending on the existence of the XBOOTLDR partition. With this change, we introduce a new PathRelativeTo= config option that makes this functionality possible
2023-05-26 04:47:47 +00:00
→ a local file <filename>$BOOT/EFI/Linux/foobarOS_@v.efi</filename>.</para></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</orderedlist>
<para>An update can only complete if the relevant URLs provide their resources for the same version,
i.e. for the same value of <literal>@v</literal>.</para>
<para>The above may be translated into three <filename>*.conf</filename> files in
<filename>sysupdate.d/</filename>, one for each resource to transfer. The <filename>*.conf</filename>
files configure the type of download, and what place to write the download to (i.e. whether to a
partition or a file in the file system). Most importantly these files contain the URL, partition name and
filename patterns shown above that describe how these resources are called on the source and how they
shall be called on the target.</para>
<para>In order to enumerate available versions and figuring out candidates to update to, a mechanism is
necessary to list suitable files:</para>
<itemizedlist>
<listitem><para>For partitions: the surrounding GPT partition table contains a list of defined
partitions, including a partition type UUID and a partition label (in this scheme the partition label
man: Miscellaneous fixes Fixes: #24056
2022-07-19 08:57:33 +00:00
plays a role for the partition similar to the filename for a regular file).</para></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
<listitem><para>For regular files: the directory listing of the directory the files are contained in
provides a list of existing files in a straightforward way.</para></listitem>
<listitem><para>For HTTP/HTTPS sources a simple scheme is used: a manifest file
<filename>SHA256SUMS</filename>, following the format defined by <citerefentry
project='man-pages'><refentrytitle>sha256sum</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
lists file names and their SHA256 hashes.</para></listitem>
</itemizedlist>
<para>Transfers are done in the alphabetical order of the <filename>.conf</filename> file names they are
defined in. First, the resource data is downloaded directly into a target file/directory/partition. Once
this is completed for all defined transfers, in a second step the files/directories/partitions are
renamed to their final names as defined by the target <varname>MatchPattern=</varname>, again in the
order the <filename>.conf</filename> transfer file names dictate. This step is not atomic, however it is
guaranteed to be executed strictly in order with suitable disk synchronization in place. Typically, when
updating an OS one of the transfers defines the entry point when booting. Thus it is generally a good idea
to order the resources via the transfer configuration file names so that the entry point is written
last, ensuring that any abnormal termination does not leave an entry point around whose backing is not
established yet. In the example above it would hence make sense to establish the EFI kernel image last
and thus give its transfer configuration file the alphabetically last name.</para>
<para>See below for an extended, more specific example based on the above.</para>
</refsect1>
<refsect1>
<title>Resource Types</title>
<para>Each transfer file defines one source resource to transfer to one target resource. The following
resource types are supported:</para>
<orderedlist>
<listitem><para>Resources of type <literal>url-file</literal> encapsulate a file on a web server,
referenced via a HTTP or HTTPS URL. When an update takes place, the file is downloaded and decompressed
and then written to the target file or partition. This resource type is only available for sources, not
for targets. The list of available versions of resources of this type is encoded in
<filename>SHA256SUMS</filename> manifest files, accompanied by
<filename>SHA256SUMS.gpg</filename> detached signatures.</para></listitem>
<listitem><para>The <literal>url-tar</literal> resource type is similar, but the file must be a
<filename>.tar</filename> archive. When an update takes place, the file is decompressed and unpacked
into a directory or btrfs subvolume. This resource type is only available for sources, not for
targets. Just like <literal>url-file</literal>, <literal>url-tar</literal> version enumeration makes
use of <filename>SHA256SUMS</filename> files, authenticated via
<filename>SHA256SUMS.gpg</filename>.</para></listitem>
<listitem><para>The <literal>regular-file</literal> resource type encapsulates a local regular file on
disk. During updates the file is uncompressed and written to the target file or partition. This
resource type is available both as source and as target. When updating no integrity or authentication
verification is done for resources of this type.</para></listitem>
<listitem><para>The <literal>partition</literal> resource type is similar to
<literal>regular-file</literal>, and encapsulates a GPT partition on disk. When updating, the partition
must exist already, and have the correct GPT partition type. A partition whose GPT partition label is
set to <literal>_empty</literal> is considered empty, and a candidate to place a newly downloaded
resource in. The GPT partition label is used to store version information, once a partition is
updated. This resource type is only available for target resources.</para></listitem>
<listitem><para>The <literal>tar</literal> resource type encapsulates local <filename>.tar</filename>
archive files. When an update takes place, the files are uncompressed and unpacked into a target
directory or btrfs subvolume. Behaviour of <literal>tar</literal> and <literal>url-tar</literal> is
generally similar, but the latter downloads from remote sources, and does integrity and authentication
checks while the former does not. The <literal>tar</literal> resource type is only available for source
resources.</para></listitem>
<listitem><para>The <literal>directory</literal> resource type encapsulates local directory trees. This
type is available both for source and target resources. If an update takes place on a source resource
of this type, a recursive copy of the directory is done.</para></listitem>
<listitem><para>The <literal>subvolume</literal> resource type is identical to
<literal>directory</literal>, except when used as the target, in which case the file tree is placed in
a btrfs subvolume instead of a plain directory, if the backing file system supports it (i.e. is
btrfs).</para></listitem>
</orderedlist>
<para>As already indicated, only a subset of source and target resource type combinations are
supported:</para>
<table>
<title>Resource Types</title>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
<colspec colname="name" />
<colspec colname="explanation" />
<thead>
<row>
<entry>Identifier</entry>
<entry>Description</entry>
<entry>Usable as Source</entry>
<entry>When Used as Source: Compatible Targets</entry>
<entry>When Used as Source: Integrity + Authentication</entry>
<entry>When Used as Source: Decompression</entry>
<entry>Usable as Target</entry>
<entry>When Used as Target: Compatible Sources</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>url-file</constant></entry>
<entry>HTTP/HTTPS files</entry>
<entry>yes</entry>
<entry><constant>regular-file</constant>, <constant>partition</constant></entry>
<entry>yes</entry>
<entry>yes</entry>
<entry>no</entry>
<entry>-</entry>
</row>
<row>
<entry><constant>url-tar</constant></entry>
<entry>HTTP/HTTPS <filename>.tar</filename> archives</entry>
<entry>yes</entry>
<entry><constant>directory</constant>, <constant>subvolume</constant></entry>
<entry>yes</entry>
<entry>yes</entry>
<entry>no</entry>
<entry>-</entry>
</row>
<row>
<entry><constant>regular-file</constant></entry>
<entry>Local files</entry>
<entry>yes</entry>
<entry><constant>regular-file</constant>, <constant>partition</constant></entry>
<entry>no</entry>
<entry>yes</entry>
<entry>yes</entry>
<entry><constant>url-file</constant>, <constant>regular-file</constant></entry>
</row>
<row>
<entry><constant>partition</constant></entry>
<entry>Local GPT partitions</entry>
<entry>no</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>yes</entry>
<entry><constant>url-file</constant>, <constant>regular-file</constant></entry>
</row>
<row>
<entry><constant>tar</constant></entry>
<entry>Local <filename>.tar</filename> archives</entry>
<entry>yes</entry>
<entry><constant>directory</constant>, <constant>subvolume</constant></entry>
<entry>no</entry>
<entry>yes</entry>
<entry>no</entry>
<entry>-</entry>
</row>
<row>
<entry><constant>directory</constant></entry>
<entry>Local directories</entry>
<entry>yes</entry>
<entry><constant>directory</constant>, <constant>subvolume</constant></entry>
<entry>no</entry>
<entry>no</entry>
<entry>yes</entry>
<entry><constant>url-tar</constant>, <constant>tar</constant>, <constant>directory</constant>, <constant>subvolume</constant></entry>
</row>
<row>
<entry><constant>subvolume</constant></entry>
<entry>Local btrfs subvolumes</entry>
<entry>yes</entry>
<entry><constant>directory</constant>, <constant>subvolume</constant></entry>
<entry>no</entry>
<entry>no</entry>
<entry>yes</entry>
<entry><constant>url-tar</constant>, <constant>tar</constant>, <constant>directory</constant>, <constant>subvolume</constant></entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
<title>Match Patterns</title>
<para>Both the source and target resources typically exist in multiple versions concurrently. An update
operation is done whenever the newest of the source versions is newer than the newest of the target
versions. To determine the newest version of the resources a directory listing, partition listing or
manifest listing is used, a subset of qualifying entries selected from that, and the version identifier
extracted from the file names or partition labels of these selected entries. Subset selection and
extraction of the version identifier (plus potentially other metadata) is done via match patterns,
configured in <varname>MatchPattern=</varname> in the [Source] and [Target] sections. These patterns are
strings that describe how files or partitions are named, with named wildcards for specific fields such as
the version identifier. The following wildcards are defined:</para>
<table>
<title>Match Pattern Wildcards</title>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
<colspec colname="name" />
<colspec colname="explanation" />
<thead>
<row>
<entry>Wildcard</entry>
<entry>Description</entry>
<entry>Format</entry>
<entry>Notes</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>@v</literal></entry>
<entry>Version identifier</entry>
<entry>Valid version string</entry>
<entry>Mandatory</entry>
</row>
<row>
<entry><literal>@u</literal></entry>
<entry>GPT partition UUID</entry>
<entry>Valid 128-Bit UUID string</entry>
<entry>Only relevant if target resource type chosen as <constant>partition</constant></entry>
</row>
<row>
<entry><literal>@f</literal></entry>
<entry>GPT partition flags</entry>
<entry>Formatted hexadecimal integer</entry>
<entry>Only relevant if target resource type chosen as <constant>partition</constant></entry>
</row>
<row>
<entry><literal>@a</literal></entry>
<entry>GPT partition flag NoAuto</entry>
<entry>Either <literal>0</literal> or <literal>1</literal></entry>
tree-wide: BLS and DPS are now on uapi-group website
2022-11-14 08:44:39 +00:00
<entry>Controls NoAuto bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</row>
<row>
<entry><literal>@g</literal></entry>
<entry>GPT partition flag GrowFileSystem</entry>
<entry>Either <literal>0</literal> or <literal>1</literal></entry>
tree-wide: BLS and DPS are now on uapi-group website
2022-11-14 08:44:39 +00:00
<entry>Controls GrowFileSystem bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</row>
<row>
<entry><literal>@r</literal></entry>
<entry>Read-only flag</entry>
<entry>Either <literal>0</literal> or <literal>1</literal></entry>
tree-wide: BLS and DPS are now on uapi-group website
2022-11-14 08:44:39 +00:00
<entry>Controls ReadOnly bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink> and other output read-only flags, see <varname>ReadOnly=</varname> below</entry>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</row>
<row>
<entry><literal>@t</literal></entry>
<entry>File modification time</entry>
tree-wide: when in doubt use greek small letter mu rather than micro symbol Doesn't really matter since the two unicode symbols are supposedly equivalent, but let's better follow the unicode recommendations to prefer greek small letter mu, as per: https://www.unicode.org/reports/tr25
2023-06-14 08:13:08 +00:00
<entry>Formatted decimal integer, μs since UNIX epoch Jan 1st 1970</entry>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
<entry>Only relevant if target resource type chosen as <constant>regular-file</constant></entry>
</row>
<row>
<entry><literal>@m</literal></entry>
<entry>File access mode</entry>
<entry>Formatted octal integer, in UNIX fashion</entry>
<entry>Only relevant if target resource type chosen as <constant>regular-file</constant></entry>
</row>
<row>
<entry><literal>@s</literal></entry>
<entry>File size after decompression</entry>
<entry>Formatted decimal integer</entry>
<entry>Useful for measuring progress and to improve partition allocation logic</entry>
</row>
<row>
<entry><literal>@d</literal></entry>
<entry>Tries done</entry>
<entry>Formatted decimal integer</entry>
<entry>Useful when operating with kernel image files, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink></entry>
</row>
<row>
<entry><literal>@l</literal></entry>
<entry>Tries left</entry>
<entry>Formatted decimal integer</entry>
man: Miscellaneous fixes Fixes: #24056
2022-07-19 08:57:33 +00:00
<entry>Useful when operating with kernel image files, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink></entry>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</row>
<row>
<entry><literal>@h</literal></entry>
<entry>SHA256 hash of compressed file</entry>
<entry>64 hexadecimal characters</entry>
man: Miscellaneous fixes Fixes: #24056
2022-07-19 08:57:33 +00:00
<entry>The SHA256 hash of the compressed file; not useful for <constant>url-file</constant> or <constant>url-tar</constant> where the SHA256 hash is already included in the manifest file anyway</entry>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</row>
</tbody>
</tgroup>
</table>
<para>Of these wildcards only <literal>@v</literal> must be present in a valid pattern, all other
wildcards are optional. Each wildcard may be used at most once in each pattern. A typical wildcard
matching a file system source image could be <literal>MatchPattern=foobar_@v.raw.xz</literal>, i.e. any file
whose name begins with <literal>foobar_</literal>, followed by a version ID and suffixed by
<literal>.raw.xz</literal>.</para>
<para>Do not confuse the <literal>@</literal> pattern matching wildcard prefix with the
<literal>%</literal> specifier expansion prefix. The former encapsulate a variable part of a match
pattern string, the latter are simple shortcuts that are expanded while the drop-in files are
parsed. For details about specifiers, see below.</para>
</refsect1>
<refsect1>
<title>[Transfer] Section Options</title>
man: fix issues reported by the manpage-l10n project Fixes #25780. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<size=> → B<cipher=>, B<hash=>, B<size=> > > "Force LUKS mode\\&. When this mode is used, the following options are " > "ignored since they are provided by the LUKS header on the device: " > "I<cipher=>, I<hash=>, I<size=>" Seems OK to me. The full stop is there and has been for at least a few years. And we use <option> for the markup, which is appropriate here. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-size=>, I<size=> → B<cipher=>, B<hash=>, B<keyfile-offset=>, B<keyfile-size=>, B<size=> > > "Use TrueCrypt encryption mode\\&. When this mode is used, the following " > "options are ignored since they are provided by the TrueCrypt header on the " > "device or do not apply: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-" > "size=>, I<size=>" Same. > Man page: journalctl.1 > Issue 1: make be → may be Fixed. > Issue 2: below\\&. → below: Fixed. > Man page: journalctl.1 > Issue: Colon at the end? > > "The following commands are understood\\&. If none is specified the default " > "is to display journal records\\&." > msgstr "" > "Die folgenden Befehle werden verstanden\\&. Falls keiner festgelegt ist, ist " > "die Anzeige von Journal-Datensätzen die Vorgabe\\&." This is a bit awkward, but I'm not sure how to fix it. > Man page: kernel-install.8 > Issue: methods a fallback → methods fallback It was correct, but I added a comma to make the sense clearer. > Man page: loader.conf.5 > Issue 1: secure boot variables → Secure Boot variables > Issue 2: one → one for (multiple times) > > "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 \\m[blue]B<UEFI specification>\\m[]\\&\\s-2\\u[2]\\d\\s+2, " > "under Secure Boot and Driver Signing\\&. Another resource that describe the " > "interplay of the different variables is the \\m[blue]B<EDK2 " > "documentation>\\m[]\\&\\s-2\\u[3]\\d\\s+2\\&." "one of" would sound strange. "One this and one that" is OK. > Man page: loader.conf.5 > Issue: systemd-boot → B<systemd-boot>(7) Fixed. > Man page: logind.conf.5 > Issue: systemd-logind → B<systemd-logind>(8) We use <filename>systemd-logind</> on subsequent references… I think that's good enough. > Man page: nss-myhostname.8 > Issue: B<getent> → B<getent>(1) Fixed. > Man page: nss-resolve.8 > Issue: B<systemd-resolved> → B<systemd-resolved>(8) The first reference does this, subsequent are shorter. > Man page: os-release.5 > Issue: Portable Services → Portable Services Documentation? Updated. > Man page: pam_systemd_home.8 > Issue: auth and account use "reason", while session and password do not? Reworded. > Man page: portablectl.1 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: repart.d.5 > Issue: The partition → the partition Fixed. > Man page: repart.d.5 > Issue: B<systemd-repart> → B<systemd-repart>(8) The first reference does this. I also change this one, because it's pretty far down in the text. > Man page: systemd.1 > Issue: kernel command line twice? > > "Takes a boolean argument\\&. If false disables importing credentials from " > "the kernel command line, qemu_fw_cfg subsystem or the kernel command line\\&." Apparently this was fixed already. > Man page: systemd-boot.7 > Issue: enrollement → enrollment Fixed. > Man page: systemd-cryptenroll.1 > Issue: multiple cases: any specified → the specified Reworded. > Man page: systemd-cryptenroll.1 > Issue: If this this → If this Fixed tree-wide. > Man page: systemd-cryptsetup-generator.8 > Issue: and the initrd → and in the initrd "Is honoured by the initrd" is OK, because we often speak about the initrd as a single unit. But in the same paragraph we also used "in the initrd", which makes the other use look sloppy. I changed it to "in the initrd" everywhere in that file. > Man page: systemd.directives.7 > Issue: Why are these two quoted (but not others)? > > "B<\\*(Aqh\\*(Aq>" > > B<\\*(Aqs\\*(Aq>" > > "B<\\*(Aqy\\*(Aq>" This is autogenerated from files… We use slightly different markup in different files, and it's just too hard to make it consistent. We gave up on this. > Man page: systemd.exec.5 > Issue 1: B<at>(1p) → B<at>(1) > Issue 2: B<crontab>(1p) → B<crontab>(1) Fixed. > Man page: systemd.exec.5 > Issue: B<select()> → B<select>(2) Fixed. > Man page: systemd.exec.5 > Issue: qemu → B<qemu>(1) The man page doesn't seem to be in any of the canonical places on the web. I added a link to online docs. > Man page: systemd.exec.5 > Issue: variable → variables Seems to be fixed already. > Man page: systemd-integritysetup-generator.8 > Issue: systemd-integritysetup-generator → B<systemd-integritysetup-generator> I changed <filename> to <command>. > Man page: systemd-integritysetup-generator.8 > Issue: superfluous comma at the end Already fixed. > Man page: systemd-measure.1 > Issue: (see B<--pcr-bank=>) below → (see B<--pcr-bank=> below) Reworded. > Man page: systemd-measure.1 > Issue: =PATH> → =>I<PATH> Fixed. > Man page: systemd-measure.1.po > Issue: B<--bank=DIGEST> → B<--bank=>I<DIGEST> Fixed. > Man page: systemd.netdev.5 > Issue: os the → on the Appears to have been fixed already. > Man page: systemd.netdev.5 > Issue: Onboard → On-board (as in previous string) Updated. > Man page: systemd.network.5 > Issue: B<systemd-networkd> -> B<systemd-networkd>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: B<netlabelctl> → B<netlabelctl>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: Missing verb (aquired? configured?) in the half sentence starting with "or by a " I dropped the comma. > Man page: systemd-nspawn.1 > Issue: All host users outside of that range → All other host users Reworded. > # FIXME no effect → no effect\\&. > #. type: Plain text > #: archlinux debian-unstable fedora-rawhide mageia-cauldron opensuse-tumbleweed > msgid "" > "Whichever ID mapping option is used, the same mapping will be used for users " > "and groups IDs\\&. If B<rootidmap> is used, the group owning the bind " > "mounted directory will have no effect" A period is added. Not sure if there's some other issue. > Man page: systemd-oomd.service.8 > Issue: B<systemd> → B<systemd>(1) Done. > Man page: systemd.path.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd-pcrphase.service.8 > Issue 1: indicate phases into TPM2 PCR 11 ?? > Issue 2: Colon at the end of the paragraph? Fixed. > Man page: systemd-pcrphase.service.8 > Issue: final boot phase → final shutdown phase? Updated. > Man page: systemd-pcrphase.service.8 > Issue: for the the → for the Fixed tree-wide. > Man page: systemd-portabled.service.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd-pstore.service.8 > Issue: Here and the following paragraphs: . → \\&. // Upstream: What does this comment mean? // You normally write \\&. for a full dot (full stop etc.); here you write only "." (i.e. a plain dot). > > "and we look up \"localhost\", nss-dns will send the following queries to " > "systemd-resolved listening on 127.0.0.53:53: first \"localhost.foobar.com\", " > "then \"localhost.barbar.com\", and finally \"localhost\". If (hopefully) the " > "first two queries fail, systemd-resolved will synthesize an answer for the " > "third query." Looks all OK to me. > Man page: systemd.resource-control.5 > Issue: Missing closing bracket after link to Control Groups version 1 Fixed. > Man page: systemd-sysext.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd.timer.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd.unit.5 > Issue: that is → that are Fixed. > Man page: systemd-veritysetup-generator.8 > Issue: systemd-veritysetup-generator → B<systemd-veritysetup-generator> > > "systemd-veritysetup-generator implements B<systemd.generator>(7)\\&." > > "systemd-veritysetup-generator understands the following kernel command line " > "parameters:" Updated. > Man page: systemd-volatile-root.service.8 > Issue: initrdyes → Initrd Fixed. > Man page: sysupdate.d.5 > Issue: : → \\&. (As above in TRANSFER) Updated. > Man page: sysupdate.d.5 > Issue: some → certain Updated. > Man page: sysupdate.d.5 > Issue 1: i\\&.e\\& → I\\&.e\\& Fixed. > Issue 2: the image → the system "image" seems correct. > Man page: tmpfiles.d.5 > Issue: systemd-tmpfiles → B<systemd-tmpfiles>(8) Updated.
2023-01-11 15:45:59 +00:00
<para>This section defines general properties of this transfer.</para>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
<variablelist>
<varlistentry>
<term><varname>MinVersion=</varname></term>
<listitem><para>Specifies the minimum version to require for this transfer to take place. If the
source or target patterns in this transfer definition match files older than this version they will
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
be considered obsolete, and never be considered for the update operation.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
<varlistentry>
<term><varname>ProtectVersion=</varname></term>
<listitem><para>Takes one or more version strings to mark as "protected". Protected versions are
never removed while making room for new, updated versions. This is useful to ensure that the
currently booted OS version (or auxiliary resources associated with it) is not replaced/overwritten
during updates, in order to avoid runtime file system corruptions.</para>
<para>Like many of the settings in these configuration files this setting supports specifier
expansion. It's particularly useful to set this setting to one of the <literal>%A</literal>,
<literal>%B</literal> or <literal>%w</literal> specifiers to automatically refer to the current OS
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
version of the running system. See below for details on supported specifiers.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
<varlistentry>
<term><varname>Verify=</varname></term>
<listitem><para>Takes a boolean, defaults to yes. Controls whether to cryptographically verify
downloaded resources (specifically: validate the GPG signatures for downloaded
<filename>SHA256SUMS</filename> manifest files, via their detached signature files
<filename>SHA256SUMS.gpg</filename> in combination with the system keyring
<filename>/usr/lib/systemd/import-pubring.gpg</filename> or
<filename>/etc/systemd/import-pubring.gpg</filename>).</para>
<para>This option is essential to provide integrity guarantees for downloaded resources and thus
should be left enabled, outside of test environments.</para>
<para>Note that the downloaded payload files are unconditionally checked against the SHA256 hashes
listed in the manifest. This option only controls whether the signatures of these manifests are
verified.</para>
<para>This option only has an effect if the source resource type is selected as
<constant>url-file</constant> or <constant>url-tar</constant>, as integrity and authentication
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
checking is only available for transfers from remote sources.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>[Source] Section Options</title>
man: fix issues reported by the manpage-l10n project Fixes #25780. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<size=> → B<cipher=>, B<hash=>, B<size=> > > "Force LUKS mode\\&. When this mode is used, the following options are " > "ignored since they are provided by the LUKS header on the device: " > "I<cipher=>, I<hash=>, I<size=>" Seems OK to me. The full stop is there and has been for at least a few years. And we use <option> for the markup, which is appropriate here. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-size=>, I<size=> → B<cipher=>, B<hash=>, B<keyfile-offset=>, B<keyfile-size=>, B<size=> > > "Use TrueCrypt encryption mode\\&. When this mode is used, the following " > "options are ignored since they are provided by the TrueCrypt header on the " > "device or do not apply: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-" > "size=>, I<size=>" Same. > Man page: journalctl.1 > Issue 1: make be → may be Fixed. > Issue 2: below\\&. → below: Fixed. > Man page: journalctl.1 > Issue: Colon at the end? > > "The following commands are understood\\&. If none is specified the default " > "is to display journal records\\&." > msgstr "" > "Die folgenden Befehle werden verstanden\\&. Falls keiner festgelegt ist, ist " > "die Anzeige von Journal-Datensätzen die Vorgabe\\&." This is a bit awkward, but I'm not sure how to fix it. > Man page: kernel-install.8 > Issue: methods a fallback → methods fallback It was correct, but I added a comma to make the sense clearer. > Man page: loader.conf.5 > Issue 1: secure boot variables → Secure Boot variables > Issue 2: one → one for (multiple times) > > "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 \\m[blue]B<UEFI specification>\\m[]\\&\\s-2\\u[2]\\d\\s+2, " > "under Secure Boot and Driver Signing\\&. Another resource that describe the " > "interplay of the different variables is the \\m[blue]B<EDK2 " > "documentation>\\m[]\\&\\s-2\\u[3]\\d\\s+2\\&." "one of" would sound strange. "One this and one that" is OK. > Man page: loader.conf.5 > Issue: systemd-boot → B<systemd-boot>(7) Fixed. > Man page: logind.conf.5 > Issue: systemd-logind → B<systemd-logind>(8) We use <filename>systemd-logind</> on subsequent references… I think that's good enough. > Man page: nss-myhostname.8 > Issue: B<getent> → B<getent>(1) Fixed. > Man page: nss-resolve.8 > Issue: B<systemd-resolved> → B<systemd-resolved>(8) The first reference does this, subsequent are shorter. > Man page: os-release.5 > Issue: Portable Services → Portable Services Documentation? Updated. > Man page: pam_systemd_home.8 > Issue: auth and account use "reason", while session and password do not? Reworded. > Man page: portablectl.1 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: repart.d.5 > Issue: The partition → the partition Fixed. > Man page: repart.d.5 > Issue: B<systemd-repart> → B<systemd-repart>(8) The first reference does this. I also change this one, because it's pretty far down in the text. > Man page: systemd.1 > Issue: kernel command line twice? > > "Takes a boolean argument\\&. If false disables importing credentials from " > "the kernel command line, qemu_fw_cfg subsystem or the kernel command line\\&." Apparently this was fixed already. > Man page: systemd-boot.7 > Issue: enrollement → enrollment Fixed. > Man page: systemd-cryptenroll.1 > Issue: multiple cases: any specified → the specified Reworded. > Man page: systemd-cryptenroll.1 > Issue: If this this → If this Fixed tree-wide. > Man page: systemd-cryptsetup-generator.8 > Issue: and the initrd → and in the initrd "Is honoured by the initrd" is OK, because we often speak about the initrd as a single unit. But in the same paragraph we also used "in the initrd", which makes the other use look sloppy. I changed it to "in the initrd" everywhere in that file. > Man page: systemd.directives.7 > Issue: Why are these two quoted (but not others)? > > "B<\\*(Aqh\\*(Aq>" > > B<\\*(Aqs\\*(Aq>" > > "B<\\*(Aqy\\*(Aq>" This is autogenerated from files… We use slightly different markup in different files, and it's just too hard to make it consistent. We gave up on this. > Man page: systemd.exec.5 > Issue 1: B<at>(1p) → B<at>(1) > Issue 2: B<crontab>(1p) → B<crontab>(1) Fixed. > Man page: systemd.exec.5 > Issue: B<select()> → B<select>(2) Fixed. > Man page: systemd.exec.5 > Issue: qemu → B<qemu>(1) The man page doesn't seem to be in any of the canonical places on the web. I added a link to online docs. > Man page: systemd.exec.5 > Issue: variable → variables Seems to be fixed already. > Man page: systemd-integritysetup-generator.8 > Issue: systemd-integritysetup-generator → B<systemd-integritysetup-generator> I changed <filename> to <command>. > Man page: systemd-integritysetup-generator.8 > Issue: superfluous comma at the end Already fixed. > Man page: systemd-measure.1 > Issue: (see B<--pcr-bank=>) below → (see B<--pcr-bank=> below) Reworded. > Man page: systemd-measure.1 > Issue: =PATH> → =>I<PATH> Fixed. > Man page: systemd-measure.1.po > Issue: B<--bank=DIGEST> → B<--bank=>I<DIGEST> Fixed. > Man page: systemd.netdev.5 > Issue: os the → on the Appears to have been fixed already. > Man page: systemd.netdev.5 > Issue: Onboard → On-board (as in previous string) Updated. > Man page: systemd.network.5 > Issue: B<systemd-networkd> -> B<systemd-networkd>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: B<netlabelctl> → B<netlabelctl>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: Missing verb (aquired? configured?) in the half sentence starting with "or by a " I dropped the comma. > Man page: systemd-nspawn.1 > Issue: All host users outside of that range → All other host users Reworded. > # FIXME no effect → no effect\\&. > #. type: Plain text > #: archlinux debian-unstable fedora-rawhide mageia-cauldron opensuse-tumbleweed > msgid "" > "Whichever ID mapping option is used, the same mapping will be used for users " > "and groups IDs\\&. If B<rootidmap> is used, the group owning the bind " > "mounted directory will have no effect" A period is added. Not sure if there's some other issue. > Man page: systemd-oomd.service.8 > Issue: B<systemd> → B<systemd>(1) Done. > Man page: systemd.path.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd-pcrphase.service.8 > Issue 1: indicate phases into TPM2 PCR 11 ?? > Issue 2: Colon at the end of the paragraph? Fixed. > Man page: systemd-pcrphase.service.8 > Issue: final boot phase → final shutdown phase? Updated. > Man page: systemd-pcrphase.service.8 > Issue: for the the → for the Fixed tree-wide. > Man page: systemd-portabled.service.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd-pstore.service.8 > Issue: Here and the following paragraphs: . → \\&. // Upstream: What does this comment mean? // You normally write \\&. for a full dot (full stop etc.); here you write only "." (i.e. a plain dot). > > "and we look up \"localhost\", nss-dns will send the following queries to " > "systemd-resolved listening on 127.0.0.53:53: first \"localhost.foobar.com\", " > "then \"localhost.barbar.com\", and finally \"localhost\". If (hopefully) the " > "first two queries fail, systemd-resolved will synthesize an answer for the " > "third query." Looks all OK to me. > Man page: systemd.resource-control.5 > Issue: Missing closing bracket after link to Control Groups version 1 Fixed. > Man page: systemd-sysext.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd.timer.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd.unit.5 > Issue: that is → that are Fixed. > Man page: systemd-veritysetup-generator.8 > Issue: systemd-veritysetup-generator → B<systemd-veritysetup-generator> > > "systemd-veritysetup-generator implements B<systemd.generator>(7)\\&." > > "systemd-veritysetup-generator understands the following kernel command line " > "parameters:" Updated. > Man page: systemd-volatile-root.service.8 > Issue: initrdyes → Initrd Fixed. > Man page: sysupdate.d.5 > Issue: : → \\&. (As above in TRANSFER) Updated. > Man page: sysupdate.d.5 > Issue: some → certain Updated. > Man page: sysupdate.d.5 > Issue 1: i\\&.e\\& → I\\&.e\\& Fixed. > Issue 2: the image → the system "image" seems correct. > Man page: tmpfiles.d.5 > Issue: systemd-tmpfiles → B<systemd-tmpfiles>(8) Updated.
2023-01-11 15:45:59 +00:00
<para>This section defines properties of the transfer source.</para>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
<variablelist>
<varlistentry>
<term><varname>Type=</varname></term>
<listitem><para>Specifies the resource type of the source for the transfer. Takes one of
<constant>url-file</constant>, <constant>url-tar</constant>, <constant>tar</constant>,
<constant>regular-file</constant>, <constant>directory</constant> or
<constant>subvolume</constant>. For details about the resource types, see above. This option is
mandatory.</para>
man: fixes for assorted issues reported by the manpage-l10n project Fixes #26761.
2023-05-17 10:24:04 +00:00
<para>Note that only certain combinations of source and target resource types are supported, see
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
above.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><varname>Path=</varname></term>
<listitem><para>Specifies where to find source versions of this resource.</para>
<para>If the source type is selected as <constant>url-file</constant> or
<constant>url-tar</constant> this must be a HTTP/HTTPS URL. The URL is suffixed with
<filename>/SHA256SUMS</filename> to acquire the manifest file, with
<filename>/SHA256SUMS.gpg</filename> to acquire the detached signature file for it, and with the file
names listed in the manifest file in case an update is executed and a resource shall be
downloaded.</para>
<para>For all other source resource types this must be a local path in the file system, referring to
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
a local directory to find the versions of this resource in.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
<varlistentry>
<term><varname>MatchPattern=</varname></term>
<listitem><para>Specifies one or more file name match patterns that select the subset of files that
are update candidates as source for this transfer. See above for details on match patterns.</para>
<para>This option is mandatory. Any pattern listed must contain at least the <literal>@v</literal>
wildcard, so that a version identifier may be extracted from the filename. All other wildcards are
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
optional.</para>
sysupdate: Add documentation for new MatchPattern behavior
2023-09-24 15:30:41 +00:00
<para>If the source type is <constant>regular-file</constant> or <constant>directory</constant>, the
pattern may contain slash characters. In this case it will match the file or directory in
corresponding subdirectory. For example <literal>MatchPattern=foo_@v/bar.efi</literal> will match
<literal>bar.efi</literal> in directory <literal>foo_1</literal>. </para>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>[Target] Section Options</title>
man: fix issues reported by the manpage-l10n project Fixes #25780. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<size=> → B<cipher=>, B<hash=>, B<size=> > > "Force LUKS mode\\&. When this mode is used, the following options are " > "ignored since they are provided by the LUKS header on the device: " > "I<cipher=>, I<hash=>, I<size=>" Seems OK to me. The full stop is there and has been for at least a few years. And we use <option> for the markup, which is appropriate here. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-size=>, I<size=> → B<cipher=>, B<hash=>, B<keyfile-offset=>, B<keyfile-size=>, B<size=> > > "Use TrueCrypt encryption mode\\&. When this mode is used, the following " > "options are ignored since they are provided by the TrueCrypt header on the " > "device or do not apply: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-" > "size=>, I<size=>" Same. > Man page: journalctl.1 > Issue 1: make be → may be Fixed. > Issue 2: below\\&. → below: Fixed. > Man page: journalctl.1 > Issue: Colon at the end? > > "The following commands are understood\\&. If none is specified the default " > "is to display journal records\\&." > msgstr "" > "Die folgenden Befehle werden verstanden\\&. Falls keiner festgelegt ist, ist " > "die Anzeige von Journal-Datensätzen die Vorgabe\\&." This is a bit awkward, but I'm not sure how to fix it. > Man page: kernel-install.8 > Issue: methods a fallback → methods fallback It was correct, but I added a comma to make the sense clearer. > Man page: loader.conf.5 > Issue 1: secure boot variables → Secure Boot variables > Issue 2: one → one for (multiple times) > > "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 \\m[blue]B<UEFI specification>\\m[]\\&\\s-2\\u[2]\\d\\s+2, " > "under Secure Boot and Driver Signing\\&. Another resource that describe the " > "interplay of the different variables is the \\m[blue]B<EDK2 " > "documentation>\\m[]\\&\\s-2\\u[3]\\d\\s+2\\&." "one of" would sound strange. "One this and one that" is OK. > Man page: loader.conf.5 > Issue: systemd-boot → B<systemd-boot>(7) Fixed. > Man page: logind.conf.5 > Issue: systemd-logind → B<systemd-logind>(8) We use <filename>systemd-logind</> on subsequent references… I think that's good enough. > Man page: nss-myhostname.8 > Issue: B<getent> → B<getent>(1) Fixed. > Man page: nss-resolve.8 > Issue: B<systemd-resolved> → B<systemd-resolved>(8) The first reference does this, subsequent are shorter. > Man page: os-release.5 > Issue: Portable Services → Portable Services Documentation? Updated. > Man page: pam_systemd_home.8 > Issue: auth and account use "reason", while session and password do not? Reworded. > Man page: portablectl.1 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: repart.d.5 > Issue: The partition → the partition Fixed. > Man page: repart.d.5 > Issue: B<systemd-repart> → B<systemd-repart>(8) The first reference does this. I also change this one, because it's pretty far down in the text. > Man page: systemd.1 > Issue: kernel command line twice? > > "Takes a boolean argument\\&. If false disables importing credentials from " > "the kernel command line, qemu_fw_cfg subsystem or the kernel command line\\&." Apparently this was fixed already. > Man page: systemd-boot.7 > Issue: enrollement → enrollment Fixed. > Man page: systemd-cryptenroll.1 > Issue: multiple cases: any specified → the specified Reworded. > Man page: systemd-cryptenroll.1 > Issue: If this this → If this Fixed tree-wide. > Man page: systemd-cryptsetup-generator.8 > Issue: and the initrd → and in the initrd "Is honoured by the initrd" is OK, because we often speak about the initrd as a single unit. But in the same paragraph we also used "in the initrd", which makes the other use look sloppy. I changed it to "in the initrd" everywhere in that file. > Man page: systemd.directives.7 > Issue: Why are these two quoted (but not others)? > > "B<\\*(Aqh\\*(Aq>" > > B<\\*(Aqs\\*(Aq>" > > "B<\\*(Aqy\\*(Aq>" This is autogenerated from files… We use slightly different markup in different files, and it's just too hard to make it consistent. We gave up on this. > Man page: systemd.exec.5 > Issue 1: B<at>(1p) → B<at>(1) > Issue 2: B<crontab>(1p) → B<crontab>(1) Fixed. > Man page: systemd.exec.5 > Issue: B<select()> → B<select>(2) Fixed. > Man page: systemd.exec.5 > Issue: qemu → B<qemu>(1) The man page doesn't seem to be in any of the canonical places on the web. I added a link to online docs. > Man page: systemd.exec.5 > Issue: variable → variables Seems to be fixed already. > Man page: systemd-integritysetup-generator.8 > Issue: systemd-integritysetup-generator → B<systemd-integritysetup-generator> I changed <filename> to <command>. > Man page: systemd-integritysetup-generator.8 > Issue: superfluous comma at the end Already fixed. > Man page: systemd-measure.1 > Issue: (see B<--pcr-bank=>) below → (see B<--pcr-bank=> below) Reworded. > Man page: systemd-measure.1 > Issue: =PATH> → =>I<PATH> Fixed. > Man page: systemd-measure.1.po > Issue: B<--bank=DIGEST> → B<--bank=>I<DIGEST> Fixed. > Man page: systemd.netdev.5 > Issue: os the → on the Appears to have been fixed already. > Man page: systemd.netdev.5 > Issue: Onboard → On-board (as in previous string) Updated. > Man page: systemd.network.5 > Issue: B<systemd-networkd> -> B<systemd-networkd>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: B<netlabelctl> → B<netlabelctl>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: Missing verb (aquired? configured?) in the half sentence starting with "or by a " I dropped the comma. > Man page: systemd-nspawn.1 > Issue: All host users outside of that range → All other host users Reworded. > # FIXME no effect → no effect\\&. > #. type: Plain text > #: archlinux debian-unstable fedora-rawhide mageia-cauldron opensuse-tumbleweed > msgid "" > "Whichever ID mapping option is used, the same mapping will be used for users " > "and groups IDs\\&. If B<rootidmap> is used, the group owning the bind " > "mounted directory will have no effect" A period is added. Not sure if there's some other issue. > Man page: systemd-oomd.service.8 > Issue: B<systemd> → B<systemd>(1) Done. > Man page: systemd.path.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd-pcrphase.service.8 > Issue 1: indicate phases into TPM2 PCR 11 ?? > Issue 2: Colon at the end of the paragraph? Fixed. > Man page: systemd-pcrphase.service.8 > Issue: final boot phase → final shutdown phase? Updated. > Man page: systemd-pcrphase.service.8 > Issue: for the the → for the Fixed tree-wide. > Man page: systemd-portabled.service.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd-pstore.service.8 > Issue: Here and the following paragraphs: . → \\&. // Upstream: What does this comment mean? // You normally write \\&. for a full dot (full stop etc.); here you write only "." (i.e. a plain dot). > > "and we look up \"localhost\", nss-dns will send the following queries to " > "systemd-resolved listening on 127.0.0.53:53: first \"localhost.foobar.com\", " > "then \"localhost.barbar.com\", and finally \"localhost\". If (hopefully) the " > "first two queries fail, systemd-resolved will synthesize an answer for the " > "third query." Looks all OK to me. > Man page: systemd.resource-control.5 > Issue: Missing closing bracket after link to Control Groups version 1 Fixed. > Man page: systemd-sysext.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd.timer.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd.unit.5 > Issue: that is → that are Fixed. > Man page: systemd-veritysetup-generator.8 > Issue: systemd-veritysetup-generator → B<systemd-veritysetup-generator> > > "systemd-veritysetup-generator implements B<systemd.generator>(7)\\&." > > "systemd-veritysetup-generator understands the following kernel command line " > "parameters:" Updated. > Man page: systemd-volatile-root.service.8 > Issue: initrdyes → Initrd Fixed. > Man page: sysupdate.d.5 > Issue: : → \\&. (As above in TRANSFER) Updated. > Man page: sysupdate.d.5 > Issue: some → certain Updated. > Man page: sysupdate.d.5 > Issue 1: i\\&.e\\& → I\\&.e\\& Fixed. > Issue 2: the image → the system "image" seems correct. > Man page: tmpfiles.d.5 > Issue: systemd-tmpfiles → B<systemd-tmpfiles>(8) Updated.
2023-01-11 15:45:59 +00:00
<para>This section defines properties of the transfer target.</para>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
<variablelist>
<varlistentry>
<term><varname>Type=</varname></term>
<listitem><para>Specifies the resource type of the target for the transfer. Takes one of
<constant>partition</constant>, <constant>regular-file</constant>, <constant>directory</constant> or
<constant>subvolume</constant>. For details about the resource types, see above. This option is
mandatory.</para>
man: fix issues reported by the manpage-l10n project Fixes #25780. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<size=> → B<cipher=>, B<hash=>, B<size=> > > "Force LUKS mode\\&. When this mode is used, the following options are " > "ignored since they are provided by the LUKS header on the device: " > "I<cipher=>, I<hash=>, I<size=>" Seems OK to me. The full stop is there and has been for at least a few years. And we use <option> for the markup, which is appropriate here. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-size=>, I<size=> → B<cipher=>, B<hash=>, B<keyfile-offset=>, B<keyfile-size=>, B<size=> > > "Use TrueCrypt encryption mode\\&. When this mode is used, the following " > "options are ignored since they are provided by the TrueCrypt header on the " > "device or do not apply: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-" > "size=>, I<size=>" Same. > Man page: journalctl.1 > Issue 1: make be → may be Fixed. > Issue 2: below\\&. → below: Fixed. > Man page: journalctl.1 > Issue: Colon at the end? > > "The following commands are understood\\&. If none is specified the default " > "is to display journal records\\&." > msgstr "" > "Die folgenden Befehle werden verstanden\\&. Falls keiner festgelegt ist, ist " > "die Anzeige von Journal-Datensätzen die Vorgabe\\&." This is a bit awkward, but I'm not sure how to fix it. > Man page: kernel-install.8 > Issue: methods a fallback → methods fallback It was correct, but I added a comma to make the sense clearer. > Man page: loader.conf.5 > Issue 1: secure boot variables → Secure Boot variables > Issue 2: one → one for (multiple times) > > "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 \\m[blue]B<UEFI specification>\\m[]\\&\\s-2\\u[2]\\d\\s+2, " > "under Secure Boot and Driver Signing\\&. Another resource that describe the " > "interplay of the different variables is the \\m[blue]B<EDK2 " > "documentation>\\m[]\\&\\s-2\\u[3]\\d\\s+2\\&." "one of" would sound strange. "One this and one that" is OK. > Man page: loader.conf.5 > Issue: systemd-boot → B<systemd-boot>(7) Fixed. > Man page: logind.conf.5 > Issue: systemd-logind → B<systemd-logind>(8) We use <filename>systemd-logind</> on subsequent references… I think that's good enough. > Man page: nss-myhostname.8 > Issue: B<getent> → B<getent>(1) Fixed. > Man page: nss-resolve.8 > Issue: B<systemd-resolved> → B<systemd-resolved>(8) The first reference does this, subsequent are shorter. > Man page: os-release.5 > Issue: Portable Services → Portable Services Documentation? Updated. > Man page: pam_systemd_home.8 > Issue: auth and account use "reason", while session and password do not? Reworded. > Man page: portablectl.1 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: repart.d.5 > Issue: The partition → the partition Fixed. > Man page: repart.d.5 > Issue: B<systemd-repart> → B<systemd-repart>(8) The first reference does this. I also change this one, because it's pretty far down in the text. > Man page: systemd.1 > Issue: kernel command line twice? > > "Takes a boolean argument\\&. If false disables importing credentials from " > "the kernel command line, qemu_fw_cfg subsystem or the kernel command line\\&." Apparently this was fixed already. > Man page: systemd-boot.7 > Issue: enrollement → enrollment Fixed. > Man page: systemd-cryptenroll.1 > Issue: multiple cases: any specified → the specified Reworded. > Man page: systemd-cryptenroll.1 > Issue: If this this → If this Fixed tree-wide. > Man page: systemd-cryptsetup-generator.8 > Issue: and the initrd → and in the initrd "Is honoured by the initrd" is OK, because we often speak about the initrd as a single unit. But in the same paragraph we also used "in the initrd", which makes the other use look sloppy. I changed it to "in the initrd" everywhere in that file. > Man page: systemd.directives.7 > Issue: Why are these two quoted (but not others)? > > "B<\\*(Aqh\\*(Aq>" > > B<\\*(Aqs\\*(Aq>" > > "B<\\*(Aqy\\*(Aq>" This is autogenerated from files… We use slightly different markup in different files, and it's just too hard to make it consistent. We gave up on this. > Man page: systemd.exec.5 > Issue 1: B<at>(1p) → B<at>(1) > Issue 2: B<crontab>(1p) → B<crontab>(1) Fixed. > Man page: systemd.exec.5 > Issue: B<select()> → B<select>(2) Fixed. > Man page: systemd.exec.5 > Issue: qemu → B<qemu>(1) The man page doesn't seem to be in any of the canonical places on the web. I added a link to online docs. > Man page: systemd.exec.5 > Issue: variable → variables Seems to be fixed already. > Man page: systemd-integritysetup-generator.8 > Issue: systemd-integritysetup-generator → B<systemd-integritysetup-generator> I changed <filename> to <command>. > Man page: systemd-integritysetup-generator.8 > Issue: superfluous comma at the end Already fixed. > Man page: systemd-measure.1 > Issue: (see B<--pcr-bank=>) below → (see B<--pcr-bank=> below) Reworded. > Man page: systemd-measure.1 > Issue: =PATH> → =>I<PATH> Fixed. > Man page: systemd-measure.1.po > Issue: B<--bank=DIGEST> → B<--bank=>I<DIGEST> Fixed. > Man page: systemd.netdev.5 > Issue: os the → on the Appears to have been fixed already. > Man page: systemd.netdev.5 > Issue: Onboard → On-board (as in previous string) Updated. > Man page: systemd.network.5 > Issue: B<systemd-networkd> -> B<systemd-networkd>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: B<netlabelctl> → B<netlabelctl>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: Missing verb (aquired? configured?) in the half sentence starting with "or by a " I dropped the comma. > Man page: systemd-nspawn.1 > Issue: All host users outside of that range → All other host users Reworded. > # FIXME no effect → no effect\\&. > #. type: Plain text > #: archlinux debian-unstable fedora-rawhide mageia-cauldron opensuse-tumbleweed > msgid "" > "Whichever ID mapping option is used, the same mapping will be used for users " > "and groups IDs\\&. If B<rootidmap> is used, the group owning the bind " > "mounted directory will have no effect" A period is added. Not sure if there's some other issue. > Man page: systemd-oomd.service.8 > Issue: B<systemd> → B<systemd>(1) Done. > Man page: systemd.path.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd-pcrphase.service.8 > Issue 1: indicate phases into TPM2 PCR 11 ?? > Issue 2: Colon at the end of the paragraph? Fixed. > Man page: systemd-pcrphase.service.8 > Issue: final boot phase → final shutdown phase? Updated. > Man page: systemd-pcrphase.service.8 > Issue: for the the → for the Fixed tree-wide. > Man page: systemd-portabled.service.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd-pstore.service.8 > Issue: Here and the following paragraphs: . → \\&. // Upstream: What does this comment mean? // You normally write \\&. for a full dot (full stop etc.); here you write only "." (i.e. a plain dot). > > "and we look up \"localhost\", nss-dns will send the following queries to " > "systemd-resolved listening on 127.0.0.53:53: first \"localhost.foobar.com\", " > "then \"localhost.barbar.com\", and finally \"localhost\". If (hopefully) the " > "first two queries fail, systemd-resolved will synthesize an answer for the " > "third query." Looks all OK to me. > Man page: systemd.resource-control.5 > Issue: Missing closing bracket after link to Control Groups version 1 Fixed. > Man page: systemd-sysext.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd.timer.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd.unit.5 > Issue: that is → that are Fixed. > Man page: systemd-veritysetup-generator.8 > Issue: systemd-veritysetup-generator → B<systemd-veritysetup-generator> > > "systemd-veritysetup-generator implements B<systemd.generator>(7)\\&." > > "systemd-veritysetup-generator understands the following kernel command line " > "parameters:" Updated. > Man page: systemd-volatile-root.service.8 > Issue: initrdyes → Initrd Fixed. > Man page: sysupdate.d.5 > Issue: : → \\&. (As above in TRANSFER) Updated. > Man page: sysupdate.d.5 > Issue: some → certain Updated. > Man page: sysupdate.d.5 > Issue 1: i\\&.e\\& → I\\&.e\\& Fixed. > Issue 2: the image → the system "image" seems correct. > Man page: tmpfiles.d.5 > Issue: systemd-tmpfiles → B<systemd-tmpfiles>(8) Updated.
2023-01-11 15:45:59 +00:00
<para>Note that only certain combinations of source and target resource types are supported, see
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
above.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
<varlistentry>
<term><varname>Path=</varname></term>
<listitem><para>Specifies a file system path where to look for already installed versions or place
newly downloaded versions of this configured resource. If <varname>Type=</varname> is set to
<constant>partition</constant>, expects a path to a (whole) block device node, or the special string
man: Miscellaneous fixes Fixes: #24056
2022-07-19 08:57:33 +00:00
<literal>auto</literal> in which case the block device which contains the root file system of the
currently booted system is automatically determined and used. If <varname>Type=</varname> is set to
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
<constant>regular-file</constant>, <constant>directory</constant> or <constant>subvolume</constant>,
must refer to a path in the local file system referencing the directory to find or place the version
files or directories under.</para>
<para>Note that this mechanism cannot be used to create or remove partitions, in case
<varname>Type=</varname> is set to <constant>partition</constant>. Partitions must exist already, and
a special partition label <literal>_empty</literal> is used to indicate empty partitions. To
automatically generate suitable partitions on first boot, use a tool such as
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
<citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
sysupdate.d: Add way to drop binaries into $BOOT As described in the BLS, we should place binaries into the XBOOTLDR directory if it is available, otherwise into the ESP. Thus, we might need to put binaries into /boot or into /efi depending on the existence of the XBOOTLDR partition. With this change, we introduce a new PathRelativeTo= config option that makes this functionality possible
2023-05-26 04:47:47 +00:00
<varlistentry>
<term><varname>PathRelativeTo=</varname></term>
<listitem><para>Specifies what partition <varname>Path=</varname> should be relative to. Takes one of
<constant>root</constant>, <constant>esp</constant>, <constant>xbootldr</constant>, or <constant>boot</constant>.
If unspecified, defaults to <constant>root</constant>.</para>
<para>If set to <constant>boot</constant>, the specified <varname>Path=</varname> will be resolved
relative to the mount point of the $BOOT partition (i.e. the ESP or XBOOTLDR), as defined by the
<ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
Specification</ulink>.</para>
<para>The values <constant>esp</constant>, <constant>xbootldr</constant>, and
<constant>boot</constant> are only supported when <varname>Type=</varname> is set to
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
<constant>regular-file</constant> or <constant>directory</constant>.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
sysupdate.d: Add way to drop binaries into $BOOT As described in the BLS, we should place binaries into the XBOOTLDR directory if it is available, otherwise into the ESP. Thus, we might need to put binaries into /boot or into /efi depending on the existence of the XBOOTLDR partition. With this change, we introduce a new PathRelativeTo= config option that makes this functionality possible
2023-05-26 04:47:47 +00:00
</varlistentry>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
<varlistentry>
<term><varname>MatchPattern=</varname></term>
<listitem><para>Specifies one or more file name or partition label match patterns that select the
subset of files or partitions that are update candidates as targets for this transfer. See above for
details on match patterns.</para>
<para>This option is mandatory. Any pattern listed must contain at least the <literal>@v</literal>
wildcard, so that a version identifier may be extracted from the filename. All other wildcards are
optional.</para>
<para>This pattern is both used for matching existing installed versions and for determining the name
of new versions to install. If multiple patterns are specified, the first specified is used for
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
naming newly installed versions.</para>
sysupdate: Add documentation for new MatchPattern behavior
2023-09-24 15:30:41 +00:00
<para>If the target type is <constant>regular-file</constant> or <constant>directory</constant>, the
pattern may contain slash characters. In this case it will match the file or directory in
corresponding subdirectory. For example <literal>MatchPattern=foo_@v/bar.efi</literal> will match
<literal>bar.efi</literal> in directory <literal>foo_1</literal>. Directories in the path will be
created when file is installed. Empty directories will be removed when file is removed.</para>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
<varlistentry>
<term><varname>MatchPartitionType=</varname></term>
<listitem><para>When the target <varname>Type=</varname> is chosen as <constant>partition</constant>,
specifies the GPT partition type to look for. Only partitions of this type are considered, all other
partitions are ignored. If not specified, the GPT partition type <constant>linux-generic</constant>
is used. Accepts either a literal type UUID or a symbolic type identifier. For a list of supported
type identifiers, see the <varname>Type=</varname> setting in
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
<citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
<varlistentry>
<term><varname>PartitionUUID=</varname></term>
<term><varname>PartitionFlags=</varname></term>
<term><varname>PartitionNoAuto=</varname></term>
<term><varname>PartitionGrowFileSystem=</varname></term>
<listitem><para>When the target <varname>Type=</varname> is picked as <constant>partition</constant>,
selects the GPT partition UUID and partition flags to use for the updated partition. Expects a valid
UUID string, a hexadecimal integer, or booleans, respectively. If not set, but the source match
pattern includes wildcards for these fields (i.e. <literal>@u</literal>, <literal>@f</literal>,
<literal>@a</literal>, or <literal>@g</literal>), the values from the patterns are used. If neither
configured with wildcards or these explicit settings, the values are left untouched. If both the
overall <varname>PartitionFlags=</varname> flags setting and the individual flag settings
<varname>PartitionNoAuto=</varname> and <varname>PartitionGrowFileSystem=</varname> are used (or the
wildcards for them), then the latter override the former, i.e. the individual flag bit overrides the
tree-wide: BLS and DPS are now on uapi-group website
2022-11-14 08:44:39 +00:00
overall flags value. See <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
Partitions Specification</ulink> for details about these flags.</para>
<para>Note that these settings are not used for matching, they only have effect on newly written
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
partitions in case a transfer takes place.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
<varlistentry>
<term><varname>ReadOnly=</varname></term>
<listitem><para>Controls whether to mark the resulting file, subvolume or partition read-only. If the
target type is <constant>partition</constant> this controls the ReadOnly partition flag, as per
tree-wide: BLS and DPS are now on uapi-group website
2022-11-14 08:44:39 +00:00
<ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
Specification</ulink>, similar to the <varname>PartitionNoAuto=</varname> and
<varname>PartitionGrowFileSystem=</varname> flags described above. If the target type is
man: fix issues reported by the manpage-l10n project Fixes #25780. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<size=> → B<cipher=>, B<hash=>, B<size=> > > "Force LUKS mode\\&. When this mode is used, the following options are " > "ignored since they are provided by the LUKS header on the device: " > "I<cipher=>, I<hash=>, I<size=>" Seems OK to me. The full stop is there and has been for at least a few years. And we use <option> for the markup, which is appropriate here. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-size=>, I<size=> → B<cipher=>, B<hash=>, B<keyfile-offset=>, B<keyfile-size=>, B<size=> > > "Use TrueCrypt encryption mode\\&. When this mode is used, the following " > "options are ignored since they are provided by the TrueCrypt header on the " > "device or do not apply: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-" > "size=>, I<size=>" Same. > Man page: journalctl.1 > Issue 1: make be → may be Fixed. > Issue 2: below\\&. → below: Fixed. > Man page: journalctl.1 > Issue: Colon at the end? > > "The following commands are understood\\&. If none is specified the default " > "is to display journal records\\&." > msgstr "" > "Die folgenden Befehle werden verstanden\\&. Falls keiner festgelegt ist, ist " > "die Anzeige von Journal-Datensätzen die Vorgabe\\&." This is a bit awkward, but I'm not sure how to fix it. > Man page: kernel-install.8 > Issue: methods a fallback → methods fallback It was correct, but I added a comma to make the sense clearer. > Man page: loader.conf.5 > Issue 1: secure boot variables → Secure Boot variables > Issue 2: one → one for (multiple times) > > "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 \\m[blue]B<UEFI specification>\\m[]\\&\\s-2\\u[2]\\d\\s+2, " > "under Secure Boot and Driver Signing\\&. Another resource that describe the " > "interplay of the different variables is the \\m[blue]B<EDK2 " > "documentation>\\m[]\\&\\s-2\\u[3]\\d\\s+2\\&." "one of" would sound strange. "One this and one that" is OK. > Man page: loader.conf.5 > Issue: systemd-boot → B<systemd-boot>(7) Fixed. > Man page: logind.conf.5 > Issue: systemd-logind → B<systemd-logind>(8) We use <filename>systemd-logind</> on subsequent references… I think that's good enough. > Man page: nss-myhostname.8 > Issue: B<getent> → B<getent>(1) Fixed. > Man page: nss-resolve.8 > Issue: B<systemd-resolved> → B<systemd-resolved>(8) The first reference does this, subsequent are shorter. > Man page: os-release.5 > Issue: Portable Services → Portable Services Documentation? Updated. > Man page: pam_systemd_home.8 > Issue: auth and account use "reason", while session and password do not? Reworded. > Man page: portablectl.1 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: repart.d.5 > Issue: The partition → the partition Fixed. > Man page: repart.d.5 > Issue: B<systemd-repart> → B<systemd-repart>(8) The first reference does this. I also change this one, because it's pretty far down in the text. > Man page: systemd.1 > Issue: kernel command line twice? > > "Takes a boolean argument\\&. If false disables importing credentials from " > "the kernel command line, qemu_fw_cfg subsystem or the kernel command line\\&." Apparently this was fixed already. > Man page: systemd-boot.7 > Issue: enrollement → enrollment Fixed. > Man page: systemd-cryptenroll.1 > Issue: multiple cases: any specified → the specified Reworded. > Man page: systemd-cryptenroll.1 > Issue: If this this → If this Fixed tree-wide. > Man page: systemd-cryptsetup-generator.8 > Issue: and the initrd → and in the initrd "Is honoured by the initrd" is OK, because we often speak about the initrd as a single unit. But in the same paragraph we also used "in the initrd", which makes the other use look sloppy. I changed it to "in the initrd" everywhere in that file. > Man page: systemd.directives.7 > Issue: Why are these two quoted (but not others)? > > "B<\\*(Aqh\\*(Aq>" > > B<\\*(Aqs\\*(Aq>" > > "B<\\*(Aqy\\*(Aq>" This is autogenerated from files… We use slightly different markup in different files, and it's just too hard to make it consistent. We gave up on this. > Man page: systemd.exec.5 > Issue 1: B<at>(1p) → B<at>(1) > Issue 2: B<crontab>(1p) → B<crontab>(1) Fixed. > Man page: systemd.exec.5 > Issue: B<select()> → B<select>(2) Fixed. > Man page: systemd.exec.5 > Issue: qemu → B<qemu>(1) The man page doesn't seem to be in any of the canonical places on the web. I added a link to online docs. > Man page: systemd.exec.5 > Issue: variable → variables Seems to be fixed already. > Man page: systemd-integritysetup-generator.8 > Issue: systemd-integritysetup-generator → B<systemd-integritysetup-generator> I changed <filename> to <command>. > Man page: systemd-integritysetup-generator.8 > Issue: superfluous comma at the end Already fixed. > Man page: systemd-measure.1 > Issue: (see B<--pcr-bank=>) below → (see B<--pcr-bank=> below) Reworded. > Man page: systemd-measure.1 > Issue: =PATH> → =>I<PATH> Fixed. > Man page: systemd-measure.1.po > Issue: B<--bank=DIGEST> → B<--bank=>I<DIGEST> Fixed. > Man page: systemd.netdev.5 > Issue: os the → on the Appears to have been fixed already. > Man page: systemd.netdev.5 > Issue: Onboard → On-board (as in previous string) Updated. > Man page: systemd.network.5 > Issue: B<systemd-networkd> -> B<systemd-networkd>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: B<netlabelctl> → B<netlabelctl>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: Missing verb (aquired? configured?) in the half sentence starting with "or by a " I dropped the comma. > Man page: systemd-nspawn.1 > Issue: All host users outside of that range → All other host users Reworded. > # FIXME no effect → no effect\\&. > #. type: Plain text > #: archlinux debian-unstable fedora-rawhide mageia-cauldron opensuse-tumbleweed > msgid "" > "Whichever ID mapping option is used, the same mapping will be used for users " > "and groups IDs\\&. If B<rootidmap> is used, the group owning the bind " > "mounted directory will have no effect" A period is added. Not sure if there's some other issue. > Man page: systemd-oomd.service.8 > Issue: B<systemd> → B<systemd>(1) Done. > Man page: systemd.path.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd-pcrphase.service.8 > Issue 1: indicate phases into TPM2 PCR 11 ?? > Issue 2: Colon at the end of the paragraph? Fixed. > Man page: systemd-pcrphase.service.8 > Issue: final boot phase → final shutdown phase? Updated. > Man page: systemd-pcrphase.service.8 > Issue: for the the → for the Fixed tree-wide. > Man page: systemd-portabled.service.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd-pstore.service.8 > Issue: Here and the following paragraphs: . → \\&. // Upstream: What does this comment mean? // You normally write \\&. for a full dot (full stop etc.); here you write only "." (i.e. a plain dot). > > "and we look up \"localhost\", nss-dns will send the following queries to " > "systemd-resolved listening on 127.0.0.53:53: first \"localhost.foobar.com\", " > "then \"localhost.barbar.com\", and finally \"localhost\". If (hopefully) the " > "first two queries fail, systemd-resolved will synthesize an answer for the " > "third query." Looks all OK to me. > Man page: systemd.resource-control.5 > Issue: Missing closing bracket after link to Control Groups version 1 Fixed. > Man page: systemd-sysext.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd.timer.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd.unit.5 > Issue: that is → that are Fixed. > Man page: systemd-veritysetup-generator.8 > Issue: systemd-veritysetup-generator → B<systemd-veritysetup-generator> > > "systemd-veritysetup-generator implements B<systemd.generator>(7)\\&." > > "systemd-veritysetup-generator understands the following kernel command line " > "parameters:" Updated. > Man page: systemd-volatile-root.service.8 > Issue: initrdyes → Initrd Fixed. > Man page: sysupdate.d.5 > Issue: : → \\&. (As above in TRANSFER) Updated. > Man page: sysupdate.d.5 > Issue: some → certain Updated. > Man page: sysupdate.d.5 > Issue 1: i\\&.e\\& → I\\&.e\\& Fixed. > Issue 2: the image → the system "image" seems correct. > Man page: tmpfiles.d.5 > Issue: systemd-tmpfiles → B<systemd-tmpfiles>(8) Updated.
2023-01-11 15:45:59 +00:00
<constant>regular-file</constant>, the writable bit is removed from the access mode. If the
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
target type is <constant>subvolume</constant>, the subvolume will be marked read-only as a
whole. Finally, if the target <varname>Type=</varname> is selected as <constant>directory</constant>,
the "immutable" file attribute is set, see <citerefentry
project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
details.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
<varlistentry>
<term><varname>Mode=</varname></term>
<listitem><para>The UNIX file access mode to use for newly created files in case the target resource
type is picked as <constant>regular-file</constant>. Expects an octal integer, in typical UNIX
fashion. If not set, but the source match pattern includes a wildcard for this field
(i.e. <literal>@t</literal>), the value from the pattern is used.</para>
<para>Note that this setting is not used for matching, it only has an effect on newly written
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
files when a transfer takes place.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
<varlistentry>
<term><varname>TriesDone=</varname></term>
<term><varname>TriesLeft=</varname></term>
<listitem><para>These options take positive, decimal integers, and control the number of attempts
done and left for this file. These settings are useful for managing kernel images, following the
scheme defined in <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot
Assessment</ulink>, and only have an effect if the target pattern includes the <literal>@d</literal>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
or <literal>@l</literal> wildcards.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
<varlistentry>
<term><varname>InstancesMax=</varname></term>
<listitem><para>Takes a decimal integer equal to or greater than 2. This configures how many concurrent
versions of the resource to keep. Whenever a new update is initiated it is made sure that no more
than the number of versions specified here minus one exist in the target. Any excess versions are
deleted (in case the target <varname>Type=</varname> of <constant>regular-file</constant>,
<constant>directory</constant>, <constant>subvolume</constant> is used) or emptied (in case the
target <varname>Type=</varname> of <constant>partition</constant> is used; emptying in this case
simply means to set the partition label to the special string <literal>_empty</literal>; note that no
partitions are actually removed). After an update is completed the number of concurrent versions of
the target resources is equal to or below the number specified here.</para>
<para>Note that this setting may be set differently for each transfer. However, it generally is
advisable to keep this setting the same for all transfers, since otherwise incomplete combinations of
files or partitions will be left installed.</para>
<para>If the target <varname>Type=</varname> is selected as <constant>partition</constant>, the number
of concurrent versions to keep is additionally restricted by the number of partition slots of the
man: fix issues reported by the manpage-l10n project Fixes #25780. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<size=> → B<cipher=>, B<hash=>, B<size=> > > "Force LUKS mode\\&. When this mode is used, the following options are " > "ignored since they are provided by the LUKS header on the device: " > "I<cipher=>, I<hash=>, I<size=>" Seems OK to me. The full stop is there and has been for at least a few years. And we use <option> for the markup, which is appropriate here. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-size=>, I<size=> → B<cipher=>, B<hash=>, B<keyfile-offset=>, B<keyfile-size=>, B<size=> > > "Use TrueCrypt encryption mode\\&. When this mode is used, the following " > "options are ignored since they are provided by the TrueCrypt header on the " > "device or do not apply: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-" > "size=>, I<size=>" Same. > Man page: journalctl.1 > Issue 1: make be → may be Fixed. > Issue 2: below\\&. → below: Fixed. > Man page: journalctl.1 > Issue: Colon at the end? > > "The following commands are understood\\&. If none is specified the default " > "is to display journal records\\&." > msgstr "" > "Die folgenden Befehle werden verstanden\\&. Falls keiner festgelegt ist, ist " > "die Anzeige von Journal-Datensätzen die Vorgabe\\&." This is a bit awkward, but I'm not sure how to fix it. > Man page: kernel-install.8 > Issue: methods a fallback → methods fallback It was correct, but I added a comma to make the sense clearer. > Man page: loader.conf.5 > Issue 1: secure boot variables → Secure Boot variables > Issue 2: one → one for (multiple times) > > "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 \\m[blue]B<UEFI specification>\\m[]\\&\\s-2\\u[2]\\d\\s+2, " > "under Secure Boot and Driver Signing\\&. Another resource that describe the " > "interplay of the different variables is the \\m[blue]B<EDK2 " > "documentation>\\m[]\\&\\s-2\\u[3]\\d\\s+2\\&." "one of" would sound strange. "One this and one that" is OK. > Man page: loader.conf.5 > Issue: systemd-boot → B<systemd-boot>(7) Fixed. > Man page: logind.conf.5 > Issue: systemd-logind → B<systemd-logind>(8) We use <filename>systemd-logind</> on subsequent references… I think that's good enough. > Man page: nss-myhostname.8 > Issue: B<getent> → B<getent>(1) Fixed. > Man page: nss-resolve.8 > Issue: B<systemd-resolved> → B<systemd-resolved>(8) The first reference does this, subsequent are shorter. > Man page: os-release.5 > Issue: Portable Services → Portable Services Documentation? Updated. > Man page: pam_systemd_home.8 > Issue: auth and account use "reason", while session and password do not? Reworded. > Man page: portablectl.1 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: repart.d.5 > Issue: The partition → the partition Fixed. > Man page: repart.d.5 > Issue: B<systemd-repart> → B<systemd-repart>(8) The first reference does this. I also change this one, because it's pretty far down in the text. > Man page: systemd.1 > Issue: kernel command line twice? > > "Takes a boolean argument\\&. If false disables importing credentials from " > "the kernel command line, qemu_fw_cfg subsystem or the kernel command line\\&." Apparently this was fixed already. > Man page: systemd-boot.7 > Issue: enrollement → enrollment Fixed. > Man page: systemd-cryptenroll.1 > Issue: multiple cases: any specified → the specified Reworded. > Man page: systemd-cryptenroll.1 > Issue: If this this → If this Fixed tree-wide. > Man page: systemd-cryptsetup-generator.8 > Issue: and the initrd → and in the initrd "Is honoured by the initrd" is OK, because we often speak about the initrd as a single unit. But in the same paragraph we also used "in the initrd", which makes the other use look sloppy. I changed it to "in the initrd" everywhere in that file. > Man page: systemd.directives.7 > Issue: Why are these two quoted (but not others)? > > "B<\\*(Aqh\\*(Aq>" > > B<\\*(Aqs\\*(Aq>" > > "B<\\*(Aqy\\*(Aq>" This is autogenerated from files… We use slightly different markup in different files, and it's just too hard to make it consistent. We gave up on this. > Man page: systemd.exec.5 > Issue 1: B<at>(1p) → B<at>(1) > Issue 2: B<crontab>(1p) → B<crontab>(1) Fixed. > Man page: systemd.exec.5 > Issue: B<select()> → B<select>(2) Fixed. > Man page: systemd.exec.5 > Issue: qemu → B<qemu>(1) The man page doesn't seem to be in any of the canonical places on the web. I added a link to online docs. > Man page: systemd.exec.5 > Issue: variable → variables Seems to be fixed already. > Man page: systemd-integritysetup-generator.8 > Issue: systemd-integritysetup-generator → B<systemd-integritysetup-generator> I changed <filename> to <command>. > Man page: systemd-integritysetup-generator.8 > Issue: superfluous comma at the end Already fixed. > Man page: systemd-measure.1 > Issue: (see B<--pcr-bank=>) below → (see B<--pcr-bank=> below) Reworded. > Man page: systemd-measure.1 > Issue: =PATH> → =>I<PATH> Fixed. > Man page: systemd-measure.1.po > Issue: B<--bank=DIGEST> → B<--bank=>I<DIGEST> Fixed. > Man page: systemd.netdev.5 > Issue: os the → on the Appears to have been fixed already. > Man page: systemd.netdev.5 > Issue: Onboard → On-board (as in previous string) Updated. > Man page: systemd.network.5 > Issue: B<systemd-networkd> -> B<systemd-networkd>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: B<netlabelctl> → B<netlabelctl>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: Missing verb (aquired? configured?) in the half sentence starting with "or by a " I dropped the comma. > Man page: systemd-nspawn.1 > Issue: All host users outside of that range → All other host users Reworded. > # FIXME no effect → no effect\\&. > #. type: Plain text > #: archlinux debian-unstable fedora-rawhide mageia-cauldron opensuse-tumbleweed > msgid "" > "Whichever ID mapping option is used, the same mapping will be used for users " > "and groups IDs\\&. If B<rootidmap> is used, the group owning the bind " > "mounted directory will have no effect" A period is added. Not sure if there's some other issue. > Man page: systemd-oomd.service.8 > Issue: B<systemd> → B<systemd>(1) Done. > Man page: systemd.path.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd-pcrphase.service.8 > Issue 1: indicate phases into TPM2 PCR 11 ?? > Issue 2: Colon at the end of the paragraph? Fixed. > Man page: systemd-pcrphase.service.8 > Issue: final boot phase → final shutdown phase? Updated. > Man page: systemd-pcrphase.service.8 > Issue: for the the → for the Fixed tree-wide. > Man page: systemd-portabled.service.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd-pstore.service.8 > Issue: Here and the following paragraphs: . → \\&. // Upstream: What does this comment mean? // You normally write \\&. for a full dot (full stop etc.); here you write only "." (i.e. a plain dot). > > "and we look up \"localhost\", nss-dns will send the following queries to " > "systemd-resolved listening on 127.0.0.53:53: first \"localhost.foobar.com\", " > "then \"localhost.barbar.com\", and finally \"localhost\". If (hopefully) the " > "first two queries fail, systemd-resolved will synthesize an answer for the " > "third query." Looks all OK to me. > Man page: systemd.resource-control.5 > Issue: Missing closing bracket after link to Control Groups version 1 Fixed. > Man page: systemd-sysext.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd.timer.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd.unit.5 > Issue: that is → that are Fixed. > Man page: systemd-veritysetup-generator.8 > Issue: systemd-veritysetup-generator → B<systemd-veritysetup-generator> > > "systemd-veritysetup-generator implements B<systemd.generator>(7)\\&." > > "systemd-veritysetup-generator understands the following kernel command line " > "parameters:" Updated. > Man page: systemd-volatile-root.service.8 > Issue: initrdyes → Initrd Fixed. > Man page: sysupdate.d.5 > Issue: : → \\&. (As above in TRANSFER) Updated. > Man page: sysupdate.d.5 > Issue: some → certain Updated. > Man page: sysupdate.d.5 > Issue 1: i\\&.e\\& → I\\&.e\\& Fixed. > Issue 2: the image → the system "image" seems correct. > Man page: tmpfiles.d.5 > Issue: systemd-tmpfiles → B<systemd-tmpfiles>(8) Updated.
2023-01-11 15:45:59 +00:00
right type in the partition table. I.e. if there are only 2 partition slots for the selected
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
partition type, setting this value larger than 2 is without effect, since no more than 2 concurrent
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
versions could be stored in the image anyway.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
<varlistentry>
<term><varname>RemoveTemporary=</varname></term>
<listitem><para>Takes a boolean argument. If this option is enabled (which is the default) before
initiating an update, all left-over, incomplete updates from a previous attempt are removed from the
target directory. This only has an effect if the target resource <varname>Type=</varname> is selected
as <constant>regular-file</constant>, <constant>directory</constant> or
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
<constant>subvolume</constant>.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
<varlistentry>
<term><varname>CurrentSymlink=</varname></term>
<listitem><para>Takes a symlink name as argument. If this option is used, as the last step of the
update a symlink under the specified name is created/updated pointing to the completed update. This
is useful in to provide a stable name always pointing to the newest version of the resource. This is
only supported if the target resource <varname>Type=</varname> is selected as
<constant>regular-file</constant>, <constant>directory</constant> or
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 16:52:36 +00:00
<constant>subvolume</constant>.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Specifiers</title>
<para>Specifiers may be used in the <varname>MinVersion=</varname>, <varname>ProtectVersion=</varname>,
<varname>Path=</varname>, <varname>MatchPattern=</varname> and <varname>CurrentSymlink=</varname>
settings. The following expansions are understood:</para>
<table class='specifiers'>
<title>Specifiers available</title>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
<colspec colname="spec" />
<colspec colname="mean" />
<colspec colname="detail" />
<thead>
<row>
<entry>Specifier</entry>
<entry>Meaning</entry>
<entry>Details</entry>
</row>
</thead>
<tbody>
<xi:include href="standard-specifiers.xml" xpointer="a"/>
<xi:include href="standard-specifiers.xml" xpointer="A"/>
<xi:include href="standard-specifiers.xml" xpointer="b"/>
<xi:include href="standard-specifiers.xml" xpointer="B"/>
<xi:include href="standard-specifiers.xml" xpointer="H"/>
<xi:include href="standard-specifiers.xml" xpointer="l"/>
<xi:include href="standard-specifiers.xml" xpointer="m"/>
<xi:include href="standard-specifiers.xml" xpointer="M"/>
<xi:include href="standard-specifiers.xml" xpointer="o"/>
<xi:include href="standard-specifiers.xml" xpointer="v"/>
<xi:include href="standard-specifiers.xml" xpointer="w"/>
<xi:include href="standard-specifiers.xml" xpointer="W"/>
<xi:include href="standard-specifiers.xml" xpointer="T"/>
<xi:include href="standard-specifiers.xml" xpointer="V"/>
<xi:include href="standard-specifiers.xml" xpointer="percent"/>
</tbody>
</tgroup>
</table>
<para>Do not confuse the <literal>%</literal> specifier expansion prefix with the <literal>@</literal>
pattern matching wildcard prefix. The former are simple shortcuts that are expanded while the drop-in
files are parsed, the latter encapsulate a variable part of a match pattern string. For details about
pattern matching wildcards, see above.</para>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Updates for a Verity Enabled Secure OS</title>
<para>With the following three files we define a root file system partition, a matching Verity
partition, and a unified kernel image to update as one. This example is an extension of the example
discussed earlier in this man page.</para>
<para><programlisting># /usr/lib/sysupdate.d/50-verity.conf
[Transfer]
ProtectVersion=%A
[Source]
Type=url-file
Path=https://download.example.com/
MatchPattern=foobarOS_@v_@u.verity.xz
[Target]
Type=partition
Path=auto
MatchPattern=foobarOS_@v_verity
MatchPartitionType=root-verity
PartitionFlags=0
Fix references to ReadOnly= PartitionReadOnly is not a valid property and ReadOnly was meant instead.
2023-11-21 17:07:25 +00:00
ReadOnly=1</programlisting></para>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
<para>The above defines the update mechanism for the Verity partition of the root file system. Verity
partition images are downloaded from
<literal>https://download.example.com/foobarOS_@v_@u.verity.xz</literal> and written to a suitable
local partition, which is marked read-only. Under the assumption this update is run from the image
itself the current image version (i.e. the <literal>%A</literal> specifier) is marked as protected, to
ensure it is not corrupted while booted. Note that the partition UUID for the target partition is
encoded in the source file name. Fixating the partition UUID can be useful to ensure that
<literal>roothash=</literal> on the kernel command line is sufficient to pinpoint both the Verity and
root file system partition, and also encode the Verity root level hash (under the assumption the UUID
in the file names match their top-level hash, the way
<citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
suggests).</para>
<para><programlisting># /usr/lib/sysupdate.d/60-root.conf
[Transfer]
ProtectVersion=%A
[Source]
Type=url-file
Path=https://download.example.com/
MatchPattern=foobarOS_@v_@u.root.xz
[Target]
Type=partition
Path=auto
MatchPattern=foobarOS_@v
MatchPartitionType=root
PartitionFlags=0
Fix references to ReadOnly= PartitionReadOnly is not a valid property and ReadOnly was meant instead.
2023-11-21 17:07:25 +00:00
ReadOnly=1</programlisting></para>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
<para>The above defines a matching transfer definition for the root file system.</para>
<para><programlisting># /usr/lib/sysupdate.d/70-kernel.conf
[Transfer]
ProtectVersion=%A
[Source]
Type=url-file
Path=https://download.example.com/
MatchPattern=foobarOS_@v.efi.xz
[Target]
man: Use correct target type for sysupdate entry While Type=file works because it seems to be the default, the line gets ignored as printed on the stderr output. Use the correct value "regular-file" for the target type.
2022-07-22 12:57:55 +00:00
Type=regular-file
sysupdate.d: Add way to drop binaries into $BOOT As described in the BLS, we should place binaries into the XBOOTLDR directory if it is available, otherwise into the ESP. Thus, we might need to put binaries into /boot or into /efi depending on the existence of the XBOOTLDR partition. With this change, we introduce a new PathRelativeTo= config option that makes this functionality possible
2023-05-26 04:47:47 +00:00
Path=/EFI/Linux
PathRelativeTo=boot
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
MatchPattern=foobarOS_@v+@l-@d.efi \
foobarOS_@v+@l.efi \
foobarOS_@v.efi
Mode=0444
TriesLeft=3
TriesDone=0
InstancesMax=2</programlisting></para>
sysupdate.d: Add way to drop binaries into $BOOT As described in the BLS, we should place binaries into the XBOOTLDR directory if it is available, otherwise into the ESP. Thus, we might need to put binaries into /boot or into /efi depending on the existence of the XBOOTLDR partition. With this change, we introduce a new PathRelativeTo= config option that makes this functionality possible
2023-05-26 04:47:47 +00:00
<para>The above installs a unified kernel image into the $BOOT partition, as per
<ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
Specification</ulink> Type #2. This defines three possible patterns for the names of the kernel
images, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink>,
and ensures when installing new kernels, they are set up with 3 tries left. No more than two parallel
kernels are kept.</para>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
<para>With this setup the web server would serve the following files, for a hypothetical version 7 of
the OS:</para>
<itemizedlist>
<listitem><para><filename>SHA256SUMS</filename> – The manifest file, containing available files and their SHA256 hashes</para></listitem>
<listitem><para><filename>SHA256SUMS.gpg</filename> – The detached cryptographic signature for the manifest file</para></listitem>
<listitem><para><filename>foobarOS_7_8b8186b1-2b4e-4eb6-ad39-8d4d18d2a8fb.verity.xz</filename> – The Verity image for version 7</para></listitem>
<listitem><para><filename>foobarOS_7_f4d1234f-3ebf-47c4-b31d-4052982f9a2f.root.xz</filename> – The root file system image for version 7</para></listitem>
<listitem><para><filename>foobarOS_7_efi.xz</filename> – The unified kernel image for version 7</para></listitem>
</itemizedlist>
<para>For each new OS release a new set of the latter three files would be added, each time with an
updated version. The <filename>SHA256SUMS</filename> manifest should then be updated accordingly,
listing all files for all versions that shall be offered for download.</para>
</example>
<example>
<title>Updates for Plain Directory Container Image</title>
<para><programlisting>
[Source]
Type=url-tar
Path=https://download.example.com/
MatchPattern=myContainer_@v.tar.gz
[Target]
Type=subvolume
Path=/var/lib/machines
MatchPattern=myContainer_@v
CurrentSymlink=myContainer</programlisting></para>
<para>On updates this downloads <literal>https://download.example.com/myContainer_@v.tar.gz</literal>
and decompresses/unpacks it to <filename>/var/lib/machines/myContainer_@v</filename>. After each update
a symlink <filename>/var/lib/machines/myContainer</filename> is created/updated always pointing to the
most recent update.</para>
</example>
</refsect1>
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-22 18:09:32 +00:00
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
man: add sysupdate documentation
2021-07-05 15:55:58 +00:00
</refsect1>
</refentry>
Reference in New Issue Copy Permalink