Overlay Filesystem / UnionFS

ChatGPT /

OverlayFS - kernel

⚠️ Writes must go to a local filesystem

OverlayFS has strict rules:

  • Lower layer (read-only): Can be NFS-mounted
  • Upper layer (read-write): Must be a local filesystem (ext4, xfs, etc.)
  • Workdir: Must be on the same local filesystem as the upper layer

UnionFS / MergerFS

MergerFS is actively maintained and preferred today.

ComposeFS

⚠️ composefs is not a general-purpose union filesystem, and it’s not suitable for arbitrarily unioning an NFS directory with another directory. [Content-Addressable Overlay Filesystem for Linux]https://github.com/composefs/composefs?tab=readme-ov-file#composefs-the-reliability-of-disk-images-the-flexibility-of-files) / HN

  • Using Composefs in OSTree - The idea is that instead of checking out a hardlinked directory and passing that on the kernel commandline we build a composefs image, enable fs-verity on it and put its filename and digest on the kernel command line instead.

caption

Mount overlayfs within unprivileged user namespace

$ unshare --mount -r			# create a new mount namespace. (with --map-root-user)
mkdir upperdir lowerdir mergeddir
mount -t overlay -o lowerdir=/path/to/lowerdir,upperdir=/path/to/upperdir,workdir=/path/to/workdir overlay /path/to/mergeddir

see also

Written on June 15, 2023, Last update on October 11, 2025
filesystem content docker cgroup