SYSTEMD-REPART(8)

📦
version 262.1 · 16 versions
, in arch rolling

💖 systemd-repart(8) 💖

okay so bestie, this is the manual page for systemd-repart and systemd-repart.service — the tool that automatically grows and adds partitions, and generates disk images (DDIs). ✨ iconic ✨

🌸 NAME 🌸

systemd-repart, systemd-repart.service — Automatically grow and add partitions, and generate disk images (DDIs)

✨ SYNOPSIS ✨

systemd-repart [OPTIONS...] [BLOCKDEVICE]

systemd-repart.service

🦋 DESCRIPTION 🦋

okay so systemd-repart creates partition tables, and adds or grows partitions, based on the configuration files described in repart.d(5). It operates on the block device or file image specified on the command line. periodt.

systemd-repart is used when building OS images, and also when deploying images to automatically adjust them, during boot, to the system they are running on. This way the image can be minimal in size and may be augmented automatically at boot, taking possession of the disk space available. the way that works is so smart fr fr.

If invoked with no arguments, systemd-repart operates on the block device backing the root file system partition of the running OS, thus adding and growing partitions of the booted OS itself. When called in the initrd, it operates on the block device backing /sysroot/ instead, i.e. on the block device the system will soon transition into. If --image= is used, it will operate on the specified device or image file. The systemd-repart.service service is generally run at boot in the initrd, in order to augment the partition table of the OS before its partitions are mounted.

If the block device is specified as - (or as an empty string), systemd-repart will not operate on any block device or image file, and instead determine and output the minimum disk/image size for the specified partition configuration, taking all configured size constraints into account. it's giving "just tell me how small I can be" energy.

systemd-repart operations are mostly incremental: it grows existing partitions or adds new ones, but 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 repart.d/*.conf configuration files, it executes no operation. no cap, it just vibes and does nothing if everything already matches.

The following use cases are among those covered:

  • The root partition may be grown to cover the whole available disk space. 💚
  • A /home/, swap, or /srv/ partition can be added. 🍑
  • 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. slay, A/B updates but make it automatic.

The algorithm executed by systemd-repart is roughly as follows:

  1. The repart.d/*.conf configuration files are loaded and parsed, and ordered by filename (without the directory prefix). For each configuration file, drop-in files are loaded from directories with same name as the configuration file with the suffix .d added.
  2. The partition table on the block device is loaded and parsed, if present.
  3. The existing partitions in the partition table are matched with the repart.d/*.conf 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 existing partitions that have no matching configuration file are considered "foreign" and left as they are. And any configuration files for which no partition was matched are treated as requests to create a partition.
  4. Partitions that shall be created are now allocated on the disk, taking the size constraints and weights declared in the configuration files into account. Free space is used within the limits set by size and padding requests. In addition, existing partitions that should be grown are grown. When possible, newly created partitions are assigned partition table slots after existing partitions of the same type, as those are matched to configuration files in partition number order and a new partition inserted before an existing one would change that matching on the next invocation. If no such slot is available, the first unused slot is used. Partitions are never reordered and thus partition numbers remain stable. When partitions are created, they are placed in the smallest area of free space that is large enough to satisfy the size and padding limits. This means that partitions might have different order on disk than in the partition table. Note that this allocation happens in memory only, the partition table on disk is not updated yet. lowkey a whole planning era, but nothing hits the disk yet.
  5. 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.
  6. 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.
  7. 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.
  8. 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 BLKDISCARD 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. this part is the actual "clean slate" moment.
  9. The new partition table is finally written to disk. The kernel is asked to reread the partition table. boom, that's the commit.

As an exception to the normal incremental operation, when called in a special "factory reset" mode, systemd-repart may be used to erase existing partitions to reset an installation back to vendor defaults. This mode of operation is used when either the --factory-reset=yes switch is passed on the tool's command line, or the systemd.factory_reset=yes option is specified on the kernel command line, or the FactoryResetRequest EFI variable (vendor UUID 8cf2644b-4b0b-428f-9387-6d876050dc67) is set to "yes". It alters the algorithm above slightly: between the 3rd and the 4th step above any partition marked explicitly via the FactoryReset= boolean is deleted, and the algorithm restarted, thus immediately re-creating these partitions anew empty.

Note that systemd-repart by default only changes partition tables, it does not create or resize any file systems within these partitions, unless the Format= configuration option is specified. Also note that there are also separate mechanisms available for this purpose, for example systemd-growfs(8) and systemd-makefs. iykyk, repart handles the table, not the filesystem contents, unless you tell it to with Format=.

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 machine-id(5) 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 --seed=random, 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 --seed= option. By hashing these UUIDs from a common seed images prepared with this tool become reproducible and the result of the algorithm above deterministic.

The positional argument should specify the block device or a regular file to operate on. If --empty=create is specified, the specified path is created as regular file, which is useful for generating disk images from scratch.

💅 OPTIONS 💅

The following options are understood:

  • -n, --dry-run= — Takes a boolean. If this switch is not specified, --dry-run=yes is the implied default. Controls whether systemd-repart executes the requested re-partition operations or whether it should only show what it would do. Unless --dry-run=no is specified systemd-repart will not actually touch the device's partition table. The short option -n is equivalent to --dry-run=yes and was added in version 262.

Added in version 245.

  • --empty= — Takes one of "refuse", "allow", "require", "force" or "create". 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 "refuse".

If "refuse" systemd-repart requires that the block device it shall operate on already carries a partition table and refuses operation if none is found. If "allow" the command will extend an existing partition table or create a new one if none exists. If "require" the command will create a new partition table if none exists so far, and refuse operation if one already exists. If "force" it will create a fresh partition table unconditionally, erasing the disk fully in effect. If "force" 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. 🚨 bestie, this is the "oops, all gone" button. If "create" a new loopback file is created under the path passed via the device node parameter, of the size indicated with --size=, see below.

Added in version 245.

  • --discard= — Takes a boolean. If this switch is not specified, --discard=yes is the implied default. Controls whether to issue the BLKDISCARD I/O control command on the space taken up by any added partitions or on the space in between them. Usually, it is 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.

Added in version 245.

  • --size= — hands the tool a size in bytes, and yes the usual K, M, G, T suffixes work, plus the special value "auto". ✨ If you use this, the device node path you gave has to point at a regular file, and that file gets grown to the size you asked for (if it's smaller) before any change is made to the partition table. Say "auto" and the minimal size for the disk image is figured out automatically — meaning the minimal sizes of all the partitions get summed up, with space for additional metadata taken into account. 🧮 This switch is not supported if the node you specified is a block device, nope. And if the file is already as big as your size or bigger? No effect, it just vibes. Your size gets implicitly rounded up to multiples of 4096. When it's used together with --empty=create, it sets the initial size of the loopback file to create. 🎀

So about --size=auto: it does take the sizes of pre-existing partitions into account. But it does not accommodate for partition tables that aren't 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 can't be fully filled by partitions to grow or create. 💀

Also note that the automatic size determination does not take files or directories specified with CopyFiles= into account: the operation might fail if the specified files or directories require more disk space than the configured per-partition minimal size limit. 😭

Added in version 246.

  • --cow=BOOL — controls copy-on-write for newly created image files on filesystems that support it. true means copy-on-write is enabled, false means it's disabled, and "auto" leaves the filesystem or parent directory default untouched. Copy-on-write lets files be reflinked into the image, which cuts down both build time and disk usage — but it may result in fragmentation for images that get frequent random writes. 🙈 Defaults to "auto".

Added in version 262.

  • --factory-reset= — takes a boolean. If you don't specify this switch at all, --factory-reset=no is the implied default. It controls whether to operate in "factory reset" mode (see above, bestie). Set it to true and all existing partitions marked with FactoryReset= set to yes get removed early while the re-partitioning algorithm is executing. ⚠️
Use with care — this is a great way to lose all your data. 🫠

Also note: partition files need to explicitly turn FactoryReset= on, since the option defaults to off. If no partitions are marked for factory reset, this switch has no effect. And fun fact, there are two other ways to request factory reset operation: via the kernel command line and via an EFI variable, see above. 👑

Added in version 245.

  • --can-factory-reset — with this switch, the disk is not re-partitioned. Instead, it's determined whether any existing partitions are marked with FactoryReset=. If there are, the tool exits with exit status zero; otherwise non-zero. This is the quick vibe-check for "does the running system support a factory reset mechanism built on systemd-repart?" 🔍

Added in version 245.

  • --root= — takes a path to a directory to use as the root file system when searching for repart.d/*.conf files, for the machine ID file to use as seed, and for the CopyFiles= and CopyBlocks= source files and directories. By default, when invoked on the regular system, this is the host's root file system, /. If invoked from the initrd it defaults to /sysroot/ instead, so the tool operates on the configuration and machine ID stored in the root file system that's later transitioned into itself. 🌱

See --copy-source= for a more restricted option that only affects CopyFiles=.

Added in version 245.

  • --image= — takes a path to a disk image file or device to mount and use in a similar fashion to --root=, see above. 🖼️

Added in version 249.

  • --image-policy=policy — takes an image policy string as argument, as per systemd.image-policy(7). The policy gets enforced when operating on the disk image specified via --image=, see above. If you don't specify it, it defaults to the "*" policy — i.e. all recognized file systems in the image are used. 🌈
  • --seed= — takes a UUID as argument, or the special value random. If you give it a UUID, the UUIDs assigned to partitions and to the partition table itself are derived via cryptographic hashing from it. 🔐 If you don't specify it, it tries to read the machine ID from the host (or more precisely, from the root directory configured via --root=) and use that as seed instead, falling back to a randomized seed otherwise. Use --seed=random to force a randomized seed. Explicitly specifying the seed may be used to generate strictly reproducible partition tables, which is lowkey iconic.

Added in version 245.

  • --pretty= — takes a boolean argument. If this switch isn't specified, it defaults to on when called from an interactive terminal and off otherwise. It controls whether to show a user friendly table and graphic illustrating the changes applied. 📊 (Yes, the pretty picture is literally part of the feature. We love that for us.)

Added in version 245.

  • --definitions= — takes a file system path. If specified, the *.conf files are read from the directory you gave instead of searching in /usr/lib/repart.d/*.conf, /etc/repart.d/*.conf, /run/repart.d/*.conf. 📁

This parameter can be specified multiple times.

Added in version 245.

  • --key-file= — takes a file system path. Configures the encryption key to use when setting up LUKS2 volumes configured with the Encrypt=key-file setting in partition files. It should refer to a regular file containing the key, or an AF_UNIX stream socket in the file system — in the socket case, a connection is made to it and the key is read from it. 🔑 If this switch isn't specified and no KeyFile= is specified in the partition file, the empty key (i.e. zero length key) is used. That behaviour is useful for setting up encrypted partitions during early first boot that receive their user-supplied password only in a later setup step. 🫶

Added in version 247.

  • --private-key= — takes a file system path or an engine or provider specific designation. Configures the signing key to use when creating verity signature partitions with the Verity=signature setting in partition files. ✍️

Added in version 252.

  • --private-key-source= — takes one of "file", "engine" or "provider". In the latter two cases it's followed by the name of a provider or engine, separated by a colon, which then gets passed to OpenSSL's "engine" or "provider" logic. Configures how to load the private key used when creating verity signature partitions with the Verity=signature setting in partition files. 🔧

Added in version 256.

  • --certificate= — takes a file system path or a provider specific designation. Configures the PEM encoded X.509 certificate to use when creating verity signature partitions with the Verity=signature setting in partition files. 📜

Added in version 252.

  • --certificate-source= — takes one of "file" or "provider". In the latter case it's followed by the name of a provider, separated by a colon, that will be passed to OpenSSL's "provider" logic. Configures how to load the X.509 certificate used when creating verity signature partitions with the Verity=signature setting in partition files. 🎀

Added in version 257.

  • --join-signature= — specifies a colon-separated tuple: the first element is a hex-encoded top-level Verity hash of a Verity=hash partition, and the second is a PKCS7 signature of the roothash, either as a path to a DER-encoded signature file or as an ASCII base64 string encoding of a DER-encoded signature prefixed by "base64:". 🧾 To be used on a pre-existing image that was created with a parameter such as --defer-partitions=root-verity-sig, in order to allow implementing offline signing of the verity signature partition.

This is an alternative to online signing using parameters such as --private-key=, for build systems where the private key for production signing isn't available in the same context where content is created. 🔥

Added in version 258.

  • --tpm2-device=, --tpm2-pcrs= — configures the TPM2 device and the list of PCRs to use for LUKS2 volumes configured with the Encrypt=tpm2 option. These options take the same parameters as the identically named options to systemd-cryptenroll(1) and have the same effect on partitions where TPM2 enrollment is requested. 🔐

Added in version 248.

  • --tpm2-device-key=PATH, --tpm2-seal-key-handle=HANDLE — configures a TPM2 SRK key to bind encryption to. See systemd-cryptenroll(1) for the deets on this option. 🔑

Added in version 255.

  • --tpm2-public-key=PATH, --tpm2-public-key-pcrs=PCR[+PCR...] — configures a TPM2 signed PCR policy to bind encryption to. See systemd-cryptenroll(1) for the deets on these two options. 🛡️

Added in version 252.

  • --tpm2-public-key-policyref=STRING — configures the policy reference to use together with the signed PCR policy configured via --tpm2-public-key=. See systemd-cryptenroll(1) for the deets on this option. 🧷

Added in version 262.

  • --tpm2-pcrlock=PATH — configures a TPM2 pcrlock policy to bind encryption to. See systemd-cryptenroll(1) for the deets on this option. 🔒

Added in version 255.

  • --split=BOOL — enables generation of split artifacts from partitions configured with SplitName=. If enabled, for each partition with SplitName= 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 SplitName=. If the loopback filename ends with ".raw", the suffix gets inserted before the ".raw" extension instead.

Note that --split is independent from --dry-run. Even if --dry-run is enabled, split artifacts will still be generated from an existing image if --split is enabled. 👀

Added in version 252.

  • --include-partitions=PARTITIONS, --exclude-partitions=PARTITIONS — these options specify which partition types systemd-repart should operate on. If --include-partitions= is used, all partitions that are not specified are excluded. If --exclude-partitions= is used, all partitions that are specified are excluded. 🎯 Both options take a comma separated list of GPT partition type UUIDs or identifiers (see Type= in repart.d(5)).
  • --defer-partitions=PARTITIONS — tells systemd-repart which partition types to defer, bestie. Here's the tea though: deferred partitions still count when it's doing the math on sizes and offsets of everything else — they just don't get written to the disk image. Net effect? If you run systemd-repart again later without this option, the missing partitions get added like they'd never been deferred the first time. ✨ added in version 253
  • --defer-partitions-empty=yes — okay so this is very similar to --defer-partitions=, but it auto-selects all the partitions for deferral that have Format=empty set and don't configure a custom label, or that set Label=_empty. You can absolutely run it together with --defer-partitions= or --defer-partitions-factory-reset=yes, and then literally every matching partition gets deferred. 🎀 added in version 259
  • --defer-partitions-factory-reset=yes — again, super close to --defer-partitions=, except this one auto-selects every partition that has FactoryReset=yes set. Same deal: stack it with --defer-partitions= or --defer-partitions-empty=yes and all the matching ones get deferred together. 💅 added in version 259
  • --sector-size=BYTES — sets the sector size of the image systemd-repart produces. It wants a value that's a power of "2" between "512" and "4096". Iconic for when you're building images for disks that use a different sector size than the disk you're actually building on. 🦋 added in version 253
  • --grain-size=BYTES — controls the partition alignment granularity used when placing partitions. Takes a power-of-2 value that's at least the sector size. Every partition start offset gets rounded up to a multiple of this value. Defaults to MAX(4096, sector_size), which matches the conventional 4 KiB alignment. Setting it to "1M" keeps proper alignment for modern storage devices even after small fixed-size partitions like a verity signature partition. 🌸 added in version 261
  • --architecture=ARCH — overrides the architecture used for architecture-specific partition types. So say you set it to "arm64" — a partition type of "root-x86-64" referenced in repart.d/ drop-ins gets dynamically patched to refer to "root-arm64" instead. Takes one of "alpha", "arc", "arm", "arm64", "ia64", "loongarch64", "mips-le", "mips64-le", "parisc", "ppc", "ppc64", "ppc64-le", "riscv32", "riscv64", "s390", "s390x", "tilegx", "x86" or "x86-64". 👑 added in version 254
  • --offline=BOOL — tells systemd-repart to build the image offline. Takes a boolean or "auto", and defaults to "auto". If enabled, the image is built without using loop devices — so useful for building images unprivileged or when loop devices just aren't there. If disabled, the image is always built using loop devices. If "auto", systemd-repart builds online when it can, and falls back to offline if loop devices aren't available or can't be accessed because of missing permissions. 😌 added in version 254
  • --copy-from=PATH — tells systemd-repart to synthesize partition definitions from the partition table in the given image or device. You can pass this option multiple times to synthesize from each of the given images or devices. The generated definitions copy the partitions into the destination partition table. Copied partitions keep the same or a slightly larger size (they may get enlarged to align to the new grain or sector size), plus the same metadata and contents — but they might land on a different partition number and at a different offset in the destination table. You can combine these definitions with ones read from regular partition definition files. The synthesized definitions take precedence over the ones from the definition files. 💖 added in version 255
  • --copy-source=PATH, -s PATH — specifies a source directory that all CopyFiles= source paths get considered relative to. It's similar to --root=, but applies exclusively to the CopyFiles= setting. If you use --root= and --copy-source= together, the former applies as usual — except for CopyFiles=, where the latter takes precedence. 🫶 added in version 255
  • --make-ddi=TYPE — takes one of "sysext", "confext" or "portable". Generates a Discoverable Disk Image (DDI) for a system extension (sysext, see systemd-sysext(8) for details), a configuration extension (confext), or Portable Services[1]. The generated image consists of a signed Verity "erofs" file system as root partition. In this mode, the partition definitions in /usr/lib/repart.d/*.conf and related directories are not read, and --definitions= is not supported, because the appropriate definitions for the selected DDI class get chosen automatically. Must be used together with --copy-source= to specify the file hierarchy to populate the DDI with. The specified directory should contain an etc/ subdirectory if "confext" is selected. If "sysext" is selected, it should contain either a usr/ or opt/ directory, or both. If "portable" is used, a full OS file hierarchy can be provided. This option implies --empty=create, --size=auto and --seed=random (the latter two can be overridden). The private key and certificate for signing the DDI must be specified via the --private-key= and --certificate= switches. 🔐 added in version 255
  • -S, -C, -P — shortcuts for --make-ddi=sysext, --make-ddi=confext, --make-ddi=portable, respectively. Periodt. 💅 added in version 255
  • --append-fstab= — takes one of "no", "auto" or "replace". Controls how the fstab(5) file generated by --generate-fstab= behaves when there's already a file sitting there. If "no", systemd-repart complains and aborts if a file exists. This is the default behaviour. If "replace", the file gets silently replaced with the freshly generated one. If "auto", systemd-repart searches the pre-existing file for the section belonging to the automatically generated content, replaces that with the newer generated content, and keeps the user-provided section if there is one. The generated section is identified by looking for the automatic content surrounded by # Start section ↓ of automatically generated fstab by systemd-repart and # End section ↑ of automatically generated fstab by systemd-repart. Anything before and after those comments counts as user-provided and gets kept in the new file. 🌈 added in version 258
  • --generate-fstab=PATH — specifies a path where fstab(5) entries get written for the mountpoints configured with MountPoint= in the root directory specified with --copy-source= or --root=, or in the host's root directory if neither is specified. Disabled by default. 🍓 added in version 256
  • --generate-crypttab=PATH — specifies a path where crypttab entries get written for the encrypted volumes configured with EncryptedVolume= in the root directory specified with --copy-source= or --root=, or in the host's root directory if neither is specified. Disabled by default. 🔐 added in version 256
  • --list-devices — shows a list of candidate block devices this command may operate on. Specifically, it enumerates the block devices currently present that support partition tables, and shows their device node paths along with any of their symlinks. 👀 added in version 257
  • --el-torito=BOOL — writes a minimal ISO9660 header with an El Torito boot catalog. That'll boot the ESP on EFI firmware. The ISO9660 filesystem it creates will be empty. The initramfs is expected to create a partitionable loop device on top of the device to change the block size and enable GPT partitions. The disk requires at least one partition with Type=esp. The first one will be the one referenced in the boot catalog. 🔥 added in version 261
  • --el-torito-system=STRING — when creating an ISO9660 header, this value is used as the system identifier. Handy for the media to be matched against the osinfo db. The value is limited to 32 characters. ⭐ added in version 261
  • --el-torito-volume=STRING — when creating an ISO9660 header, this value is used as the volume identifier. Also handy for matching the media against the osinfo db. The value is limited to 32 characters. 🌟 added in version 261
  • --el-torito-publisher=STRING — when creating an ISO9660 header, this value is used as the publisher identifier. Yep, again for matching the media against the osinfo db. The value is limited to 128 characters. ✨ added in version 261
  • -h, --help — prints a short help text and exits. 🫶
  • --version — prints a short version string and exits. 💜
  • --no-pager — doesn't pipe output into a pager. 🚫
  • --no-legend — doesn't print the legend, i.e. the column headers and the footer with hints. 🙈
  • --json=MODE — shows output formatted as JSON. Expects one of "short" (the shortest possible output, no redundant whitespace or line breaks), "pretty" (a pretty version of the same, with indentation and line breaks) or "off" (turn JSON output off — that's the default). 💻

🌱 ENVIRONMENT 🌱

  • $SOURCE_DATE_EPOCH — takes a UNIX timestamp in seconds. Clamps the access and modification times written into the image. See the reproducible builds specification[2]. added in version 262

Byte-for-byte reproducible images require --offline=yes mode, no cap. Populating a file system through the kernel writes metadata that can't be corrected from userspace afterwards. 😭

Format="vfat" images have extra noise on top of that: the directory entry of the volume label gets written with a wallclock timestamp by mkfs.fat(8) with dosfstools versions up to and including 4.2. A later release, or a backport of the upstream fix[3], sets it to $SOURCE_DATE_EPOCH.

Offline and online mode also write "vfat" short names differently, so images built both ways never match each other. 💀

🏁 EXIT STATUS 🏁

On success, 0 is returned, and a non-zero failure code otherwise. Slay. ✅

🎀 EXAMPLE 🎀

Okay bestie, here's where it gets fun. Three whole real-life scenarios, copy-paste-able, no cap. 💅

✨ Example 1. Generate a configuration extension image

This one makes a configuration extension DDI (a confext, iykyk) that updates /etc/motd. So like, your login greeting, but ✨containerised✨.

mkdir -p tree/etc/extension-release.d
echo "Hello World" >tree/etc/motd
cat >tree/etc/extension-release.d/extension-release.my-motd <<EOF
ID=fedora
VERSION_ID=38
IMAGE_ID=my-motd
IMAGE_VERSION=7
EOF
systemd-repart -C \
  --private-key=verity-private-key.pem \
  --certificate=verity-certificate.pem \
  -s tree/ \
  /var/lib/confexts/my-motd.confext.raw
systemd-confext refresh

The DDI generated that way may be applied to the system with systemd-confext(8). 🫶

💖 Example 2. Generate a system extension image and sign it via PKCS11

Now we're making a system extension DDI (sysext) that ships an update to /usr/foo, and we're signing it with a hardware token through PKCS11. Very main character of it, honestly. 🔥

mkdir -p tree/usr/lib/extension-release.d
echo "Hello World" >tree/usr/foo
cat >tree/usr/lib/extension-release.d/extension-release.my-foo <<EOF
ID=fedora
VERSION_ID=38
IMAGE_ID=my-foo
IMAGE_VERSION=7
EOF
systemd-repart --make-ddi=sysext \
  --private-key-source=engine:pkcs11 \
  --private-key="pkcs11:model=PKCS%2315%20emulated;manufacturer=piv_II;serial=0123456789abcdef;token=Some%20Cert" \
  --certificate=verity-certificate.pem \
  -s tree/ \
  /var/lib/extensions/my-foo.sysext.raw
systemd-sysext refresh

The DDI generated that way may be applied to the system with systemd-sysext(8). 💜

🌸 Example 3. Generate a dm-verity signature offline and append it to a pre-built image

This one is the boss level, ngl. It builds an image with dm-verity metadata, signs it separately to simulate an offline signing system, and then appends the signature to the image afterwards. The way that works is genuinely iconic. 😭✨

First, we set up our dirs and drop an os-release into the tree:

mkdir -p repart.d/ /tmp/tree/usr/lib/

cat >/tmp/tree/usr/lib/os-release <<EOF
ID=debian
VERSION_ID=13
EOF

Then our three partition definitions — the root, its verity hash, and its verity signature:

cat >repart.d/10-root.conf <<EOF
[Partition]
Type=root
Format=erofs
SizeMinBytes=100M
SizeMaxBytes=100M
Verity=data
VerityMatchKey=root
EOF

cat >repart.d/11-root-verity.conf <<EOF
[Partition]
Type=root-verity
Label=%o_%w_verity
Verity=hash
VerityMatchKey=root
SizeMinBytes=400M
SizeMaxBytes=400M
EOF

cat >repart.d/12-root-verity-sig.conf <<EOF
[Partition]
Type=root-verity-sig
Label=%o_%w_verity_sig
Verity=signature
VerityMatchKey=root
EOF

Then build the image — deferring the signature partition for later — and grab the roothash out of the JSON with jq:

systemd-repart --definitions repart.d \
  --defer-partitions=root-verity-sig \
  --copy-source=/tmp/tree/ \
  --empty=create --size=600M \
  --json=short \
  /tmp/img.raw | jq --raw-output0 ".[-1].roothash" > /tmp/img.roothash

Sign that roothash with openssl smime (offline signing era 💅):

openssl smime -sign -in /tmp/img.roothash \
  -inkey verity-private-key.pem \
  -signer verity-certificate.pem \
  -noattr -binary -outform der \
  -out /tmp/img.roothash.p7s

...and finally, feed the signature back in and let systemd-repart append it to the pre-built image:

systemd-repart --definitions repart.d \
  --dry-run=no --root=/tmp/tree/ \
  --join-signature="$(cat /tmp/img.roothash):/tmp/img.roothash.p7s" \
  --certificate=verity-certificate.pem \
  /tmp/img.raw

Ate. No crumbs. 🍓

🌈 SEE ALSO 🌈

⭐ NOTES ⭐

  1. Portable Services — https://systemd.io/PORTABLE_SERVICES
  2. reproducible builds specification — https://reproducible-builds.org/specs/source-date-epoch/
  3. upstream fix — https://github.com/dosfstools/dosfstools/commit/8da7bc93315c

and that's the whole page, bestie!! 💖✨ You just read the SYSTEMD-REPART(8) manual as it ships with systemd 262.1 — go forth and repartition responsibly, you absolute icon 👑💅🦋

📦 where this page comes from
  • arch rolling: systemd 262.1-1 · LGPL-2.1-or-later AND CC0-1.0 AND GPL-2.0-or-later AND MIT-0
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms