HALF ECHO LEARN / REFERENCE COLLECTION
v262.2man/repart.d.xml
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>