upperdir

Upperdir is a term used in layered or union filesystems in Linux, most commonly with OverlayFS. It designates the top writable layer in a stack of directories that are presented as a single merged filesystem. The upperdir sits above one or more lower (read-only) layers; the merged view reflects the combined content, with changes recorded in the upperdir.

In operation, when a file from the lower layers is modified, the file is first copied into the upperdir (a copy-up operation), and then the modification is applied there. Deletions from the merged view are implemented as whiteout entries created in the upperdir, which effectively hide corresponding files in the lower layers. The workdir is a separate directory used by the filesystem implementation to hold temporary state during operations.

Mounting a union filesystem such as OverlayFS typically involves specifying the lowerdir(s), upperdir, and workdir. A common mount setup is a command that provides these three paths at mount time, with the merged filesystem exposed at a mount point. The upperdir must be writable, and it is often located on the same underlying storage as the workdir. The lowerdir(s) can be read-only layers stacked beneath the upperdir.

Upperdir is central to the copy-on-write behavior of layered filesystems. It enables efficient use of storage by sharing common data across layers while isolating changes in the writable top layer. This concept is widely used in container runtimes and systems that rely on image layering and snapshotting. While the basic idea is shared across implementations like OverlayFS and AUFS, exact details can vary between filesystem versions and kernel configurations.