{
  "slug": "overlayfs",
  "term": "OverlayFS",
  "aliases": [
    "overlay filesystem"
  ],
  "definition": "OverlayFS is a Linux filesystem that combines lower directory trees and an optional upper tree into one merged namespace.",
  "note": "Upper entries take precedence, while directory names can merge. Write access to a lower file can trigger copy-up; a read-write open may cause this even without changing data. With redirect_dir disabled, renaming a lower or merged directory fails with EXDEV. Enabling directory redirects changes that behavior. [linux-overlayfs-612]\n\nWhiteouts suppress matching lower names during lookup without exposing the marker as an ordinary file. They record visibility changes, not removal of the lower object. [linux-overlayfs-lookup]",
  "advantages": [
    "Allows changes in a writable upper tree while retaining lower-layer objects."
  ],
  "limitations": [
    "Copy-up and directory-rename behavior depend on the operation and configured features.",
    "A merged pathname view is not evidence of secure erasure or crash durability."
  ],
  "related": [
    "whiteout",
    "atomic-rename",
    "copy-up",
    "metacopy"
  ],
  "status": "shipping",
  "supersedes": [],
  "supersededBy": [],
  "firstSeen": null,
  "lastSeen": null,
  "updated": "2026-11-04",
  "citations": [
    {
      "id": "linux-overlayfs-612",
      "title": "Linux 6.12: Overlay Filesystem, layer lookup, copy-up and directory renames",
      "url": "https://docs.kernel.org/6.12/filesystems/overlayfs.html",
      "accessed": "2026-11-04"
    },
    {
      "id": "linux-overlayfs-lookup",
      "title": "Linux v6.12: OverlayFS ovl_lookup_single, whiteout and opaque-directory lookup",
      "url": "https://github.com/torvalds/linux/blob/v6.12/fs/overlayfs/namei.c#L213-L303",
      "accessed": "2026-11-04"
    }
  ],
  "provenance": [
    "Source review of Linux 6.12 and the cited API/specification; no mounted-overlay experiment or crash test."
  ]
}