In this lesson, you will learn how to use Opaque Directories to completely mask entire directory structures from lower layers within an OverlayFS mount.
While whiteout files are effective for deleting individual files, they become cumbersome when you need to hide an entire directory hierarchy inherited from a lower read-only layer. If you simply delete the files one by one, the directory entry itself remains visible, which can cause issues with application logic or directory-traversal tools.
The Mechanism of Opaque Directories
An Opaque Directory is a directory in the upper layer that effectively tells the OverlayFS driver: "Ignore everything underneath me." When the kernel encounters an Opaque Directory, it treats it as if it were empty, regardless of whether the same directory exists in the lower layers.
To mark a directory as opaque, the kernel sets an extended attribute on the directory in the upper layer. Specifically, it sets trusted.overlay.opaque to the value y.
Practical Illustration
Imagine you have a read-only base layer containing /data/config/ with several sensitive files, and you want to completely hide this configuration from your container's view. Instead of whiteing out every file individually, you create the directory in your upper layer and set the opaque flag:
# Create the directory in the upper layer
mkdir -p /mnt/upper/data/config
# Mark the directory as opaque
setfattr -n trusted.overlay.opaque -v y /mnt/upper/data/config
Once this is applied, even if /mnt/lower/data/config/ contains hundreds of files, the merged view will present /data/config/ as an empty directory. The underlying files are not deleted; they are simply "masked" by the upper directory’s opaque status. This is a critical primitive for container runtimes, as it allows for clean, atomic overrides of filesystem paths during image composition or layer management. It provides a robust way to ensure that "removed" configurations or data structures are completely invisible to processes running within the union mount.
Key Takeaway: Opaque Directories use the trusted.overlay.opaque extended attribute to atomically hide the entire contents of a lower-layer directory, ensuring a clean state for your containerized applications.