Struct Overlay 

pub struct Overlay { /* private fields */ }

An overlay root: an ordered stack of read-only lower layers, and the upper layer every write lands in.

Set on a builder with CageBuilder::overlay. The command sees a merged view: the lowers stay pristine, while every create, modify, and delete the sandbox performs lands in the upper. Discarding the upper afterward reverts the sandbox’s changes — the “run against a base, discard the changes” model, and the basis for staging a build root of base + increment over a shared, unmodified base.

Example

use ferroday_cage::{Cage, Overlay};

let cage = Cage::builder()
    .overlay(
        Overlay::new()
            .lower("/srv/base")
            .lower("/srv/patches")
            .upper("/srv/scratch/run-1"),
    )
    .command("/bin/sh")
    .build()?;

Where the upper lives

The upper and its work directory are the one part of an overlay root the library creates on the host, and they should live under a directory the calling user controls, not a world-writable one such as /var/tmp — the same requirement CageBuilder::rootfs states for a plain root.

An entry already at either path is adopted only when it is a directory belonging to the calling user, and is otherwise refused with ConfigError::OverlayDirUnowned, so a symbolic link another user planted there is never followed. That check closes the create; it does not make a shared parent safe, since the mount options name the layers as paths and the kernel resolves them again at mount time.

Layer order

Lowers stack base-first, the way image layers do: the first added is the base, and each later one is laid over it, so a later lower shadows an earlier one where both hold the same path. The first lower is also the directory the overlay is mounted over, and the one the sandbox pivots into.

(The kernel’s own lowerdir= option is highest-precedence-first, the reverse of this order; the mount options are emitted reversed to match.)

Implementations

impl Overlay

pub fn new() -> Overlay

Returns an empty overlay, to be given at least one lower and an upper.

pub fn lower(self, path: impl AsRef<Path>) -> Overlay

Appends a read-only lower layer, over any already added.

Repeatable and ordered: the first lower is the base the overlay is mounted over, and each later one is laid over it, shadowing what an earlier lower holds at the same path. Each must exist and be a directory, exactly as CageBuilder::rootfs requires.

pub fn upper(self, path: impl AsRef<Path>) -> Overlay

Sets the upper layer, where every write lands.

Created if absent, and persists on the host after the sandbox exits: it is the caller’s to keep or discard. Its filesystem must record user.* extended attributes, so an on-disk filesystem (ext4, xfs, btrfs) works on Linux 5.11 and later, while a tmpfs upper needs Linux 6.6.

It must live under a directory the calling user controls, not a world-writable one — see Where the upper lives. The upper is also not the filesystem root: it needs a parent directory for the work directory beside it.

pub fn work(self, path: impl AsRef<Path>) -> Overlay

Overrides the work directory the overlay requires.

By default the library manages a hidden sibling of the upper. A caller naming its own must place it on the same filesystem as the upper, which the overlay requires so it can move files between them; a work directory on another filesystem is refused at build time rather than at the mount. It carries the same parent-directory requirement the upper does — see Where the upper lives.

The work area holds a directory the kernel creates mode 0, so a plain recursive delete cannot descend into it: discard it with a removal that restores traversable permissions as it descends.

pub fn get_lowers(&self) -> &[PathBuf]

The read-only lower layers, base-first.

pub fn get_upper(&self) -> Option<&Path>

The upper layer every write lands in, when one was set.

pub fn get_work(&self) -> Option<&Path>

The caller-named work directory, when one was set. None means the library manages a hidden sibling of the upper.

Trait Implementations

impl Clone for Overlay

fn clone(&self) -> Overlay

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Overlay

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Overlay

fn default() -> Overlay

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Overlay

where Overlay: Default,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for Overlay

impl PartialEq for Overlay

fn eq(&self, other: &Overlay) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Overlay

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Overlay