SYSTEMD.IMAGE-FILTER(7)

✨ NAME ✨

systemd.image-filter — Disk Image Dissection Filter 💅 (yes bestie, it's the manual page systemd.image-filter, and it's lowkey iconic)

---

🦋 DESCRIPTION 🦋

okay so picture this: in systemd, whenever a disk image (a DDI, short for Discoverable Disk Image) that implements the UAPI.2 Discoverable Partitions Specification[1] gets activated, you can hand it a filter that controls which partitions are even considered for mounting. no cap.

That filter — the disk image dissection filter — is literally just a string. Inside that string you've got per-partition-type patterns, and they're separated by colons (":"). Each individual rule is made of three lil pieces:

• a partition identifier
• an equal sign ("=")
• a shell globbing pattern that gets applied to the GPT label string of the partition

For the whole deets on shell globbing, go read glob(7). 🫶

The partition identifiers that are currently defined are, and I'm gonna list every single one because we don't skip:

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

These identifiers match up with the relevant partition types in the Discoverable Partitions Specification, but bestie they are agnostic to CPU architectures ✨ — they don't care what chip you're on.

---

🌸 USE 🌸

So like, a bunch of different systemd components that support working with disk images all support a --image-filter= command line option, and that's how you specify which image filter to use. 🎀

If you don't specify a filter at all? Then every partition in the partition table gets considered, and no per-label filtering gets applied. The one exception (and it's always the exception, she's that girl) is that partitions with the "_empty" label are always ignored. periodt.

For the host root file system 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. She accepts an image filter via the kernel command line option systemd.image_filter=. 👑

---

💖 EXAMPLES 💖

okay so here's an image filter string that dictates: for the root file system partition, only partitions whose label begins with "ParticleOS-" shall be considered. And for the /usr/ partition, the precise label "ParticleOS_47110815" is required. she's picky, we respect it 💅

root=ParticleOS-*:usr=ParticleOS_47110815

---

🧚 SEE ALSO 🧚

• systemd(1)
• systemd-dissect(1)
• systemd-gpt-auto-generator(8)
• systemd.image-policy(7)

---

🌈 NOTES 🌈

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

---

and that's the whole vibe bestie, no notes 🫶 this was brought to you by systemd 262.1, the version that ate and left no crumbs. go dissect some disk images, mwah 💖✨🎀