How OverlayFS Works: Layers, Whiteouts, and Why Containers Share Base Images

A container that starts from a shared Debian image layer, writes a new hostname into /etc/hostname, and deletes a file that came from the base image does not modify the image that other containers still use. The base layers stay identical on disk. The container sees a private writable view produced by OverlayFS.

This article explains how lower and upper directories are merged, when a file is copied up, how deletions are recorded, and why containers share image layers. Related: How Linux Namespaces and cgroups Work.

The contract

OverlayFS is a union mount presenting one or more read-only lower directories and one writable upper directory as a single tree. Lookups prefer upper. Directories merge; non-directories in upper hide lower names. Writes to lower files cause copy-up. Deletions use whiteouts. Workdir (same FS as upper) enables atomic copy-up.

Lower layers are never modified. That is why multiple containers share the same image layers.

Mount

mount -t overlay overlay -o lowerdir=/layer2:/layer1,upperdir=/upper,workdir=/work /merged

Leftmost lower has highest precedence. Upper is writable. Work is scratch. Merged is the view.

Lookup and merging

Non-directory: upper first, then lowers. Whiteout hides lower match. Directories: merge names; upper metadata wins. readdir unions the lists.

Copy-up

Write open or metadata change on lower file copies the whole file (data + xattrs) to upper via workdir rename. After that, operations hit the upper copy. File granularity, not page.

Whiteouts and opaque

Delete of lower file creates whiteout (char 0,0 or xattr trusted.overlay.whiteout) in upper. Lookup ignores lower and hides the whiteout → ENOENT. Opaque dir (xattr trusted.overlay.opaque=y) hides entire lower directory.

Sharing

Lowers immutable → shared across containers. Only per-container upper holds diffs. Start cost is empty upper + mount, not copy of image.

Limitations

Rename of lower dir returns EXDEV by default. Limited hard links. st_dev/st_ino quirks unless xino. Large copy-up visible as latency.

Example

mkdir -p /tmp/ov/{lower,upper,work,merged}
echo original > /tmp/ov/lower/file.txt
mount -t overlay overlay -o lowerdir=/tmp/ov/lower,upperdir=/tmp/ov/upper,workdir=/tmp/ov/work /tmp/ov/merged
echo modified > /tmp/ov/merged/file.txt
rm /tmp/ov/merged/file.txt
ls -l /tmp/ov/upper

Lower unchanged; upper has the changes or whiteout.

Takeaways

OverlayFS merges RO lowers with RW upper. Upper names hide lowers; dirs merge unless opaque. Copy-up on write. Whiteouts for delete. Immutability of lowers enables sharing of container image layers. Independent of namespaces/cgroups.