OverlayFS: a small write can trigger a large copy-up

When a name exists in upper and lower trees, the upper non-directory object generally hides the lower one; directories can present a merged set of names. The result is a namespace view, not a bytewise merge of two versions of the same regular file. The work directory supports OverlayFS operations and must satisfy the kernel's upper/work requirements, including being on the same filesystem. Sharing lower layers is common, but overlapping or concurrently reused upper/work directories have specific restrictions and are not a safe shortcut for sharing writable state.

Removing a lower-visible name cannot modify a read-only lower tree, so the upper layer records a whiteout that hides it in the merged view. An opaque upper directory can hide the corresponding lower directory's contents. Kernel representations include documented device or xattr forms depending on the feature configuration. These are distinct from OCI image archive whiteout naming conventions, which an image unpacker interprets. Deleting a lower-visible name does not imply its image bytes were erased from the lower layer or that its space was reclaimed there.

For an operation requiring write access to a lower-only file, OverlayFS may create the needed upper object, parent directories, metadata, and data before using that upper representation. Opening for read-write can cause copy-up even if no data is ultimately changed, under the documented behavior. Full-file data copying, reflink support, sparse allocation, caching, and filesystem-specific mechanisms affect actual physical work. An estimate based on the logical file size is an explicit model, not a universal measurement of device writes.

With metacopy enabled, a metadata-only operation can copy metadata without immediately copying file data. A later write still needs the appropriate data copy-up. Therefore changing ownership on a large lower file and editing its contents are not always equivalent costs. Record feature support and avoid trusting untrusted layer metadata or redirect combinations outside the documented security constraints. File identity fields can also behave differently across layers and configurations; do not assume a stable device-and-inode story from a single pre-copy observation.

A database, checkpoint writer, or model cache that repeatedly modifies large image-resident files can incur surprising startup and space costs. Consider whether mutable data belongs on a separately managed volume or should be initialized directly in the writable destination. That decision also changes backup and lifecycle semantics, so verify persistence expectations rather than merely moving files until a benchmark improves. Compare first-write behavior with later writes and account for upper-layer growth, page cache, metadata, and failure recovery separately.

The function lab illustrates one related payload-scaling effect, not OverlayFS itself. Reset, explicitly set a=1 and x=1, predict y=1, then Play or Step; for a separate comparison Reset and explicitly set a=1 and x=2, predicting y=4. Interpret x as normalized side length of a dense square file payload. Four times the lower-file payload can make a full logical copy-up four times larger under that model. The graph has no upper/lower trees, whiteouts, metacopy, reflinks, or device-I/O simulation.