OverlayFS: Mounting, File Operations, and Android Use Cases

OverlayFS is a stacking file system that can overlay the contents of multiple directories into a single merged directory. It does not depend on the underlying disk layout and works with source directories of different file‑system types.

Mounting OverlayFS

Typical mount command:

mount -t overlay -o lowerdir=/lower,upperdir=/upper,workdir=/work overlay /merged

This stacks the lowerdir and upperdir directories onto /merged . The workdir must be an empty directory on the same file‑system type as upperdir .

Variants:

mount -t overlay -o lowerdir=/upper:/lower overlay /merged (read‑only merged view)

mount -t overlay -o lowerdir=/lower1:/lower2:/lower3,upperdir=/upper,workdir=/work overlay /merged (multiple lower layers separated by ‘:’; hierarchy: /lower1 > /lower2 > /lower3)

Behavior after mounting

• If a file exists with the same name in both lowerdir and upperdir , the version in upperdir hides the lower one. • Lower‑layer files have lower priority; same‑name files are hidden. • Directories with the same name are merged. • Modifications to files originating from upperdir are written directly to upperdir . • Modifications to files originating from lowerdir trigger a copy‑up: the file is copied to upperdir (the “copy‑up” feature) and subsequent changes affect the copy only; the original lower file remains unchanged. • Deleting a lower‑layer file creates a *whiteout* character device (major/minor numbers 0) in upperdir . Rename operations on lower‑layer entries are not supported by default; they return EXDEV unless the CONFIG_OVERLAY_FS_REDIRECT_DIR option is enabled.

Deleting files and directories

OverlayFS uses whiteout files to record deletions without altering the read‑only lower layer. After removing a file or directory in the merged view, a whiteout character device appears in upperdir (e.g., files aa , bb , dir in the example).

Creating files and directories

Creation always occurs in upperdir . If a whiteout file exists for the target, it must be removed first. When creating a new directory that shadows a lower‑layer directory, the directory must be marked opaque by setting the extended attribute trusted.overlay.opaque="y" (requires xattr support). An opaque directory causes OverlayFS to ignore any same‑named directories in lower layers.

Renaming directories

Two possible outcomes when renaming a lower‑layer directory:

1. EXDEV error (default behavior). 2. Successful rename if the redirect_dir feature is enabled, creating a copy in upperdir .

Control of redirect_dir can be done via:

• Kernel config options: OVERLAY_FS_REDIRECT_DIR , OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW . • Sysfs parameters: /sys/module/overlay/parameters/redirect_dir , redirect_always_follow , redirect_max . • Mount options: redirect_dir=on|off|follow|nofollow .

Application in Android

OverlayFS enables a read‑only system partition to become writable in Android’s userdebug / eng modes. After adb remount , /system is re‑mounted as an OverlayFS stack, allowing pushes to the system directory. The upper layer resides in /cache/overlay/system/upper , while the original /system partition remains unchanged. Similar techniques are used in OpenWRT to reduce flash wear and in cloud container platforms to overlay immutable base images with mutable layers.

Conclusion

OverlayFS’s unique stacking mechanism is increasingly adopted for Android system modification, OpenWRT flash‑wear reduction, and container image layering in cloud environments.