Enum ConfigError 

#[non_exhaustive]
pub enum ConfigError {
    RootfsMissing,
    RootContradiction,
    #[non_exhaustive]
    RootfsUnusable {
        path: PathBuf,
        source: Error,
    },
    RootfsIsHostRoot,
    CommandMissing,
    #[non_exhaustive]
    CommandNotAbsolute {
        command: PathBuf,
    },
    #[non_exhaustive]
    ManagedMountsContradiction {
        toggle: &'static str,
    },
    #[non_exhaustive]
    SearchPathUnusable {
        path: OsString,
    },
    #[non_exhaustive]
    BindSourceUnusable {
        path: PathBuf,
        source: Error,
    },
    #[non_exhaustive]
    MountTargetInvalid {
        path: PathBuf,
    },
    #[non_exhaustive]
    MountFlagsInvalid {
        flags: u64,
    },
    #[non_exhaustive]
    WorkdirNotAbsolute {
        path: PathBuf,
    },
    HostnameInvalid,
    #[non_exhaustive]
    EnvNameInvalid {
        name: OsString,
    },
    EmbeddedNul,
    #[non_exhaustive]
    SeccompInvalid {
        reason: String,
    },
    #[non_exhaustive]
    SeccompUnsupportedArch {
        arch: String,
    },
    #[non_exhaustive]
    SeccompProgramTooLong {
        len: usize,
        max: usize,
    },
    #[non_exhaustive]
    LandlockPathInvalid {
        path: PathBuf,
    },
    #[non_exhaustive]
    LandlockGrantEmpty {
        grant: String,
    },
    RestrictionEmpty,
    #[non_exhaustive]
    RestrictionLandlockUnenforceable {
        abi: Option<i32>,
    },
    #[non_exhaustive]
    HostNetworkLandlockUnenforceable {
        abi: Option<i32>,
    },
    #[non_exhaustive]
    ProfileOperationForbidden {
        operation: &'static str,
    },
    #[non_exhaustive]
    StreamAttachmentConflict {
        stream: &'static str,
        attachment: &'static str,
    },
    #[non_exhaustive]
    IdentityMapInvalid {
        reason: String,
    },
    #[non_exhaustive]
    IdentityMapUnavailable {
        reason: String,
    },
    #[non_exhaustive]
    RunAsUnmapped {
        id: u32,
        space: &'static str,
    },
    RunAsGroupsWithSingleMap,
    NestedUsernsNeedsProcfs,
    #[non_exhaustive]
    SetidCapWithNonRootIdentity {
        capability: &'static str,
    },
    #[non_exhaustive]
    OverlayPathInvalid {
        path: PathBuf,
    },
    OverlayLowerMissing,
    OverlayUpperMissing,
    #[non_exhaustive]
    OverlayDirUnusable {
        layer: OverlayLayer,
        path: PathBuf,
        source: Error,
    },
    #[non_exhaustive]
    OverlayDirUnowned {
        layer: OverlayLayer,
        path: PathBuf,
    },
    #[non_exhaustive]
    OverlayUpperIsRoot {
        path: PathBuf,
    },
    #[non_exhaustive]
    OverlayUnavailable {
        blocker: OverlayBlocker,
    },
    #[non_exhaustive]
    RlimitInvalid {
        resource: Resource,
        soft: Limit,
        hard: Limit,
    },
}

A sandbox configuration rejected by CageBuilder::build.

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.

RootfsMissing

No rootfs was provided.

RootContradiction

A plain rootfs and an overlay root were both configured, where exactly one root can be in force.

The builder’s setters keep the two exclusive — rootfs clears an overlay and overlay clears a rootfs — so this arises from a profile that carries both keys. Honoring either one silently would discard the other’s configuration.

#[non_exhaustive]

RootfsUnusable

The rootfs path could not be resolved and opened as a directory.

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.

path: PathBuf

The rootfs path as it was given to the builder.

source: Error

The error encountered while resolving or opening it.

RootfsIsHostRoot

The rootfs resolves to the host root directory.

CommandMissing

No command was provided, or the path given names nothing.

An empty path is the second: it is not a command that could not be found, it is the absence of one written down. Every later check reads it as something else — it carries no slash, so a path lookup takes it for a bare name and joining it onto a PATH entry yields that entry — so it is refused where the command is read rather than deferred to an execve of a directory.

#[non_exhaustive]

CommandNotAbsolute

The command path is not absolute.

The message names the remedy that fits: a bare command name — the most common form of this mistake — is resolvable with path_lookup, while a relative path containing a slash is never searched and must be made absolute.

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.

command: PathBuf

The command path as it was given to the builder.

#[non_exhaustive]

ManagedMountsContradiction

The managed mount profile was opted out of, while one of its mounts was explicitly asked for. The two cannot both be honored.

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.

toggle: &'static str

The builder method naming the mount that was explicitly requested.

#[non_exhaustive]

SearchPathUnusable

Path lookup was requested, but the PATH in force holds no absolute directory to search, so the command could not resolve to any candidate.

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.

path: OsString

The PATH the lookup would have searched.

#[non_exhaustive]

BindSourceUnusable

A bind-mount source could not be resolved on the host.

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.

path: PathBuf

The source path as it was given to the builder.

source: Error

The error encountered while resolving it.

#[non_exhaustive]

MountTargetInvalid

A mount target is not a normal absolute path inside the rootfs.

A bind or raw-mount target must be absolute, must not be / itself, and must not contain . or .. components.

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.

path: PathBuf

The target path as it was given to the builder.

#[non_exhaustive]

MountFlagsInvalid

A raw mount’s flags do not fit the kernel’s mount-flags word.

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.

flags: u64

The flags as they were given to the builder.

#[non_exhaustive]

WorkdirNotAbsolute

The working directory path is not absolute.

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.

path: PathBuf

The working directory as it was given to the builder.

HostnameInvalid

The hostname is empty or longer than 64 bytes.

#[non_exhaustive]

EnvNameInvalid

An environment variable name is empty or contains =.

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.

name: OsString

The offending variable name.

EmbeddedNul

A configured path, name, or value contains an interior NUL byte.

#[non_exhaustive]

SeccompInvalid

A seccomp policy could not be compiled into a BPF program.

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.

reason: String

What the compiler reported.

#[non_exhaustive]

SeccompUnsupportedArch

Seccomp filtering is not available for the host architecture.

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.

arch: String

The host architecture, as std::env::consts::ARCH reports it.

#[non_exhaustive]

SeccompProgramTooLong

A seccomp program is longer than the kernel’s instruction ceiling.

The kernel accepts a classic BPF filter of at most BPF_MAXINSNS (4096) instructions. A precompiled SeccompPolicy::Program escape hatch that exceeds it is rejected here rather than being silently truncated when the filter is installed.

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.

len: usize

The program’s instruction count.

max: usize

The kernel’s maximum instruction count.

#[non_exhaustive]

LandlockPathInvalid

A Landlock grant path is not a normal absolute path.

A grant path must be absolute and must not contain . or .. components. In a cage it is a sandbox path, resolved after the pivot; in a restriction it is a host path.

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.

path: PathBuf

The grant path as it was given to the builder.

#[non_exhaustive]

LandlockGrantEmpty

A Landlock grant names no access at all.

An empty access set is not “grant nothing here”: enrolling any grant denies everything ungranted, and the kernel skips a rule that permits nothing — so an empty grant is a total denial of the class it belongs to. That is never what an author means by naming a path or a port, so it is refused rather than silently applied.

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.

grant: String

The grant as it was written: the path of a filesystem grant, or tcp:<port> for a network grant.

RestrictionEmpty

A restriction names no Landlock grant and no seccomp policy.

A restriction exists to confine the command; with nothing to enforce it would launch a plain process while appearing to sandbox it, so an empty restriction is rejected instead.

#[non_exhaustive]

RestrictionLandlockUnenforceable

A restriction’s Landlock grants cannot be enforced on this host.

A restriction is confined only by what the running kernel enforces. When its Landlock grants all fall outside the supported Landlock ABI — a network grant on a kernel below ABI 4 — or the Landlock LSM is absent, no ruleset applies and the command would run unconfined, so the build is refused rather than silently dropping the requested confinement. A cage in the same case keeps its namespace isolation, so this is specific to the restriction fallback.

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.

abi: Option<i32>

The kernel’s supported Landlock ABI, or None when the LSM is absent.

#[non_exhaustive]

HostNetworkLandlockUnenforceable

A host-network cage requests a Landlock network grant the kernel cannot enforce.

Under Network::Host there is no network namespace, so a Landlock network grant is the only network boundary. When the kernel’s Landlock ABI is below 4 (network rights first appear there) or the LSM is absent, the grant governs nothing and the command would reach the host network unrestricted, so the build is refused. A Isolated or None cage is unaffected: its network namespace remains the boundary.

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.

abi: Option<i32>

The kernel’s supported Landlock ABI, or None when the LSM is absent.

#[non_exhaustive]

ProfileOperationForbidden

A profile loaded under the restricted policy uses an operation only a trusted profile may.

Deserializing a profile straight into a CageBuilder trusts it as code-equivalent configuration. A profile from an untrusted source is loaded under the restricted policy instead, which forbids the operations that map host resources into the sandbox or share a host namespace: bind mounts, raw mounts, an overlay root, host networking, and sharing the host PID namespace.

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.

operation: &'static str

The forbidden operation, as a short phrase.

#[non_exhaustive]

StreamAttachmentConflict

A launch attaches a conduit to a standard stream the sandbox was built to send somewhere else.

Stdio::Inherit states no destination, so a launch is free to supply one and this never arises against it. Stdio::Null and Stdio::from_fd state one, and a launch that would supply its own is refused rather than silently overriding what the caller said. Two launches supply one: an Observer’s capture pipes, on the output pair, and a terminal launch’s pseudoterminal replica, on all three at once.

Reported by the launch rather than by build: the contradiction is between the frozen sandbox and one particular launch of it, and the same sandbox launches without contradiction through an entry point that attaches nothing.

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.

stream: &'static str

The stream whose disposition the attachment contradicts, as a short phrase — "standard input", "standard output", or "standard error".

attachment: &'static str

What the launch attaches to it, as a short phrase.

#[non_exhaustive]

IdentityMapInvalid

An identity map’s ranges are structurally invalid.

The kernel’s rules are enforced here so an unwritable map is a typed configuration error: both lists non-empty, inside-id 0 mapped, no zero-count or wrapping extents, no overlaps, and at most 340 extents.

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.

reason: String

What makes the map unwritable.

#[non_exhaustive]

IdentityMapUnavailable

No identity-map delegate can satisfy the requested range map.

The fallback is between delegates, never between tiers: a range request that no delegate can establish is refused rather than silently downgraded to the single-identity map. The reason carries each delegate’s refusal, and the host probe’s diagnosis when host::range_map_blocker identifies one.

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.

reason: String

Why each delegate refused, and any identified host blocker.

#[non_exhaustive]

RunAsUnmapped

A run-as id is not contained in the identity map.

Every id the command runs as must be representable in the sandbox’s user namespace. Under the single-identity map the only id is 0; a range map contains what its extents say.

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.

id: u32

The unmapped id.

space: &'static str

Which id it is: "uid", "gid", or "supplementary group".

RunAsGroupsWithSingleMap

A run-as identity names supplementary groups under the single-identity map.

Establishing that map requires denying setgroups, so no group list can ever be set inside it. Supplementary groups need a range gid map.

NestedUsernsNeedsProcfs

The profile mounts no procfs the nested user namespace’s identity map can be established through.

Every container enters a nested user namespace before it hardens, which is what locks the flags of the mounts it inherited — without it the command is root of the namespace those mounts belong to and may lift any restriction they carry. Establishing that namespace’s map reaches for a procfs by path from inside the sandbox, so a sandbox with no procfs has no way to establish one.

Reachable only from a profile that opts out of the managed mounts with managed_mounts(false) (or mount_proc(false)) and mounts no procfs of its own, and then only where the map’s route reads one. The single-identity map’s command writes its own map files, and a bind of the host’s procfs serves it — every instance resolves self for its reader. A range identity_map is written by a delegate, and where the sandbox has a PID namespace that delegate is inside it and needs a fresh procfs, since it names the command by an in-namespace pid a bound procfs does not index. Where the sandbox has no PID namespace the delegate is outside it and reads the host’s own /proc, so no procfs is required at all.

#[non_exhaustive]

SetidCapWithNonRootIdentity

A retained set-id capability alongside a non-root run-as identity.

The securebits that preserve kept capabilities across the identity switch also mean a command holding CAP_SETUID, CAP_SETGID, or CAP_SETPCAP could return to the mapped uid 0, making the non-root identity no boundary at all. The combination is rejected by name rather than shipped as a claim the configuration does not keep.

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.

capability: &'static str

The offending capability.

#[non_exhaustive]

OverlayPathInvalid

An overlay-root path holds a character the overlay mount options cannot carry.

The lower, upper, and work directories are passed to the kernel as a comma-separated, colon-delimited option string, so a , or : in any of their resolved paths would be misparsed. Such a path is refused rather than silently truncated.

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.

path: PathBuf

The offending path.

OverlayLowerMissing

An overlay root names no lower layer.

The first lower is the base the overlay mounts over — the sandbox’s root filesystem — so an overlay carrying only an upper has nothing to merge; Overlay::lower is required.

OverlayUpperMissing

An overlay root names no upper layer.

An overlay with only lowers is a read-only merge; the sandbox needs somewhere for its writes to land, so Overlay::upper is required.

#[non_exhaustive]

OverlayDirUnusable

An overlay layer directory could not be prepared.

Every layer is canonicalized, since the mount options name the layers absolutely; the upper and work directories are additionally created when absent, while a stacked lower must already exist. This reports a host failure at either step: a path that does not resolve, a permission refusal, or a path that resolves to something other than a usable directory.

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.

layer: OverlayLayer

Which layer directory failed.

path: PathBuf

The directory that could not be prepared.

source: Error

The error the preparation failed with.

#[non_exhaustive]

OverlayDirUnowned

An overlay layer directory the library would have created was already there, and is not a directory the calling user owns.

The upper and work directories are created if absent, and the caller may name them under a directory it shares with other local users. An entry already at the path is adopted only when it is a directory belonging to the calling user: a symbolic link — which would send every write the sandbox makes to a destination of whoever planted it, and hand that destination back to the caller as the layer its run produced — or a directory owned by someone else is refused instead of used.

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.

layer: OverlayLayer

Which layer directory was refused.

path: PathBuf

The path that was already occupied.

#[non_exhaustive]

OverlayUpperIsRoot

An overlay’s upper layer is the filesystem root.

The upper needs a parent directory: the work directory the library derives is a sibling of the upper, and the host overlay preflight runs in that parent so its scratch entries land beside the upper rather than inside it. / has no parent — and an upper there would put the sandbox’s writes over the whole host root.

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.

path: PathBuf

The offending path.

#[non_exhaustive]

OverlayUnavailable

An overlay-rooted cage was requested on a host that cannot establish an unprivileged overlay mount.

The overlay preflight names what is missing: the running kernel may predate unprivileged overlay-in-a-user-namespace (Linux 5.11), or the upper layer’s filesystem may not support the user.* extended-attribute namespace an unprivileged overlay records its metadata in — which tmpfs gained only in Linux 6.6, so an on-disk upper (ext4, xfs, btrfs) is the portable choice.

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: OverlayBlocker

The host blocker the overlay preflight identified.

#[non_exhaustive]

RlimitInvalid

A resource limit names a soft value above its hard value.

The kernel refuses such a pair with EINVAL; it is caught here so the mistake is a typed configuration error rather than a launch failure.

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.

resource: Resource

The resource the limit governs.

soft: Limit

The soft limit as it was given.

hard: Limit

The hard limit as it was given.

Trait Implementations

impl Debug for ConfigError

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

Formats the value using the given formatter.

impl Display for ConfigError

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

Formats the value using the given formatter.

impl Error for ConfigError

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

The OS failure underneath, for the three refusals that have one.

Every other variant is a request the builder refused on its own terms — a contradiction, a missing field, a path that is not the shape it has to be — where nothing failed and there is nothing to return.

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.