BOOTC-SETUP-ROOT-CONF(5)

💖 bootc-setup-root-conf.toml — the File Formats Manual glow-up (section 5, bestie) 💖

okay so bestie, gather round, because this is the little config file that decides how your whole root filesystem gets mounted, and it is literally living at /usr/lib/composefs/setup-root-conf.toml. no cap.

---

✨ SYNOPSIS ✨

/usr/lib/composefs/setup-root-conf.toml

---

🌸 DESCRIPTION 🌸

so here's the vibe: when the composefs backend is the one running the show, bootc-root-setup.service pops off in the initramfs, doing its little job of mounting the root filesystem before switch-root happens. and to know how to do that, it reads this optional TOML config file — which is the thing that controls how /, /etc, and /var get mounted. that's the whole assignment. 🎀

if the file is not there at all? no stress. every option just takes its documented default. the defaults ate, honestly.

but here's the part that's giving main character energy: the mere presence of this file (even if it's completely empty, like emotionally unavailable but still showing up) marks the image as composefs-native. and that decides which storage backend bootc install uses:

• if the image also has no ostree prepare-root.conf, it gets installed with the composefs backend
• otherwise it goes with ostree

(see bootc-installation(7) — yes, that's a real reference, go read it.) on top of that, bootc container lint then also stops requiring the /ostree symlink, and stops requiring the ostree prepare-root.conf composefs configuration that the ostree backend needs. so basically you get to skip a whole chore list. iconic.

also, the 51bootc dracut module installs this file into the initramfs automatically whenever it's present on the host image. so image authors can just ship the file at this path in their container image and rebuild the initramfs with a plain dracut --force — no --include flags needed. no extra drama. periodt. 💅

---

👑 SECTIONS 👑

[root]

this section controls the mount of the root (/) filesystem. yeah. the big one. the whole vibe.

• transient (boolean, default: false) — if true, the composefs root gets wrapped in a tmpfs overlay before switch-root. every single write to / gets yeeted at the next reboot. this is lowkey perfect for kiosk or lab systems where runtime modifications must NEVER persist. like, not even a little.

[etc]

this one controls how /etc gets mounted from the deployment state directory.

• mount (string) — one of "none", "bind" (the default), "overlay", or "transient". let's break it down because it's giving options:
  • none (alias "root") — /etc is not remounted at all. the composefs image's /etc is used directly and it is read-only. the system sees exactly the /etc baked into the container image, with no per-deployment state overlaid on top. 🫶 this requires that the OS and all services work without a writable /etc: SSH host keys, machine-id, NetworkManager leases, and similar files that are normally generated on first boot into the deployment's writable /etc must either be baked into the image or generated elsewhere (e.g. /var, systemd credentials). this mode is most useful in combination with [root] transient = true, where the transient overlay is already providing a writable surface over /etc. slay.
  • bind — /etc is bind-mounted from the deployment state directory, preserving persistent per-machine changes across reboots. this is the default ostree behaviour, bestie.
  • overlay — /etc is an overlayfs with the deployment state as the upper layer; writes go to state and persist across reboots.
  • transient — /etc is a tmpfs overlay; all runtime edits are discarded on reboot. suitable for immutable or sealed images where /etc drift is simply not the vibe.
• transient (boolean, default: false) — just shorthand for mount = "transient". it gets ignored when mount is also set. pick a lane, honestly. 🙈

[var]

and this section controls how /var gets mounted from the deployment state directory.

• mount (string) — one of "bind" (the default) or "none".
  • bind — /var is bind-mounted from the deployment state directory, preserving persistent per-machine data across reboots. the default. the standard. the reliable friend.
  • none (alias "root") — /var is not remounted; the composefs image's empty /var directory is used. combine it with systemd.volatile=state (see below) to get a fresh tmpfs on every single boot. 💖

for a fresh, ephemeral /var on every boot (think stateless or kiosk systems), use the systemd.volatile=state kernel argument. bootc-root-setup detects this karg automatically and skips the /var bind-mount, so you don't even need an explicit [var] section. she just knows. 🧚

the karg can be baked into the image via /usr/lib/bootc/kargs.d/:

# /usr/lib/bootc/kargs.d/50-var-volatile.toml
kargs = ["systemd.volatile=state"]

this causes systemd to mount /var as a plain tmpfs at early boot, which is fully compatible with tools like podman that use overlayfs under /var. 🌈

⚠️ note, and this one matters: unlike /etc and /root, using overlayfs (that's the "transient" mount type from earlier releases) for /var is not supported — because it breaks podman and other tools that use overlayfs under /var/lib/containers. do not do it. i'm begging. 💀

---

🦋 EXAMPLES 🦋

default (all persistent, equivalent to an absent file):

[etc]
mount = "bind"

transient /etc — suitable for sealed or integrity-verified images where runtime /etc changes should be discarded on reboot:

[etc]
transient = true

transient root with read-only /etc — / and /etc follow the composefs image exactly within the session (all writes discarded on reboot). to also make /var ephemeral, combine with systemd.volatile=state in kargs.d:

[root]
transient = true

[etc]
mount = "root"

---

🍓 FILES 🍓

• /usr/lib/composefs/setup-root-conf.toml — the configuration file read by bootc-root-setup.service. that's her. that's the one.

---

💜 SEE ALSO 💜

bootc-root-setup.service(5), bootc(8)

---

⭐ VERSION ⭐

v1.17.1

---

okay bestie that's the whole page, you're officially educated 🎀 this was section 5 of the File Formats Manual, BOOTC-SETUP-ROOT-CONF(5), brought to you by v1.17.1 — now go mount something responsibly, mwah 💅✨