OverlayFS Internals

The last lesson treated layered images as a stack of name -> path maps. Real Docker uses OverlayFS — a union filesystem with two more mechanisms you haven't seen yet: whiteouts and opaque directories.

Whiteouts

When you rm /etc/hosts inside a container, the file in the lower layer can't actually be deleted (lowers are read-only). OverlayFS creates a special character device with major:minor = 0:0 in the upper layer at that path. The kernel reads this device, recognises the whiteout, and hides the lower file.

upper/etc/hosts  -> char dev 0:0  ("this path is deleted")
lower/etc/hosts  -> the actual file (still there)
user sees:         ENOENT

Opaque directories

What if you delete an entire directory? Creating one whiteout per child doesn't scale. OverlayFS marks the upper directory with the xattr trusted.overlay.opaque="y". Effect: the kernel ignores any lower entries with that path, all children of the lower directory become invisible.

upper/var/log/  (opaque)
  + my-app.log  (new)
lower/var/log/
  - syslog
  - auth.log
  - ...
user sees:        just my-app.log

Copy-up

First write to a lower-only file triggers a copy-up: the file is copied to the upper layer, then modified there. This is why WRITE is slow the first time and fast afterward, and why the container's writable layer grows as you touch lower files.

For this exercise: implement READ/WRITE/DELETE/LS/OPAQUE on top of a lower + upper, respecting whiteouts and opaque markers.

Reference: Documentation/filesystems/overlayfs.rst in the kernel tree; Liz Rice ch. 4.