overlayfs

overlayfs OverlayFS is a union mount filesystem for the Linux kernel that enables combining multiple directory trees into a single coherent view by presenting a writable layer atop one or more read-only layers. It is designed to support lightweight copy-on-write semantics for container images, live systems, and ephemeral filesystems, integrating with kernel VFS structures and userspace tooling. Developed within the Linux ecosystem, OverlayFS interacts with container runtimes, init systems, and distribution packaging tools to provide flexible layering and fast deployment.

Introduction

OverlayFS provides a union mount mechanism that merges an upper writable layer with one or more lower read-only layers to present a unified mount point. It targets use cases such as ephemeral filesystems for Docker, Kubernetes, systemd, Snapcraft, and Flatpak, and interoperates with storage drivers, kernel features like OverlayFS-adjacent subsystems, and filesystem interfaces used by Red Hat, Canonical, and SUSE. Implementers integrate OverlayFS with image distribution services such as Quay.io, Docker Hub, and orchestration platforms like OpenShift and Rancher.

Design and architecture

OverlayFS implements a layered union by treating one layer as an upper writable filesystem and one or more lower read-only filesystems; the resulting merged view resolves path lookups by consulting the upper layer first and falling back to lower layers. The architecture leverages kernel primitives from the Linux kernel VFS, inode and dentry caches, and copy-on-write semantics akin to techniques used in UnionFS and aufs; it uses a "whiteout" mechanism to hide files from lower layers similar to designs in Plan 9 and 9P protocols. Namespace isolation from Linux namespaces and mount propagation semantics from mount namespaces allow integration with container runtimes such as containerd and CRI-O.

Implementation and operation

The implementation resides in the Linux kernel source tree as a filesystem module that registers mount options, superblock operations, and inode operations. Operation requires specifying an upperdir and lowerdir(s) on mount, with the kernel handling copy-up of files on write, creation of opaque directories, and generation of whiteout entries implemented via special inode operations. Interaction with userspace tools like mount(8), systemd-nspawn, and image builders such as Buildah is common; overlay mounts are managed by init systems like systemd and orchestration frameworks in Kubernetes clusters. On-disk behavior depends on underlying filesystems like ext4, XFS, Btrfs, and ZFS, affecting features such as reflink support and atomic operations.

Use cases and applications

Common applications include container image layering for Docker, Kubernetes, and Podman, live CD systems employed by distributions like Ubuntu, Fedora, and Debian, and transactional update mechanisms in operating systems such as Fedora Silverblue and CoreOS. OverlayFS is used in continuous integration platforms like Jenkins and GitLab CI to provide ephemeral build environments, in cloud platforms including Amazon Web Services, Google Cloud Platform, and Microsoft Azure for fast provisioning, and in embedded devices managed by projects like Yocto Project and OpenWrt to reduce storage footprint.

Performance and limitations

Performance characteristics depend on the number of layers, underlying filesystem capabilities, and workload patterns; metadata-heavy workloads can stress dentry and inode caches in the Linux kernel, while write amplification occurs due to copy-up operations from lower layers. Limitations include restrictions on mixing underlying filesystems with incompatible features, constraints when using features like fuse or certain network filesystems, and historical issues with whiteout handling across lower layer types. Benchmarks from vendors like Red Hat and research groups show varying throughput and latency trade-offs compared to alternatives such as aufs and Btrfs subvolumes.

Security considerations

Security implications involve permission and ownership semantics when merging layers from different sources, potential escalation via improperly controlled upper layers, and interactions with mandatory access control systems such as SELinux and AppArmor. Container security platforms like gVisor and Kata Containers consider OverlayFS behavior when enforcing isolation; kernel hardening efforts in projects like Grsecurity influence attack surface. Administrators must consider namespace boundaries from user namespaces and mount propagation when designing secure deployments.

History and development

The filesystem originated from efforts to provide a simpler union mount solution within the Linux kernel tree, influenced by predecessors such as UnionFS and aufs, and underwent review through kernel mailing lists maintained by developers associated with organizations like Open Source communities and companies including Google, Red Hat, and Canonical. Key upstream integration milestones occurred across kernel versions, with maintenance and feature additions contributed by individuals and teams active in repositories and projects around Git and GitHub workflows. Continued development intersects with container ecosystem evolution driven by projects such as OCI and standards discussions at industry events like KubeCon.

Category:Linux filesystems