BOOTC-USR-OVERLAY(8)

💖 BOOTC-USR-OVERLAY 💖

okay bestie, welcome to the bootc-usr-overlay(8) page, straight out of your System Manager's Manual 🫶 this is the one that yeets a whole temp overlay onto /usr and then forgets it ever happened.

---

✨ NAME ✨

bootc-usr-overlay — drops a transient overlayfs on /usr that gets thrown away the moment you reboot 🦋

---

✨ SYNOPSIS ✨

bootc usr-overlay [OPTIONS...]

---

✨ DESCRIPTION ✨

So what this does is slap a transient overlayfs on top of /usr, and no cap, it's getting discarded on reboot. Gone. Poof. 💅

And it's read/write by default, just so you know.

---

🌸 USE CASES 🌸

the classic move here? you wanna run tracing/debugging tools — think strace — and they're just... not in the base image 😭. Not a vibe.

That's where a system package manager like apt or dnf comes in: it can apply changes into this transient overlay, and everything it does gets discarded on reboot. main character energy for your debugging session, zero permanent consequences ✨

---

🧚 STORAGE AND MEMORY REQUIREMENTS 🧚

okay this part is important so pay attention bestie 👑

the transient overlay is backed by a tmpfs</> filesystem, which means every single thing you write into the overlay (yes, including all those packages you installed) is living in system memory (RAM), not on persistent disk. it's giving "temporary" fr fr.

By default the kernel sizes this tmpfs at 50% of physical RAM.

So on systems with limited memory, installing big packages into the overlay can straight up exhaust your available RAM and hit you with ENOSPC — that's "No space left on device" 💀. And here's the tea: there is currently no pre-flight space check and no early warning before the tmpfs is full. it just fills up and then it's over.

Keep this in mind when you're doing transient overlays in memory-constrained environments like CI runners or tiny virtual machines 🙈. And if the combined size of the packages you're installing is approaching half of the system's RAM? consider increasing the VM's memory allocation instead. like, actually. do that.

---

🌈 /ETC AND /VAR 🌈

so here's the plot twist 😭 — this command has no effect on /etc and /var. changes written there will persist. and it's super common for package installations to modify these directories. so yeah. those ones stay. no take-backs.

---

💜 UNMOUNTING 💜

almost always, some system process is gonna be holding a reference to that open mount point, so it just won't let go 😤.

You can however invoke:

umount -l /usr

to perform a "lazy unmount". iconic workaround honestly.

---

💅 OPTIONS 💅

• --read-only — mount the overlayfs as read-only. and a read-only overlayfs is genuinely useful, because it may be remounted as read/write in a private mount namespace and written to while the mount point stays read-only to the rest of the system. sneaky? yes. useful? also yes. 🎀

---

⭐ VERSION ⭐

v1.17.1

---

and that's the whole page, bestie 💖 you now know everything this manual page knows, no gatekeeping.

this has been bootc-usr-overlay(8) from the System Manager's Manual, version v1.17.1 — go forth and overlay responsibly, mwah 🫶✨