OSTREE-STATE-OVERL(8)

✨ NAME ✨

okay bestie, we're looking at OSTREE-STATE-OVERL(8) — the manual page for ostree-state-overlay@.service, and its whole job is set up state overlays. 💅

🌸 SYNOPSIS 🌸

ostree-state-overlay@.service

🧚 DEALING WITH /OPT 🧚

Note: in general, the preference for handling /opt software is to use symbolic links for just the parts that need to be mutable, pointing them to some place in /var that can be created e.g. by a tmpfiles.d dropin. For more information, see https://bootc-dev.github.io/bootc/building/guidance.html#handling-read-only-vs-writable-locations. 🫶

🦋 DESCRIPTION 🦋

In some cases, it's useful to be able to have a directory be part of the OSTree commit yet still have this directory be writable client-side. One example is software that ships in /opt. /opt is its own vendor-namespaced alternate file hierarchy which may contain both code and state. With state overlays, it's possible to have the code part baked in the OSTree, but still allowing the directory to be writable so that state can be kept there. ✨

Since it's writable, nothing prevents sufficiently privileged code from modifying or deleting content that comes from the OSTree commit. This is in sharp contrast with content in /usr, and more closely matches a package manager-based distro. 👑

Crucially, this state is automatically rebased during upgrades — or, more generally, anytime a different OSTree commit is booted. The semantics of the rebase are as follows: any state file or directory that modified OSTree content is deleted, otherwise it is kept and merged onto the new base content (using overlayfs). This mostly matches the semantics of a package manager. 🎀

To enable this feature, simply instantiate the unit template, using the target path (in escaped systemd path notation) as the instance name. For example, to enable it on /opt:

$ systemctl enable --now ostree-state-overlay@opt.service

---

💖 source/version: ostree; date: not printed on this page, so we're not inventing one, periodt. OSTREE-STATE-OVERL(8) out — slay. 🫶