HALF ECHO LEARN / REFERENCE COLLECTION

v262.2

man/repart.d.xml

80,205 bytesGit mode 100644Download original fileLGPL-2.1-or-later

Git blob: 3e012f86194d93e6515d5eb7af6fccafee41df28

Lines 1001–1420 of 1,420

 
        <xi:include href="version-info.xml" xpointer="v259"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>KeyFile=</varname></term>
 
        <listitem><para>Takes a file system path. This path must be absolute, otherwise the option is ignored.
        Configures the encryption key to use when setting up LUKS2 volumes configured with the
        <varname>Encrypt=key-file</varname> setting in partition files. Please refer to the documentation of
        <varname>--key-file=</varname> for more details. This option will be overridden by the global
        <varname>--key-file=</varname> option.</para>
 
        <xi:include href="version-info.xml" xpointer="v259"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>Integrity=</varname></term>
 
        <listitem><para>Enable integrity checking for the partition. Currently, the only supported option
        is <varname>Integrity=inline</varname> which enables authenticated disk encryption for LUKS2 devices.
        The option requires <varname>Encrypt=</varname> setting and can only be used in online image build.
        Defaults to <literal>off</literal>, i.e. integrity protection is disabled.</para>
        <para>Note: authenticated disk encryption is considered EXPERIMENTAL by cryptsetup.</para>
 
        <xi:include href="version-info.xml" xpointer="v260"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>IntegrityAlgorithm=</varname></term>
        <listitem><para>Specify the integrity algorithm to be used for integrity verification. For
        <varname>Integrity=inline</varname> the supported values are: <literal>hmac-sha1</literal>,
        <literal>hmac-sha256</literal>(default), and <literal>hmac-sha512</literal>.</para>
 
        <xi:include href="version-info.xml" xpointer="v260"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>Compression=</varname></term>
 
        <listitem><para>Specifies the compression algorithm to use for the filesystem configured with
        <varname>Format=</varname>. Takes a single argument specifying the compression algorithm.</para>
 
        <para>Note that this setting is only taken into account when the filesystem configured with
        <varname>Format=</varname> supports compression (
        <citerefentry project="url"><refentrytitle url="https://btrfs.readthedocs.io/en/latest/btrfs.html">btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
        squashfs,
        <citerefentry project='man-pages'><refentrytitle>erofs</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
        Here's an incomplete list of compression algorithms supported by the filesystems
        known to <command>systemd-repart</command>:</para>
 
        <table>
          <title>File System Compression Algorithms</title>
 
          <tgroup cols='3' align='left' colsep='1' rowsep='1'>
            <colspec colname="filesystem" />
            <colspec colname="algorithms" />
            <colspec colname="manpage" />
 
            <thead>
              <row>
                <entry>File System</entry>
                <entry>Compression Algorithms</entry>
                <entry>Documentation</entry>
              </row>
            </thead>
 
            <tbody>
              <row>
                <entry><constant>squashfs</constant></entry>
                <entry>gzip, lzo, lz4, xz, zstd, lzma</entry>
                <entry><member><citerefentry project='man-pages'><refentrytitle>mksquashfs</refentrytitle><manvolnum>1</manvolnum></citerefentry></member></entry>
              </row>
 
              <row>
                <entry><constant>erofs</constant></entry>
                <entry>lz4, lz4hc, lzma, deflate, libdeflate, zstd</entry>
                <entry><member><citerefentry project='man-pages'><refentrytitle>mkfs.erofs</refentrytitle><manvolnum>1</manvolnum></citerefentry></member></entry>
              </row>
 
              <row>
                <entry><constant>btrfs</constant></entry>
                <entry>zlib, lzo, zstd</entry>
                <entry><member><citerefentry project='man-pages'><refentrytitle>mkfs.btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry></member></entry>
              </row>
            </tbody>
          </tgroup>
        </table>
 
        <xi:include href="version-info.xml" xpointer="v257"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>CompressionLevel=</varname></term>
 
        <listitem><para>Specifies the compression level to use for the filesystem configured with
        <varname>Format=</varname>. Takes a single argument specifying the compression level to use for the
        configured compression algorithm. The possible compression levels and their meaning are filesystem
        specific (refer to the filesystem's documentation for the exact meaning of a particular compression
        level).</para>
 
        <para>Note that this setting is only taken into account when the filesystem configured with
        <varname>Format=</varname> supports compression and the <varname>Compression=</varname> setting is
        configured explicitly.</para>
 
        <xi:include href="version-info.xml" xpointer="v257"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>SupplementFor=</varname></term>
 
        <listitem><para>Takes a partition definition name, such as <literal>10-esp</literal>. If specified,
        <command>systemd-repart</command> will avoid creating this partition and instead prefer to partially
        merge the two definitions. However, depending on the existing layout of partitions on disk,
        <command>systemd-repart</command> may be forced to fall back onto un-merging the definitions and
        using them as originally written, potentially creating this partition. Specifically,
        <command>systemd-repart</command> will fall back if this partition is found to already exist on disk,
        or if the target partition already exists on disk but is too small, or if it cannot allocate space
        for the merged partition for some other reason.</para>
 
        <para>The following fields are merged into the target definition in the specified ways:
        <varname>Weight=</varname> and <varname>PaddingWeight=</varname> are simply overwritten;
        <varname>SizeMinBytes=</varname> and <varname>PaddingMinBytes=</varname> use the larger of the two
        values; <varname>SizeMaxBytes=</varname> and <varname>PaddingMaxBytes=</varname> use the smaller
        value; and <varname>CopyFiles=</varname>, <varname>ExcludeFiles=</varname>,
        <varname>ExcludeFilesTarget=</varname>, <varname>MakeDirectories=</varname>, and
        <varname>Subvolumes=</varname> are concatenated.</para>
 
        <para>Usage of this option in combination with <varname>CopyBlocks=</varname>,
        <varname>Encrypt=</varname>, or <varname>Verity=</varname> is not supported. The target definition
        cannot set these settings either. A definition cannot simultaneously be a supplement and act as a
        target for some other supplement definition. A target cannot have more than one supplement partition
        associated with it.</para>
 
        <para>For example, distributions can use this to implement <varname>$BOOT</varname> as defined in the
        <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification/">UAPI.1 Boot Loader
        Specification</ulink>. Distributions may prefer to use the ESP as <varname>$BOOT</varname> whenever
        possible, but to adhere to the spec XBOOTLDR must sometimes be used instead. So, they should create
        two definitions: the first defining an ESP big enough to hold just the bootloader, and a second for
        the XBOOTLDR that's sufficiently large to hold kernels and configured as a supplement for the ESP.
        Whenever possible,
        <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>
        will try to merge the two definitions to create one large ESP, but if that's not allowable due to the
        existing conditions on disk a small ESP and a large XBOOTLDR will be created instead.</para>
 
        <para>As another example, distributions can also use this to seamlessly share a single
        <filename>/home</filename> partition in a multi-boot scenario, while preferring to keep
        <filename>/home</filename> on the root partition by default. Having a <filename>/home</filename>
        partition separated from the root partition entails some extra complexity: someone has to decide how
        to split the space between the two partitions. On the other hand, it allows a user to share their
        home area between multiple installed OSs (i.e. via
        <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>).
        Distributions should create two definitions: the first for a root partition that takes up some
        relatively small percentage of the disk, and the second as a supplement for the first to create a
        <filename>/home</filename> partition that takes up all the remaining free space. On first boot, if
        <command>systemd-repart</command> finds an existing <filename>/home</filename> partition on disk,
        it'll un-merge the definitions and create just a small root partition. Otherwise, the definitions
        will be merged and a single large root partition will be created.</para>
 
        <xi:include href="version-info.xml" xpointer="v257"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>AddValidateFS=</varname></term>
 
        <listitem><para>Takes a boolean argument. If enabled will set the
        <varname>user.validatefs.gpt_label</varname>, <varname>user.validatefs.gpt_type_uuid</varname> and
        <varname>user.validatefs.mount_point</varname> extended attributes on the root inode of the formatted
        file system to the partition labels, partition type UUIDs and the intended mount point for the file
        system. Defaults to on if <varname>Format=</varname> is used and the specified argument is neither
        <literal>swap</literal> nor <literal>vfat</literal>.</para>
 
        <para>These extended attributes are read by
        <citerefentry><refentrytitle>systemd-validatefs@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
        and may encode constraints on mounted file systems that must be fulfilled for the system to
        successfully boot. This is particular important in
        <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
        scenarios, which puts together the mount hierarchy from untrusted data from the GPT partition
        table. As these extended attributes are stored inside the file system, they are typically
        authenticated as part of the file system (assuming it is contained in protected volume; i.e. LUKS or
        dm-verity), and hence may be used to securely validate the matching partition table fields.</para>
 
        <xi:include href="version-info.xml" xpointer="v258"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>FileSystemSectorSize=</varname></term>
 
        <listitem><para>Controls the sector size for any file system, LUKS volume or Verity volume formatted
        on this partition. Expects a power of 2 as value, and must be equal or larger than 512. Typically
        it's recommended to set the file system sector size to 4096, even on 512 sector disks (and in
        particular for images that are only ever intended to be stored as file on disks), in order to
        optimize performance. However, for compatibility with foreign operating systems or firmware it might
        be advisable to use the native sector size of the backing disk.</para>
 
        <para>If unspecified and operating on a block device, defaults to the native sector size of the
        device. If unspecified and operating on a disk image file defaults to 4096.</para>
 
        <para>Regardless of what is configured here, or which default is picked, the file system sector size
        is always increased to be equal or larger than the disk sector size.</para>
 
        <xi:include href="version-info.xml" xpointer="v258"/></listitem>
      </varlistentry>
 
    </variablelist>
  </refsect1>
 
  <refsect1>
    <title>Specifiers</title>
 
    <para>Specifiers may be used in the <varname>Label=</varname>, <varname>CopyBlocks=</varname>,
    <varname>CopyFiles=</varname>, <varname>MakeDirectories=</varname>, <varname>MakeSymlinks=</varname>,
    <varname>SplitName=</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="q"/>
            <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>Additionally, for the <varname>SplitName=</varname> setting, the following specifiers are also
    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>
            <row id='T'>
              <entry><literal>%T</literal></entry>
              <entry>Partition Type UUID</entry>
              <entry>The partition type UUID, as configured with <varname>Type=</varname></entry>
            </row>
            <row id='t'>
              <entry><literal>%t</literal></entry>
              <entry>Partition Type Identifier</entry>
              <entry>The partition type identifier corresponding to the partition type UUID</entry>
            </row>
            <row id='U'>
              <entry><literal>%U</literal></entry>
              <entry>Partition UUID</entry>
              <entry>The partition UUID, as configured with <varname>UUID=</varname></entry>
            </row>
            <row id='n'>
              <entry><literal>%n</literal></entry>
              <entry>Partition Number</entry>
              <entry>The partition number assigned to the partition</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
  </refsect1>
 
  <refsect1>
    <title>Environment</title>
 
    <para>Extra filesystem formatting options can be provided using filesystem-specific environment variables:
    <varname>$SYSTEMD_REPART_MKFS_OPTIONS_BTRFS</varname>, <varname>$SYSTEMD_REPART_MKFS_OPTIONS_XFS</varname>,
    <varname>$SYSTEMD_REPART_MKFS_OPTIONS_VFAT</varname>, <varname>$SYSTEMD_REPART_MKFS_OPTIONS_EROFS</varname>,
    and <varname>$SYSTEMD_REPART_MKFS_OPTIONS_SQUASHFS</varname>. Each variable accepts valid
    <command>mkfs.<replaceable>filesystem</replaceable></command> command-line arguments.
    The content of those variables is passed as-is to the command, without any verification.
    </para>
 
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
 
    <example>
      <title>Grow the root partition to the full disk size at first boot</title>
 
      <para>With the following file the root partition is automatically grown to the full disk if possible
      during boot.</para>
 
      <para><programlisting># /usr/lib/repart.d/50-root.conf
[Partition]
Type=root
</programlisting></para>
    </example>
 
    <example>
      <title>Create a swap and home partition automatically on boot, if missing</title>
 
      <para>The home partition gets all available disk space while the swap partition gets 1G at most and 64M
      at least. We set a priority > 0 on the swap partition to ensure the swap partition is not used if not
      enough space is available. For every three bytes assigned to the home partition the swap partition gets
      assigned one.</para>
 
      <para><programlisting># /usr/lib/repart.d/60-home.conf
[Partition]
Type=home
</programlisting></para>
 
      <para><programlisting># /usr/lib/repart.d/70-swap.conf
[Partition]
Type=swap
SizeMinBytes=64M
SizeMaxBytes=1G
Priority=1
Weight=333
</programlisting></para>
    </example>
 
    <example>
      <title>Create B partitions in an A/B Verity setup, if missing</title>
 
      <para>Let's say the vendor intends to update OS images in an A/B setup, i.e. with two root partitions
      (and two matching Verity partitions) that shall be used alternatingly during upgrades. To minimize
      image sizes the original image is shipped only with one root and one Verity partition (the "A" set),
      and the second root and Verity partitions (the "B" set) shall be created on first boot on the free
      space on the medium.</para>
 
      <para><programlisting># /usr/lib/repart.d/50-root.conf
[Partition]
Type=root
SizeMinBytes=512M
SizeMaxBytes=512M
</programlisting></para>
 
      <para><programlisting># /usr/lib/repart.d/60-root-verity.conf
[Partition]
Type=root-verity
SizeMinBytes=64M
SizeMaxBytes=64M
</programlisting></para>
 
      <para>The definitions above cover the "A" set of root partition (of a fixed 512M size) and Verity
      partition for the root partition (of a fixed 64M size). Let's use symlinks to create the "B" set of
      partitions, since after all they shall have the same properties and sizes as the "A" set.</para>
 
<para><programlisting># ln -s 50-root.conf /usr/lib/repart.d/70-root-b.conf
# ln -s 60-root-verity.conf /usr/lib/repart.d/80-root-verity-b.conf
</programlisting></para>
    </example>
 
     <example>
      <title>Create a data partition and corresponding verity partitions from a OS tree</title>
 
      <para>Assuming we have an OS tree at <filename index='false'>/var/tmp/os-tree</filename> that we want
      to package in a root partition together with matching verity partitions, we can do so as follows:
      </para>
 
      <para><programlisting># 50-root.conf
[Partition]
Type=root
CopyFiles=/var/tmp/os-tree
Verity=data
VerityMatchKey=root
Minimize=guess
</programlisting></para>
 
      <para><programlisting># 60-root-verity.conf
[Partition]
Type=root-verity
Verity=hash
VerityMatchKey=root
# Explicitly set the hash and data block size to 4K
VerityDataBlockSizeBytes=4096
VerityHashBlockSizeBytes=4096
Minimize=best
</programlisting></para>
 
<para><programlisting># 70-root-verity-sig.conf
[Partition]
Type=root-verity-sig
Verity=signature
VerityMatchKey=root
</programlisting></para>
    </example>
 
  </refsect1>
 
  <refsect1>
    <title>See Also</title>
    <para><simplelist type="inline">
      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
      <member><citerefentry project='man-pages'><refentrytitle>sfdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
    </simplelist></para>
  </refsect1>
 
</refentry>