What is overlayfs.mdx?

overlayfs.mdx is a documentation file that lives inside the Linux kernel source tree. It is written in the MDX format, which is a mix of Markdown and JSX, and it explains how the OverlayFS file system works, its design, usage, and implementation details.

Let's break it down

OverlayFS is a “union” file system - it lets you stack one directory (the upper layer) on top of another (the lower layer) and see them as a single directory tree. Key concepts:

  • lowerdir - the read‑only base layer, often an existing image or filesystem.
  • upperdir - a writable layer where changes are stored.
  • workdir - a small helper directory needed for certain operations.
  • merged view - the combined view you interact with; reads come from lowerdir unless a file exists in upperdir, writes go to upperdir. The overlayfs.mdx file describes these pieces, shows the mount syntax (mount -t overlay overlay -o lowerdir=...,upperdir=...,workdir=... merged), and provides diagrams and code snippets.

Why does it matter?

OverlayFS makes it easy to create lightweight, copy‑on‑write environments. Instead of duplicating whole filesystems, you can share a common base and only store the differences. This saves disk space, speeds up container start‑up, and simplifies updates because you can replace just the upper layer.

Where is it used?

  • Inside the Linux kernel as the official implementation of OverlayFS.
  • Container platforms such as Docker, Podman, and Kubernetes use OverlayFS to build container images and run containers.
  • Live‑system tools (e.g., Ubuntu’s live‑CD) use it to overlay a read‑only OS image with a writable temporary layer.
  • Development environments that need fast, disposable file‑system snapshots.

Good things about it

  • Performance: Very low overhead; most operations are simple directory lookups.
  • Simplicity: Only a few mount options are needed, no special daemon required.
  • Flexibility: Can stack multiple layers, useful for layered images.
  • Wide support: Included in the mainline Linux kernel, works on most distributions.
  • Space efficiency: Stores only changes, not full copies of files.

Not-so-good things

  • Limited feature set: Does not support all POSIX file‑system semantics (e.g., rename across layers can be tricky).
  • Copy‑up cost: The first write to a file triggers a copy‑up from lower to upper, which can cause latency spikes.
  • Workdir requirement: Needs a separate work directory, adding a small management overhead.
  • Compatibility issues: Some older kernel versions lack full OverlayFS support, and certain filesystems cannot be used as lower or upper layers.
  • Security considerations: Misconfiguration of lower/upper layers can expose read‑only data to unintended writes.