SYSTEMD.IMAGE-POLICY(7)

💖 SYSTEMD.IMAGE-POLICY(7) 💖

okay bestie, pull up a chair, we're talking about systemd.image-policy — the Disk Image Dissection Policy — from section 7 of the manuals. yes it's a mouthful. no you don't have to be scared. let's go 🫶

---

✨ DESCRIPTION ✨

so in systemd, whenever a disk image (aka a DDI) that implements the UAPI.2 Discoverable Partitions Specification[1] gets activated, you can hand it a policy. that policy is the vibe check for your image: which partitions get mounted, what kind of cryptographic protection is required, and which filesystem types are even allowed to show up. 👑

the policy itself is just a string. it's made of per-partition-type rules, and those rules are separated by colons (":"). each individual rule is: a partition identifier, then an equal sign ("="), then one or more flags that you're setting for that partition. if you want multiple flags on one partition, you separate them with a plus sign ("+"). simple. slay.

the partition identifiers that are currently defined are:

• root
• usr
• home
• srv
• esp
• xbootldr
• swap
• root-verity
• root-verity-sig
• usr-verity
• usr-verity-sig
• tmp
• var

these identifiers line up with the relevant partition types in the Discoverable Partitions Specification, but here's the tea: they're agnostic to CPU architectures. 💅

and if you leave the partition identifier empty? that's you setting the default policy for all the partitions defined in the Discoverable Partitions Specification that don't have policy flags explicitly listed in the policy string. it's giving "catch-all". ✨

---

🔐 partition policy flags (existence / use / protection level)

these are the flags that dictate whether a partition exists, whether it's used, and how protected it is:

• unprotected — for partitions that shall exist and be used, but come with no cryptographic protection: no Verity authentication, no LUKS encryption.
• verity — for partitions that shall exist and be used, with Verity authentication.

ngl this next bit matters: if a DDI image carries a data partition, along with a Verity partition and a signature partition for it, and only the verity flag is set (and signed is not), then the image will be set up with Verity, but the signature data will not be used. or, to put it another way: any DDI with a set of partitions that qualify for signature also implicitly qualifies for verity — and in fact also unprotected.

• signed — for partitions that shall exist and be used, with Verity authentication, and which are also accompanied by a PKCS#7 signature of the Verity root hash.
• encrypted — for partitions which shall exist and be used and are encrypted with LUKS.
• unused — for partitions that shall exist but shall not be used.
• absent — for partitions that shall not exist on the image.

---

🗂️ filesystem policy flags

these ones dictate which filesystem types are allowed for which partition. the filesystem flags supported by the policy are:

• "btrfs"
• "erofs"
• "ext4"
• "f2fs"
• "squashfs"
• "vfat"
• "xfs"

(that's Table 1: Filesystems types supported by the policy, bestie 🎀)

---

🧚 combinations & shortcuts

by setting a combination of the flags above, you can declare alternatives. example: the combination "unused+absent" means the partition may exist (in which case it shall not be used) or may be absent. either is fine, we're flexible. 💅

and the combination "unprotected+verity+signed+encrypted+unused+absent" can be written with the special shortcut "open". what does open mean? the partition may exist or may be absent, but if it exists it is used, regardless of the protection level. periodt.

special rule alert: if none of the flags above are set for a listed partition identifier, the default policy of open is implied. like, setting none of these flags effectively means all of the flags listed above will be set. yes really. 🙈

---

🏷️ GPT partition flag policies

these flags dictate the state of specific GPT partition flags:

• read-only-off, read-only-on — require that the partitions have the read-only partition flag off or on.
• growfs-off, growfs-on — require that the partitions have the growfs partition flag off or on.

if both read-only-off and read-only-on are set for a partition, then the state of the read-only flag on the partition is not dictated by the policy. and setting neither flag is equivalent to setting both — i.e. setting neither of these two flags means effectively both will be set. the same exact logic applies to growfs-off / growfs-on. ✨

---

🫥 unlisted partitions

if partitions are not listed inside an image policy string, the default policy flags get applied — and those are configurable via that empty partition identifier we mentioned earlier, iykyk. if no default policy flags are configured in the policy string at all, it's implied to be "absent+unused"...

...except for the Verity partition and their signature partitions, where the policy is automatically derived from the minimal protection level of the data partition they protect, as encoded in the policy. 🦋

---

🌈 SPECIAL POLICIES 🌈

the special image policy string "*" is short for "use everything", i.e. it's equivalent to:

=verity+signed+encrypted+unprotected+unused+absent

the special image policy string "-" is short for "use nothing", i.e. it's equivalent to:

=unused+absent

the special image policy string "~" is short for "everything must be absent", i.e. it's equivalent to:

=absent

---

💻 USE 💻

most systemd components that support operating with disk images support a --image-policy= command line option so you can specify the image policy you want to use. and they default to relatively open policies (typically the "*" policy we just described), operating under the assumption that trust in disk images is established before the images get passed to the program in question. 💖

for the host image itself, systemd-gpt-auto-generator(8) is the one responsible for processing the GPT partition table and making use of the included discoverable partitions. it accepts an image policy via the kernel command line option systemd.image_policy=. 👑

now, a big important note, bestie: image policies do not dictate how the components will mount and use disk images. they only dictate which parts to avoid, and which protection level and arrangement to require while mounting/using them. for example:

• systemd-sysext(8) only cares about the /usr/ and /opt/ trees inside a disk image, so it ignores any /home/ partitions (and similar) in all cases — even if they're included in the image, and regardless of whether the configured image policy would allow access to it or not.
• similarly, systemd-nspawn(1) is not going to make use of any discovered swap device, regardless of whether the policy would allow that or not.

use the image-policy command of the systemd-analyze(1) tool to analyze image policy strings, and to determine what a specific policy string actually means for a specific partition. 🔍

---

🌸 EXAMPLES 🌸

example one — this image policy string dictates that one read-only Verity-enabled /usr/ partition must exist, plus encrypted root and swap partitions. all other partitions are ignored:

usr=verity+read-only-on:root=encrypted:swap=encrypted

example two — this image policy string dictates an encrypted, writable root file system, and an optional /srv/ file system that must be encrypted if it exists, and no swap partition may exist:

root=encrypted+read-only-off:srv=encrypted+absent:swap=absent

example three — this image policy string dictates a single root partition that may be encrypted, but does not have to be, and ignores swap partitions, and uses all other partitions if they are available, possibly with encryption:

root=unprotected+encrypted:swap=absent+unused:=unprotected+encrypted+absent

example four — this image policy string dictates a single root partition that can only be erofs or squashfs, and ignores swap partitions, and uses all other partitions if they are available, possibly with encryption:

root=erofs+squashfs:swap=absent+unused:=unprotected+encrypted+absent

---

👀 SEE ALSO 👀

systemd(1), systemd-dissect(1), systemd-gpt-auto-generator(8), systemd-sysext(8), systemd-analyze(1)

---

📝 NOTES 📝

1. UAPI.2 Discoverable Partitions Specification https://uapi-group.org/specifications/specs/discoverable_partitions_specification

---

okay that's the whole page, you ate that fr fr 💅✨ this was systemd.image-policy from systemd 262.1, SYSTEMD.IMAGE-POLICY(7), no cap. go forth and policy your disk images, bestie 🎀🦋💖