Enum Error 

#[non_exhaustive]
pub enum Error {
    Config(ConfigError),
    #[non_exhaustive]
    UsernsUnavailable {
        blocker: Option<UsernsBlocker>,
        source: Error,
    },
    NestedUsernsBudgetExhausted,
    #[non_exhaustive]
    Setup {
        step: SetupStep,
        source: Error,
        detail: Option<String>,
    },
    #[non_exhaustive]
    Spawn {
        source: Error,
    },
    #[non_exhaustive]
    Wait {
        source: Error,
    },
    SupervisorLost,
    #[non_exhaustive]
    Signal {
        source: Error,
    },
    IdentityMap(IdMapError),
    #[non_exhaustive]
    Terminal {
        source: Error,
    },
    TerminalsExhausted,
}

An error from the library itself.

Cage::run returns Err only when the library fails: invalid configuration, an unsupported host, a failed setup step, or a failure to spawn or wait. The sandboxed command’s own exit code is data, carried by ExitStatus, and is never an Error.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Config(ConfigError)

The sandbox configuration was rejected at build time.

#[non_exhaustive]

UsernsUnavailable

The host cannot create unprivileged user namespaces.

Produced when namespace creation is denied by the kernel. When the probe in crate::host identifies the mechanism responsible, it is carried in blocker.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

blocker: Option<UsernsBlocker>

The host configuration identified as blocking user namespaces, when one could be determined.

source: Error

The error the kernel returned for namespace creation.

NestedUsernsBudgetExhausted

The host’s user-namespace budget is exhausted, so the command could not enter the nested user namespace that locks the sandbox’s mount flags.

A user namespace is charged against user.max_user_namespaces at every level up to the initial namespace, and a launch holds two: the sandbox’s own, and the nested one the command enters. A host whose ceiling admits the first and not the second reports this rather than a bare ENOSPC.

Distinct from UsernsUnavailable, which is a host that permits no user namespace at all: here the sandbox was built and only the second namespace was refused.

#[non_exhaustive]

Setup

A sandbox setup step failed in the child process.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

step: SetupStep

The step that failed.

source: Error

The error the step failed with.

detail: Option<String>

What the step was operating on, when the step has a subject — for a mount step, the mount it was assembling; for Exec, the command path, and for a command resolved by path lookup, the candidates the search tried.

An ENOENT from the exec step means either that the command itself is absent or that its ELF interpreter is: a dynamically linked binary whose loader is missing from the rootfs reports the same errno as a missing binary. The detail names the command, not the interpreter, so a path that plainly exists inside the rootfs points at the second reading.

#[non_exhaustive]

Spawn

The sandbox process could not be created.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

source: Error

The error from pipe creation or fork.

#[non_exhaustive]

Wait

The sandbox process outcome could not be collected.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

source: Error

The error from collecting the outcome: reading the setup-error, status, or capture pipes, waiting on them, or the wait itself.

SupervisorLost

The sandbox supervisor exited without reporting the command’s outcome.

The supervisor always reports the command’s wait status before it exits; its silent disappearance means it was killed from outside or exited abnormally, and the command’s outcome is unknown. A kill requested through the handle is not this error: after Running::kill, the outcome is reported as termination by SIGKILL.

#[non_exhaustive]

Signal

The sandbox could not be signaled through the handle.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

source: Error

The error from the signaling machinery.

IdentityMap(IdMapError)

The identity-map delegate failed to establish the range map.

The delegate runs caller-side against the gated launch, so its own error is the diagnostic; the gated sandbox is torn down.

#[non_exhaustive]

Terminal

A pseudoterminal operation failed: allocating one for the sandbox, or reading or setting its window size.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

source: Error

The error the operation failed with.

TerminalsExhausted

The host has no free pseudoterminal to allocate.

Pseudoterminals are a bounded resource — /proc/sys/kernel/pty/max states the ceiling — so a host running many sandboxes at once can exhaust them. Distinct from Terminal because it is the one allocation failure that says nothing is wrong with the request: the same launch succeeds once something releases a terminal.

Implementations

impl Error

pub fn shell_code(&self) -> u8

The exit code a launcher reports when a launch fails, following the conventions sh and timeout(1) established.

A caller whose whole purpose is to run one command inside a sandbox is a launcher, and a launcher’s own failures have to be distinguishable from the command’s exit codes. The conventions are:

Code	Meaning
127	The command does not exist.
126	The command exists but could not be executed.
125	The launcher itself failed, for any other reason.

The distinction between 127 and 126 comes from the errno the Exec step failed with. An ENOENT there has two readings — the command is absent, or its ELF interpreter is — and both are reported as 127, since neither produced a runnable process.

This is what the fcage binary returns. A caller with its own convention is free to map Error itself; this is the answer for one that has none, and the one that makes a consumer behave like a shell.

124, timeout(1)’s “the deadline expired”, is not produced here: an expired deadline is not an Error, it is a Running::wait_timeout that returned no status, so only the caller knows it happened.

Example

use std::process::ExitCode;

use ferroday_cage::Cage;

fn launch(rootfs: &str) -> ExitCode {
    match Cage::builder().command("/bin/true").rootfs(rootfs).build() {
        Ok(_cage) => ExitCode::SUCCESS,
        Err(error) => {
            eprintln!("myapp: {error}");
            ExitCode::from(error.shell_code())
        }
    }
}

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

The failure underneath, where there is one.

Every OS failure this type carries is an io::Error, so every one of them is returned here. The variants that answer None carry nothing: NestedUsernsBudgetExhausted, SupervisorLost, and TerminalsExhausted are conditions the library recognized rather than syscalls that failed.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<ConfigError> for Error

fn from(err: ConfigError) -> Self

Converts to this type from the input type.

impl From<Error> for DebianError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for RelayError

fn from(error: Error) -> RelayError

Converts to this type from the input type.