Struct CopyIn 

pub struct CopyIn<'a> { /* private fields */ }

Copies a host directory tree into a rootfs, with each entry created under the identity map the rootfs is owned through.

The mirror image of Export. An export forks a child into the map to read a tree at the ownership it intends; this forks one to write one.

The mirroring is of the mechanism, not of the entry types. An export describes a rootfs the cage built, for a runtime that will supply its own device nodes and pipes; a copy lays down a tree the caller wrote by hand, where every entry is there because someone put it there. So the copy creates everything it can create — a named pipe included — and names the rest. A source entry’s host ownership is read back through the map to the id it means inside the rootfs. So a tree an earlier mapped sandbox produced copies in owned as it was written, and a tree the caller staged as themselves lands as whatever id the map gives the calling user — root, under a Single map.

That is the thing a plain cp structurally cannot do. cp runs as the calling user, which can create a file owned by nobody else, so a tree laid into a rootfs by hand arrives owned by the caller’s own host id, whatever the source intended — an id a range-mapped rootfs has no name for at all.

The destination must already exist. Entries are added to it: a directory the rootfs already carries is kept and descended into, and a file, symlink, or named pipe is replaced.

Directories, regular files, symbolic links, and named pipes are copied. Several names for one file are copied as hard links, so a tree keeps the sharing it was written with. Character and block devices and sockets cannot be copied and are named in the CopyReport the run returns; see SkippedKind for why each is left out.

Example

use ferroday_cage::IdentityMap;
use ferroday_cage::provision::CopyIn;

let report = CopyIn::new("./overlay", "/srv/images/trixie")
    .map(IdentityMap::Subordinate)
    .run()?;

for entry in &report.skipped {
    eprintln!("not copied: {} ({})", entry.path.display(), entry.kind);
}

Implementations

impl<'a> CopyIn<'a>

pub fn new(source: impl AsRef<Path>, rootfs: impl AsRef<Path>) -> CopyIn<'a>

Returns a copy of the tree at source into the rootfs at rootfs.

The identity map defaults to IdentityMap::Single, under which the in-map child writes its own one-id map and every entry lands as root — what a single-mapped sandbox sees, and what such a sandbox could have written itself.

pub fn map(self, map: IdentityMap) -> CopyIn<'a>

Sets the identity map the rootfs is owned through.

It must be the map the rootfs was built under, for the reason an export must name the same one: the ids on the host are the rootfs’s ids offset by the map, so a copy made through a different map writes ownership the rootfs will not read back as intended.

pub fn mapper(self, mapper: &'a dyn IdMapper) -> CopyIn<'a>

Copies through a caller-supplied identity-map delegate, for a rootfs built under CageBuilder::id_mapper.

Without one, the copy resolves the bundled delegate chain, which covers a Subordinate rootfs and a bundled-delegate Ranges one. A Single map self-establishes and ignores the mapper, as the launch does.

pub fn run(self) -> Result<CopyReport, ProvisionError>

Performs the copy, reporting what it could not copy.

Errors

ProvisionError::CopyUnprivileged when the rootfs needs a range map and no delegate can establish one; ProvisionError::EntryRefused for a source entry the copy cannot carry — a tree deeper than the walk descends, a name or a link target longer than a frame holds, or an ownership the rootfs’s identity map has no id for; ProvisionError::SourceChanged for a file that changed size while it was being read; and ProvisionError::Io for a failure of the copy machinery, of the walk, or of the in-map writer.

Trait Implementations

impl Debug for CopyIn<'_>

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

Renders every setting, and the mapper by its presence rather than its contents: it is a caller’s trait object, with nothing useful to show.