From 2cb9c68c3a898954a99a915006ea82822450e2c9 Mon Sep 17 00:00:00 2001 From: Adrian Vovk Date: Sat, 17 Aug 2024 13:30:46 -0400 Subject: repart: Add SupplementFor= logic This was designed to deal with $BOOT, as defined by the Boot Loader Specification, but it was made a generic mechanism because it is useful elsewhere too. See the updated man page for usage examples, motivation, and an explanation of how this works. --- man/repart.d.xml | 73 +++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 62 insertions(+), 11 deletions(-) (limited to 'man/repart.d.xml') diff --git a/man/repart.d.xml b/man/repart.d.xml index 3ffb6aba02..b01c0c04f0 100644 --- a/man/repart.d.xml +++ b/man/repart.d.xml @@ -76,16 +76,7 @@ Type= The GPT partition type UUID to match. This may be a GPT partition type UUID such as - 4f68bce3-e8cd-4db1-96e7-fbcaf984b709, or an identifier. - Architecture specific partition types can use one of these architecture identifiers: - alpha, arc, arm (32-bit), - arm64 (64-bit, aka aarch64), ia64, - loongarch64, mips-le, mips64-le, - parisc, ppc, ppc64, - ppc64-le, riscv32, riscv64, - s390, s390x, tilegx, - x86 (32-bit, aka i386) and x86-64 (64-bit, aka amd64). - + 4f68bce3-e8cd-4db1-96e7-fbcaf984b709, or an identifier. The supported identifiers are: @@ -237,7 +228,14 @@ - This setting defaults to linux-generic. + Architecture specific partition types can use one of these architecture identifiers: + alpha, arc, arm (32-bit), + arm64 (64-bit, aka aarch64), ia64, + loongarch64, mips-le, mips64-le, + parisc, ppc, ppc64, + ppc64-le, riscv32, riscv64, + s390, s390x, tilegx, + x86 (32-bit, aka i386) and x86-64 (64-bit, aka amd64). Most of the partition type UUIDs listed above are defined in the Discoverable Partitions @@ -897,6 +895,59 @@ + + + SupplementFor= + + Takes a partition definition name, such as 10-esp. If specified, + systemd-repart will avoid creating this partition and instead prefer to partially + merge the two definitions. However, depending on the existing layout of partitions on disk, + systemd-repart may be forced to fall back onto un-merging the definitions and + using them as originally written, potentially creating this partition. Specifically, + systemd-repart 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. + + The following fields are merged into the target definition in the specified ways: + Weight= and PaddingWeight= are simply overwritten; + SizeMinBytes= and PaddingMinBytes= use the larger of the two + values; SizeMaxBytes= and PaddingMaxBytes= use the smaller + value; and CopyFiles=, ExcludeFiles=, + ExcludeFilesTarget=, MakeDirectories=, and + Subvolumes= are concatenated. + + Usage of this option in combination with CopyBlocks=, + Encrypt=, or Verity= 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. + + For example, distributions can use this to implement $BOOT as defined in + the Boot Loader + Specification. Distributions may prefer to use the ESP as $BOOT 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, systemd-repart 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. + + As another example, distributions can also use this to seamlessly share a single + /home partition in a multi-boot scenario, while preferring to keep + /home on the root partition by default. Having a /home + 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 systemd-homed.service + 8). 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 /home partition that takes up + all the remaining free space. On first boot, if systemd-repart finds an existing + /home 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. + + + -- cgit v1.2.3