From 732e6454f5c01322af66863ddbe2e7cfc6a7a1cb Mon Sep 17 00:00:00 2001 From: Joseph Marrero Corchado Date: Thu, 13 Aug 2026 22:43:03 -0400 Subject: [PATCH] docs: Document tmpfs-backed storage for usr-overlay The transient overlay created by `bootc usr-overlay` is backed by a tmpfs filesystem, meaning installed packages consume system RAM rather than persistent disk. The kernel default sizes this tmpfs at 50% of physical RAM, and there is currently no pre-flight space check before the overlay fills up. This is not obvious from the existing documentation and can lead to confusing ENOSPC errors on memory-constrained systems such as CI runners or small VMs, where users may assume the overlay uses disk storage. Assisted-by: AI Signed-off-by: Joseph Marrero Corchado --- docs/src/man/bootc-usr-overlay.8.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/src/man/bootc-usr-overlay.8.md b/docs/src/man/bootc-usr-overlay.8.md index c7bae74c38..ac48fe3911 100644 --- a/docs/src/man/bootc-usr-overlay.8.md +++ b/docs/src/man/bootc-usr-overlay.8.md @@ -19,6 +19,23 @@ A common pattern is wanting to use tracing/debugging tools, such as such as `apt` or `dnf` can apply changes into this transient overlay that will be discarded on reboot. +## STORAGE AND MEMORY REQUIREMENTS + +The transient overlay is backed by a `tmpfs` filesystem, which means all +data written to the overlay (i.e. installed packages) is stored in +**system memory (RAM)**, not on persistent disk. By default the kernel +sizes this `tmpfs` at 50% of physical RAM. + +On systems with limited memory, installing large packages into the +overlay can exhaust available RAM and result in `ENOSPC` ("No space left +on device") errors. There is currently no pre-flight space check and no +early warning before the `tmpfs` is full. + +Keep this in mind when using transient overlays in memory-constrained +environments such as CI runners or small virtual machines. If the +combined size of the packages being installed approaches half of the +system's RAM, consider increasing the VM's memory allocation instead. + ## /ETC AND /VAR However, this command has no effect on `/etc` and `/var` - changes