whiteout · shipping · also whiteout marker

Whiteout

A whiteout is a layered-filesystem marker that hides a matching lower-layer name without deleting that lower-layer object.

Related Observatory article: Whiteout on hesela.com

Linux RENAME_WHITEOUT atomically couples a rename with creating a whiteout at its source. Outside an overlay, that API's marker appears as a character device with device number 0:0; filesystem support and CAP_MKNOD are required. This API representation is not a universal encoding for layered storage. [1]

OCI v1.1.1 instead serializes deletion as an empty regular TAR entry named .wh.<name>. The .wh..wh..opq entry hides lower-layer children of its directory. Both affect lower layers, not additions in the same layer, and the markers themselves are hidden when applied. [2]

Relations

related
OverlayFS, Unlink

Advantages

  • Represents a deletion in a higher layer without rewriting a lower layer.

Limitations

  • Visibility suppression is not physical erasure.
  • OCI archive markers must be interpreted as changes, not restored as ordinary payload files.

Citations

  1. Linux man-pages: rename(2), RENAME_WHITEOUT (accessed 2026-11-04)
  2. OCI Image Specification v1.1.1: layer changesets, whiteouts and opaque whiteouts (accessed 2026-11-04)
Sources & caveats
  • Source review of Linux 6.12 and the cited API/specification; no mounted-overlay experiment or crash test.

JSON: /data/terms/whiteout.json

Published by Hesela team · Updated

Report a correction · Editorial standards · Reuse guidance

Cite this page
Hesela team. Whiteout. Hesela. 2026-11-04. https://hesela.dev/terms/whiteout/