Adding upstream version 252.22.upstream/252.22upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 390 insertions, 0 deletions

diff --git a/man/systemd-repart.xml b/man/systemd-repart.xml
new file mode 100644
index 0000000..3585cbf
--- /dev/null
+++ b/man/systemd-repart.xml
@@ -0,0 +1,390 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="systemd-repart" conditional='ENABLE_REPART'
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>systemd-repart</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd-repart</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd-repart</refname>
+    <refname>systemd-repart.service</refname>
+    <refpurpose>Automatically grow and add partitions</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>systemd-repart</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="opt" rep="repeat"><replaceable><optional>BLOCKDEVICE</optional></replaceable></arg>
+    </cmdsynopsis>
+
+    <para><filename>systemd-repart.service</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><command>systemd-repart</command> grows and adds partitions to a partition table, based on the
+    configuration files described in
+    <citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    </para>
+
+    <para>If invoked with no arguments, it operates on the block device backing the root file system
+    partition of the running OS, thus growing and adding partitions of the booted OS image itself. If
+    <varname>--image=</varname> is used it will operate on the specified image file. When called in the
+    initrd it operates on the block device backing <filename>/sysroot/</filename> instead, i.e. on the block
+    device the system will soon transition into. The <filename>systemd-repart.service</filename> service is
+    generally run at boot in the initrd, in order to augment the partition table of the OS before its
+    partitions are mounted. <command>systemd-repart</command> (mostly) operates in a purely incremental mode:
+    it only grows existing and adds new partitions; it does not shrink, delete or move existing partitions.
+    The service is intended to be run on every boot, but when it detects that the partition table already
+    matches the installed <filename>repart.d/*.conf</filename> configuration files, it executes no
+    operation.</para>
+
+    <para><command>systemd-repart</command> is intended to be used when deploying OS images, to automatically
+    adjust them to the system they are running on, during first boot. This way the deployed image can be
+    minimal in size and may be augmented automatically at boot when needed, taking possession of disk space
+    available but not yet used. Specifically the following use cases are among those covered:</para>
+
+    <itemizedlist>
+      <listitem><para>The root partition may be grown to cover the whole available disk space.</para></listitem>
+      <listitem><para>A <filename>/home/</filename>, swap or <filename>/srv/</filename> partition can be
+      added.</para></listitem>
+      <listitem><para>A second (or third, …) root partition may be added, to cover A/B style setups
+      where a second version of the root file system is alternatingly used for implementing update
+      schemes. The deployed image would carry only a single partition ("A") but on first boot a second
+      partition ("B") for this purpose is automatically created.</para></listitem>
+    </itemizedlist>
+
+    <para>The algorithm executed by <command>systemd-repart</command> is roughly as follows:</para>
+
+    <orderedlist>
+      <listitem><para>The <filename>repart.d/*.conf</filename> configuration files are loaded and parsed,
+      and ordered by filename (without the directory prefix). For each configuration file,
+      drop-in files are looked for in directories with same name as the configuration file
+      with a suffix ".d" added.</para></listitem>
+
+      <listitem><para>The partition table already existing on the block device is loaded and
+      parsed.</para></listitem>
+
+      <listitem><para>The existing partitions in the partition table are matched up with the
+      <filename>repart.d/*.conf</filename> files by GPT partition type UUID. The first existing partition
+      of a specific type is assigned the first configuration file declaring the same type. The second
+      existing partition of a specific type is then assigned the second configuration file declaring the same
+      type, and so on. After this iterative assigning is complete any left-over existing partitions that have
+      no matching configuration file are considered "foreign" and left as they are. And any configuration
+      files for which no partition currently exists are understood as a request to create such a
+      partition.</para></listitem>
+
+      <listitem><para>Taking the size constraints and weights declared in the configuration files into
+      account, all partitions that shall be created are now allocated to the disk, taking up all free space,
+      always respecting the size and padding requests. Similarly, existing partitions that should be grown
+      are grown. New partitions are always appended to the end of the partition table, taking the first
+      partition table slot whose index is greater than the indexes of all existing partitions. Partition
+      table slots are never reordered and thus partition numbers are ensured to remain stable. Note that this
+      allocation happens in memory only, the partition table on disk is not updated yet.</para></listitem>
+
+      <listitem><para>All existing partitions for which configuration files exist and which currently have no
+      GPT partition label set will be assigned a label, either explicitly configured in the configuration or
+      — if that's missing — derived automatically from the partition type. The same is done for all
+      partitions that are newly created. These assignments are done in memory only, too, the disk is not
+      updated yet.</para></listitem>
+
+      <listitem><para>Similarly, all existing partitions for which configuration files exist and which
+      currently have an all-zero identifying UUID will be assigned a new UUID. This UUID is cryptographically
+      hashed from a common seed value together with the partition type UUID (and a counter in case multiple
+      partitions of the same type are defined), see below. The same is done for all partitions that are
+      created anew. These assignments are done in memory only, too, the disk is not updated yet.
+      </para></listitem>
+
+      <listitem><para>Similarly, if the disk's volume UUID is all zeroes it is also initialized, also
+      cryptographically hashed from the same common seed value. This is done in memory only too.
+      </para></listitem>
+
+      <listitem><para>The disk space assigned to new partitions (i.e. what was previously free space) is now
+      erased. Specifically, all file system signatures are removed, and if the device supports it, the
+      <constant>BLKDISCARD</constant> I/O control command is issued to inform the hardware that the space is
+      now empty. In addition any "padding" between partitions and at the end of the device is similarly
+      erased.</para></listitem>
+
+      <listitem><para>The new partition table is finally written to disk. The kernel is asked to reread the
+      partition table.</para></listitem>
+    </orderedlist>
+
+    <para>As exception to the normally strictly incremental operation, when called in a special "factory
+    reset" mode, <command>systemd-repart</command> may also be used to erase existing partitions to
+    reset an installation back to vendor defaults. This mode of operation is used when either the
+    <option>--factory-reset=yes</option> switch is passed on the tool's command line, or the
+    <option>systemd.factory_reset=yes</option> option specified on the kernel command line, or the
+    <varname>FactoryReset</varname> EFI variable (vendor UUID
+    <constant>8cf2644b-4b0b-428f-9387-6d876050dc67</constant>) is set to "yes". It alters the algorithm above
+    slightly: between the 3rd and the 4th step above any partition marked explicitly via the
+    <varname>FactoryReset=</varname> boolean is deleted, and the algorithm restarted, thus immediately
+    re-creating these partitions anew empty.</para>
+
+    <para>Note that <command>systemd-repart</command> only changes partition tables, it does not create or
+    resize any file systems within these partitions. A separate mechanism should be used for that, for
+    example
+    <citerefentry><refentrytitle>systemd-growfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> and
+    <command>systemd-makefs</command>.</para>
+
+    <para>The UUIDs identifying the new partitions created (or assigned to existing partitions that have no
+    UUID yet), as well as the disk as a whole are hashed cryptographically from a common seed value. This
+    seed value is usually the
+    <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> of the
+    system, so that the machine ID reproducibly determines the UUIDs assigned to all partitions. If the
+    machine ID cannot be read (or the user passes <option>--seed=random</option>, see below) the seed is
+    generated randomly instead, so that the partition UUIDs are also effectively random. The seed value may
+    also be set explicitly, formatted as UUID via the <option>--seed=</option> option. By hashing these UUIDs
+    from a common seed images prepared with this tool become reproducible and the result of the algorithm
+    above deterministic.</para>
+
+    <para>The positional argument should specify the block device to operate on. Instead of a block device
+    node path a regular file may be specified too, in which case the command operates on it like it would if
+    a loopback block device node was specified with the file attached. If <option>--empty=create</option> is
+    specified the specified path is created as regular file, which is useful for generating disk images from
+    scratch.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+
+    <para>The following options are understood:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><option>--dry-run=</option></term>
+        <listitem><para>Takes a boolean. If this switch is not specified <option>--dry-run=yes</option> is
+        the implied default. Controls whether <filename>systemd-repart</filename> executes the requested
+        re-partition operations or whether it should only show what it would do. Unless
+        <option>--dry-run=no</option> is specified <filename>systemd-repart</filename> will not actually
+        touch the device's partition table.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--empty=</option></term>
+        <listitem><para>Takes one of <literal>refuse</literal>, <literal>allow</literal>,
+        <literal>require</literal>, <literal>force</literal> or <literal>create</literal>. Controls how to
+        operate on block devices that are entirely empty, i.e. carry no partition table/disk label yet. If
+        this switch is not specified the implied default is <literal>refuse</literal>.</para>
+
+        <para>If <literal>refuse</literal> <command>systemd-repart</command> requires that the block device
+        it shall operate on already carries a partition table and refuses operation if none is found. If
+        <literal>allow</literal> the command will extend an existing partition table or create a new one if
+        none exists. If <literal>require</literal> the command will create a new partition table if none
+        exists so far, and refuse operation if one already exists. If <literal>force</literal> it will create
+        a fresh partition table unconditionally, erasing the disk fully in effect. If
+        <literal>force</literal> no existing partitions will be taken into account or survive the
+        operation. Hence: use with care, this is a great way to lose all your data. If
+        <literal>create</literal> a new loopback file is create under the path passed via the device node
+        parameter, of the size indicated with <option>--size=</option>, see below.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--discard=</option></term>
+
+        <listitem><para>Takes a boolean. If this switch is not specified <option>--discard=yes</option> is
+        the implied default. Controls whether to issue the <constant>BLKDISCARD</constant> I/O control
+        command on the space taken up by any added partitions or on the space in between them. Usually, it's
+        a good idea to issue this request since it tells the underlying hardware that the covered blocks
+        shall be considered empty, improving performance. If operating on a regular file instead of a block
+        device node, a sparse file is generated.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--size=</option></term>
+
+        <listitem><para>Takes a size in bytes, using the usual K, M, G, T suffixes, or the special value
+        <literal>auto</literal>. If used the specified device node path must refer to a regular file, which
+        is then grown to the specified size if smaller, before any change is made to the partition table. If
+        specified as <literal>auto</literal> the minimal size for the disk image is automatically determined
+        (i.e. the minimal sizes of all partitions are summed up, taking space for additional metadata into
+        account). This switch is not supported if the specified node is a block device. This switch has no
+        effect if the file is already as large as the specified size or larger. The specified size is
+        implicitly rounded up to multiples of 4096. When used with <option>--empty=create</option> this
+        specifies the initial size of the loopback file to create.</para>
+
+        <para>The <option>--size=auto</option> option takes the sizes of pre-existing partitions into
+        account. However, it does not accommodate for partition tables that are not tightly packed: the
+        configured partitions might still not fit into the backing device if empty space exists between
+        pre-existing partitions (or before the first partition) that cannot be fully filled by partitions to
+        grow or create.</para>
+
+        <para>Also note that the automatic size determination does not take files or directories specified
+        with <option>CopyFiles=</option> into account: operation might fail if the specified files or
+        directories require more disk space then the configured per-partition minimal size
+        limit.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--factory-reset=</option></term>
+
+        <listitem><para>Takes boolean. If this switch is not specified <option>--factory=reset=no</option> is
+        the implied default. Controls whether to operate in "factory reset" mode, see above. If set to true
+        this will remove all existing partitions marked with <varname>FactoryReset=</varname> set to yes
+        early while executing the re-partitioning algorithm. Use with care, this is a great way to lose all
+        your data. Note that partition files need to explicitly turn <varname>FactoryReset=</varname> on, as
+        the option defaults to off. If no partitions are marked for factory reset this switch has no
+        effect. Note that there are two other methods to request factory reset operation: via the kernel
+        command line and via an EFI variable, see above.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--can-factory-reset</option></term>
+
+        <listitem><para>If this switch is specified the disk is not re-partitioned. Instead it is determined
+        if any existing partitions are marked with <varname>FactoryReset=</varname>. If there are the tool
+        will exit with exit status zero, otherwise non-zero. This switch may be used to quickly determine
+        whether the running system supports a factory reset mechanism built on
+        <command>systemd-repart</command>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--root=</option></term>
+
+        <listitem><para>Takes a path to a directory to use as root file system when searching for
+        <filename>repart.d/*.conf</filename> files, for the machine ID file to use as seed and for the
+        <varname>CopyFiles=</varname> and <varname>CopyBlocks=</varname> source files and directories. By
+        default when invoked on the regular system this defaults to the host's root file system
+        <filename>/</filename>. If invoked from the initrd this defaults to <filename>/sysroot/</filename>,
+        so that the tool operates on the configuration and machine ID stored in the root file system later
+        transitioned into itself.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--image=</option></term>
+
+        <listitem><para>Takes a path to a disk image file or device to mount and use in a similar fashion to
+        <option>--root=</option>, see above.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--seed=</option></term>
+
+        <listitem><para>Takes a UUID as argument or the special value <constant>random</constant>. If a UUID
+        is specified the UUIDs to assign to partitions and the partition table itself are derived via
+        cryptographic hashing from it. If not specified it is attempted to read the machine ID from the host
+        (or more precisely, the root directory configured via <option>--root=</option>) and use it as seed
+        instead, falling back to a randomized seed otherwise. Use <option>--seed=random</option> to force a
+        randomized seed. Explicitly specifying the seed may be used to generated strictly reproducible
+        partition tables.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--pretty=</option></term>
+
+        <listitem><para>Takes a boolean argument. If this switch is not specified, it defaults to on when
+        called from an interactive terminal and off otherwise. Controls whether to show a user friendly table
+        and graphic illustrating the changes applied.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--definitions=</option></term>
+
+        <listitem><para>Takes a file system path. If specified the <filename>*.conf</filename> files are read
+        from the specified directory instead of searching in <filename>/usr/lib/repart.d/*.conf</filename>,
+        <filename>/etc/repart.d/*.conf</filename>,
+        <filename>/run/repart.d/*.conf</filename>.</para>
+
+        <para>This parameter can be specified multiple times.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--key-file=</option></term>
+
+        <listitem><para>Takes a file system path. Configures the encryption key to use when setting up LUKS2
+        volumes configured with the <varname>Encrypt=key-file</varname> setting in partition files. Should
+        refer to a regular file containing the key, or an <constant>AF_UNIX</constant> stream socket in the
+        file system. In the latter case a connection is made to it and the key read from it. If this switch
+        is not specified the empty key (i.e. zero length key) is used. This behaviour is useful for setting
+        up encrypted partitions during early first boot that receive their user-supplied password only in a
+        later setup step.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--private-key=</option></term>
+
+        <listitem><para>Takes a file system path. Configures the signing key to use when creating verity
+        signature partitions with the <varname>Verity=signature</varname> setting in partition files.
+        </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--certificate=</option></term>
+
+        <listitem><para>Takes a file system path. Configures the PEM encoded X.509 certificate to use when
+        creating verity signature partitions with the <varname>Verity=signature</varname> setting in
+        partition files.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--tpm2-device=</option></term>
+        <term><option>--tpm2-pcrs=</option></term>
+
+        <listitem><para>Configures the TPM2 device and list of PCRs to use for LUKS2 volumes configured with
+        the <varname>Encrypt=tpm2</varname> option. These options take the same parameters as the identically
+        named options to
+        <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        and have the same effect on partitions where TPM2 enrollment is requested.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--tpm2-public-key=</option><arg>PATH</arg></term>
+        <term><option>--tpm2-public-key-pcrs=</option><arg rep="repeat">PCR</arg></term>
+
+        <listitem><para>Configures a TPM2 signed PCR policy to bind encryption to. See
+        <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        for details on these two options.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--split=</option><arg>BOOL</arg></term>
+
+        <listitem><para>Enables generation of split artifacts from partitions configured with
+        <varname>SplitName=</varname>. If enabled, for each partition with <varname>SplitName=</varname> set,
+        a separate output file containing just the contents of that partition is generated. The output
+        filename consists of the loopback filename suffixed with the name configured with
+        <varname>SplitName=</varname>. If the loopback filename ends with <literal>.raw</literal>, the suffix
+        is inserted before the <literal>.raw</literal> extension instead.</para>
+
+        <para>Note that <option>--split</option> is independent from <option>--dry-run</option>. Even if
+        <option>--dry-run</option> is enabled, split artifacts will still be generated from an existing image
+        if <option>--split</option> is enabled.</para></listitem>
+      </varlistentry>
+
+      <xi:include href="standard-options.xml" xpointer="help" />
+      <xi:include href="standard-options.xml" xpointer="version" />
+      <xi:include href="standard-options.xml" xpointer="no-pager" />
+      <xi:include href="standard-options.xml" xpointer="no-legend" />
+      <xi:include href="standard-options.xml" xpointer="json" />
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Exit status</title>
+
+    <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>