OverlayFS Stashed Credentials Separate Overlay Access from Backing Filesystem Access

A process opens a path through an OverlayFS mount and appears to access one ordinary filesystem object. The kernel may actually consult an upper layer, a lower layer, or both, and a write can trigger copy-up before the requested operation proceeds. That indirection creates an authorization problem: the caller must be permitted to use the object as exposed by the overlay, while the internal access to the backing filesystems must also run under a defined security identity.

OverlayFS addresses those checks with two credential contexts. Access against the overlay object is evaluated with the credentials of the current task. Operations that OverlayFS performs on the underlying upper or lower filesystem use credentials stashed with the overlay superblock. The split is part of the filesystem’s permission model, not an incidental implementation detail.

One pathname crosses two authorization contexts

The first permission check applies to the object presented by OverlayFS. Normal discretionary access control and applicable Linux Security Module policy can reject the caller at this layer. This check follows the caller’s current credentials, so changing the process identity can change its ability to access the overlay namespace.

If that check succeeds, OverlayFS may need to perform an operation on a real inode in an upper or lower filesystem. That backing operation is checked again, but with the stashed credentials. The second check prevents the overlay implementation from simply borrowing whatever backing-filesystem authority the current caller happens to possess.

The two checks answer different questions. The overlay check decides whether the caller may act on the merged object. The backing check decides whether the identity assigned to OverlayFS may carry out the filesystem work needed to satisfy that request. A deployment can therefore produce a denial even when one side of the boundary would permit the operation in isolation.

This separation is especially visible when a backing filesystem has policy that is not identical to the merged overlay view. POSIX mode bits, ACLs, LSM labels, mount conditions, and filesystem-specific permission behavior can all affect the final result.

The superblock records the backing-access identity

OverlayFS stores credentials when its superblock is created. With the legacy mount(2) interface, the credentials of the task performing the mount are stashed. With the newer mount API, the default point is the task that creates the superblock through fsconfig() using FSCONFIG_CMD_CREATE.

That timing matters in software that separates mount construction across helpers or privilege transitions. Setting mount options and creating the superblock are distinct operations in the newer API. The identity active at superblock creation becomes part of subsequent backing-filesystem access behavior.

Linux also provides the OverlayFS override_creds mount option for the new mount API. When that option is used, the credentials of the calling task are recorded instead of retaining the default superblock-creation identity. This option changes the credential-selection point; it does not collapse the two permission checks into one.

Credential stashing is consequently an architectural input. A mount assembled by a privileged service can carry different backing authority from a mount whose superblock is created after that service has reduced privilege, even when both expose an otherwise similar directory layout.

Copy-up exposes the boundary during writes

A lower-layer file can be visible through the merged mount without an upper-layer copy. A write that requires modification cannot alter a read-only lower object in place, so OverlayFS may create a corresponding object in the upper layer and copy data and metadata before continuing.

The caller-facing permission check still applies to the overlay object. The internal creation, metadata work, and access to backing objects are performed through OverlayFS and are constrained by the stashed credentials plus the backing filesystems’ own checks.

This means that permission before copy-up and permission after copy-up are intended to remain consistent from the caller’s overlay view. OverlayFS documents this as a core permission-model objective. It also requires that the task creating the overlay mount not gain extra privilege merely through the overlay.

Those goals do not mean that direct access to the upper or lower directories is equivalent to access through the merged mount. A task can have a different result through the overlay because the overlay path introduces both its own object view and the stashed-credential check. Direct backing access bypasses that composition and is governed by the task’s credentials against the backing filesystem itself.

Stashed privilege can make the overlay more capable than the caller

The permission model permits a caller to gain access through the overlay relative to what that same caller could do by directly reaching a backing layer. That is not the same as the mount creator gaining new privilege. The overlay can act as a controlled intermediary whose stashed identity has authority on the backing filesystem while the caller is restricted to the merged namespace and its permission checks.

This property is useful only when the overlay-facing policy is treated as a real security boundary. If untrusted callers can also reach the upper or lower directories directly, they may encounter a different authorization surface. Namespace construction, bind mounts, directory permissions, and LSM policy can therefore be as important as the OverlayFS mount options themselves.

The model resembles a narrow deputy: the filesystem implementation performs backing work with an identity selected at mount construction. The caller does not receive those credentials as process credentials, but successful overlay operations can cause work to occur under them. Security review should consequently focus on the operations exposed through the merged mount rather than treating the stashed identity as invisible plumbing.

Metadata operations can involve both layers

OverlayFS does more than redirect file data. Rename, unlink, directory merge behavior, whiteouts, opaque directories, extended attributes, and copy-up metadata can require operations on upper-layer objects while preserving the merged namespace semantics.

Each such operation can cross from the caller-facing overlay check into backing work. The exact backing operations depend on object state and the requested action, so a successful read does not imply that a later rename or write will succeed. The latter may require upper-layer creation or metadata changes that exercise additional backing permissions.

This also makes permission failures sensitive to layer state. Two paths with similar visible mode bits can behave differently if one already has an upper object while the other still requires copy-up. The visible overlay metadata is not a complete description of every backing permission that a future mutating operation may encounter.

Operational diagnostics should therefore retain the distinction between an overlay denial and a denial arising while OverlayFS acts on a backing filesystem. Treating every EACCES or EPERM as a simple check against the visible inode can hide the credential boundary that produced the result.

LSM policy remains part of both decisions

OverlayFS does not replace Linux Security Module enforcement. Security hooks can participate in checks on the overlay object and in operations against backing objects. The labels and policy involved can differ because the merged object and its underlying inode are not interchangeable security contexts.

A policy design that grants a mount service broad backing access but expects confined workloads to receive only a narrow overlay view must account for both sides. The service’s stashed credentials need enough authority for legitimate backing work, while overlay-facing labels and namespace exposure constrain what workloads can request.

Overbroad stashed authority increases the set of backing operations the overlay can perform when an overlay-facing request passes its first check. Overly narrow authority produces operational failures during copy-up or metadata changes. The useful boundary lies in matching the stored identity to the backing operations the mount is intended to support.

Mount construction is part of the trust boundary

OverlayFS permission behavior is not determined solely by the ownership and mode bits visible after the mount exists. The identity captured during mount construction persists as an input to backing access, and the capture point depends on the mount API and credential-selection options.

For systems that build overlays inside container managers, sandbox launchers, package systems, or privileged helpers, that makes mount creation a security-sensitive transition. The process that selects layers, creates the superblock, applies credential behavior, and exposes the resulting mount determines both the namespace presented to callers and the authority available behind that namespace.

A sound isolation design keeps those roles explicit. Caller credentials govern entry through the overlay view; stashed credentials govern OverlayFS operations on the backing filesystems; backing filesystem and LSM policy remain independent enforcement layers. Collapsing those identities conceptually can produce access assumptions that the kernel’s actual two-context model does not support.