Ephemeral Sandbox mascot — a Siamese kitten peeking out of its wooden sandbox
Browse architecture
Chapter 02

A leased history becomes one writable kernel view.

OverlayFS bridges LayerStack storage and an executing workspace. It combines pinned immutable lower layers with one session’s private writable state inside the session’s mount namespace.

Section 02 · Overlay mount

Storage supplies the layers. A namespace owns the view.

LayerStack does not expose a writable checkout. The runtime takes one pinned lease, adds fresh per-session writable directories, and asks the kernel to attach exactly one merged workspace inside the holder's mount namespace.

The bridge

Two inputs meet at one kernel object.

LayerStack contributes stable lower paths and a lease that keeps them alive. The namespace runtime contributes a holder, user and mount namespace file descriptors, and a pre-existing workspace root. A one-shot runner joins those namespaces and builds the overlay there.

Ownership handoff

No base tree is copied or materialized during this handoff.

LayerStack lease

[L42, S41, B1]

immutable · newest-first · pinned

One-shot runner

setns(user, mnt)

configure · attach · mask · exit

Mounted workspace

/workspace

private writes · shared reads

Mount anatomy

One visible root, four different roles.

The upperdir and lowerdirs participate in the merged view. The workdir does not: it is private kernel scratch and must remain a sibling of the upperdir on the same filesystem.

OverlayFS priority

Highest visible source first

one session
/workspacemerged root
upper/ws-17rw

private writes + whiteouts

L0000421 · newest published delta
S0000412 · compacted immutable history
B000001-base3 · oldest · shared base
work/ws-17kernel scratch · not visible
Workspace root
The pre-existing mountpoint that workloads see as the merged filesystem.
Upperdir
The session-private writable tree. New files, copy-ups, and deletion metadata land here.
Workdir
OverlayFS scratch space beside the upperdir. It supports kernel operations but is not part of the visible stack.
Lowerdirs
The leased immutable layers in newest-first priority order, with the shared base last.
Raw mount API

Configure detached. Attach once.

The runtime calls the Linux new-mount API directly. It does not invoke the mount(8) binary, assemble a legacy option string, or attach a half-built filesystem to the daemon's namespace.

mount_overlay()
  1. 01
    fsopen

    Open a new overlay filesystem context.

  2. 02
    fsconfig · lowerdir+

    Append each leased lower path, newest first.

  3. 03
    fsconfig · userxattr

    Enable user-namespace-compatible overlay metadata.

  4. 04
    fsconfig · upper / work

    Attach the session’s real writable paths.

  5. 05
    fsconfig_create

    Ask the kernel to finish the filesystem configuration.

  6. 06
    fsmount

    Create the detached, read-write mount object.

  7. 07
    move_mount

    Attach that object to the real workspace root.

Lowerdirs are pinned

Each leased lower directory is opened without following its final symlink and passed to the kernel through a /proc/self/fd/N path. Renaming its original path cannot redirect this mount build.

Writable paths stay real

Upperdir, workdir, and workspace root are validated and held open, but configured with real paths because common kernels do not accept the same FD-path treatment for these roles.

Ordering + copy-on-write

Array order becomes filesystem truth.

Publication prepends a layer. A lease copies manifest order into its paths. Workspace and runner messages preserve that array. Finally, the first lowerdir+ call receives highest priority. The plumbing does not sort or re-derive the order later.

One invariant across four boundaries
  1. 01

    Manifest

    prepend newest L*

  2. 02

    Lease

    copy ordered paths

  3. 03

    Runner request

    serialize unchanged

  4. 04

    Kernel

    first lowerdir+ wins

Read

first visible path wins

The upperdir is checked first, then leased lower layers from newest to oldest.

First mutation

lower file → copy-up

OverlayFS may copy the complete lower file into the upperdir before applying the write.

Delete

lower path → whiteout

A deletion marker hides the immutable lower path without changing shared history.

Copy-on-write is not byte-diff-on-write. A small edit to a lower-only file can require copying that whole file into the upperdir first.

Capture handoff

The upperdir is both the write target and the change record.

Capture does not copy the merged workspace. It walks the private upperdir, preserves OverlayFS deletion and opacity semantics, and prepares a candidate immutable delta. Workspace coordination decides whether that candidate may become shared history.

Kernel state becomes a publication candidate
  1. 01

    Quiesce writes

    The session gate stops lifecycle races around capture.

  2. 02

    Walk upperdir

    Read created files, copied-up entries, whiteouts, and opaque directories.

  3. 03

    Stage delta

    Build private immutable payload and path metadata outside the manifest.

  4. 04

    Hand off

    Conflict detection and merge determine whether publication can commit.

Overlay metadata is semantic. Dropping a whiteout or opaque-directory marker can resurrect an older lower-layer path. Capture must translate those markers, not treat them as disposable scratch.

Namespace-owned lifetime

The daemon coordinates the mount. It never owns the mount.

The one-shot runner joins only the holder's user and mount namespaces. After mounting and applying configured path masks, it deliberately gives up its userspace teardown guard. Kernel namespace references keep the overlay alive after the runner exits.

  1. 01

    Daemon

    spawn holder and open namespace FDs

  2. 02

    Runner

    join holder user + mount namespaces

  3. 03

    Kernel

    attach overlay; mask configured host paths

  4. 04

    Holder

    namespace pins the mount until teardown

Store paths are masked

Existing configured paths such as the runtime storage root receive a tiny, read-only, no-exec tmpfs cover inside the workload namespace after the overlay is attached.

Teardown follows ownership

Normal session destroy kills the holder. When its isolated mount namespace dies, the kernel drops the overlay; the runtime then removes the session scratch tree.

Limits + failure semantics

Reject ambiguity before attach. Preserve kernel errors after it.

Validation constrains path shape and directory identity. It does not promise that every Linux kernel accepts every layer chain; feature support and practical stack depth remain kernel limits.

Linux kernel boundary
Mount syscalls are Linux-only; non-Linux builds do not provide a real overlay workspace.
Non-empty lease
At least one lower layer is required. The workspace root and every lower layer must already exist.
Directory integrity
Root, lower, upper, and work paths are opened as directories without following a final symlink.
Path hygiene
Mount inputs reject comma, colon, backslash, control whitespace, and NUL before configuration.
Kernel-sized stack
The runtime sets no synthetic lower-layer cap; the kernel rejects an unsupported chain.
No hidden fallback
Syscall failures retain their operation context instead of silently changing mount semantics.

Before syscalls

Invalid input

No mount context is created. Session setup fails with the validation detail.

Before attachment

Kernel build failure

Owned file descriptors close; a detached mount that never moved to the root is discarded.

After attachment

Namespace lifetime

The holder namespace owns the live mount; ordinary teardown relies on namespace death, not lazy detach.

Live squash remount is the deliberate exception: it stages a second overlay, moves mountpoints through pre-opened FDs, and uses strict unmount so EBUSY remains visible instead of being hidden by lazy detach.

Previous · 01LayerStack store & copy-on-writeNext · 03Namespace execution & isolation