Struct Restriction 

#[non_exhaustive]
pub struct Restriction { /* private fields */ }

A validated, ready-to-run restriction.

Constructed by Restriction::builder; all validation, the seccomp compilation, and the Landlock lowering happen in RestrictionBuilder::build, which freezes the configuration into a launch plan. run then executes the command under the restriction and blocks until it terminates.

Example

Run a command that may read the system trees and a work directory, and nothing else on the filesystem:

use ferroday_cage::{FsAccess, Restriction};

let status = Restriction::builder()
    .command("/usr/bin/sort")
    .args(["/work/input"])
    .landlock_fs(FsAccess::READ | FsAccess::EXECUTE, "/usr")
    .landlock_fs(FsAccess::READ | FsAccess::EXECUTE, "/lib")
    .landlock_fs(FsAccess::READ, "/etc")
    .landlock_fs(FsAccess::READ | FsAccess::WRITE, "/work")
    .build()?
    .run()?;
assert!(status.success());

A Restriction holds no live resources — it is a frozen plan — so it is Clone and every launch method takes &self, exactly as Cage is. One restriction can launch the same command any number of times, concurrently or in sequence.

Implementations

impl Restriction

pub fn resolved_inputs(&self) -> ResolvedInputs

The environment this restriction will actually apply.

The counterpart of Cage::resolved_inputs. Its mount list is always empty: a restriction confines a process in place rather than building a filesystem for it.

pub fn builder() -> RestrictionBuilder

Returns a builder for configuring a restriction.

pub fn run(&self) -> Result<ExitStatus, Error>

Runs the command under the restriction and blocks until it terminates.

Returns Ok with the command’s ExitStatus whenever the command was executed, regardless of its exit code. Err is reserved for the library failing: spawning the process, a setup step (a Landlock rule that cannot apply, a rejected filter), or collecting the outcome.

The command runs with the stream dispositions the restriction carries, which are inherited unless the builder said otherwise.

pub fn run_with(&self, observer: &mut dyn Observer) -> Result<ExitStatus, Error>

Runs the command under the restriction, streaming its output to the observer, and blocks until it terminates.

Like run, but the command’s standard output and standard error are captured and delivered to observer as they are produced, on the calling thread.

pub fn output(&self) -> Result<Output, Error>

Runs the command under the restriction and returns its exit status together with everything it wrote.

The restriction’s counterpart of Cage::output, with the same unbounded-capture caution: for a command whose output volume the caller does not control, stream through an Observer that caps what it keeps instead.

pub fn spawn(&self) -> Result<Running<'static>, Error>

Starts the command under the restriction and returns a handle to it.

spawn blocks until the restriction is applied and the command is executing, so a setup failure is reported here, as the same typed error run would return. The command runs with the stream dispositions the restriction carries; the returned Running waits for, signals, or kills it.

pub fn spawn_with<'obs>( &self, observer: &'obs mut dyn Observer, ) -> Result<Running<'obs>, Error>

Starts the command under the restriction, capturing its output for the observer, and returns a handle to it.

Like spawn, but the command’s standard output and standard error are captured into pipes. The captured bytes are delivered to observer while the returned handle is waited on; see Observer.

pub fn spawn_terminal( &self, terminal: &Terminal, ) -> Result<(Running<'static>, Pty), Error>

Starts the command on a pseudoterminal of its own, returning a handle to it and the caller’s end of the terminal.

The counterpart of Cage::spawn_terminal, and the fallback supports it in full: a host-allocated pseudoterminal needs no devpts instance, so a restriction gets the same interactive story a cage does. The command process is the session leader here, since a restriction has no PID namespace and so no init above it.

Trait Implementations

impl Clone for Restriction

fn clone(&self) -> Restriction

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Restriction

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

Formats the value using the given formatter.