Struct jail::RunningJail

pub struct RunningJail {
    pub jid: i32,
}

Represents a running jail.

Fields

jid: i32

The jid of the jail

Implementations

impl RunningJail

Represent a running jail.

pub fn from_jid(jid: i32) -> Option<RunningJail>

Create a RunningJail instance given a jid.

Returns an [Option] containing a [RunningJail] if a Jail with the given jid exists, or None.

Examples

use jail::RunningJail;

let running = RunningJail::from_jid(jid)
    .expect("No Jail with this JID");

When given the JID of a non-existent jail, it should panic.

use jail::RunningJail;

let running = RunningJail::from_jid(99999)
    .expect("No Jail with this JID");

pub fn from_jid_unchecked(jid: i32) -> RunningJail

Create a RunningJail instance given a jid.

No checks will be performed. If jid is invalid, most method calls will fail.

Examples

use jail::RunningJail;

let running = RunningJail::from_jid_unchecked(jid);

pub fn from_name(name: &str) -> Result<RunningJail, JailError>

Create a RunningJail given the jail name.

The jid will be internally resolved using jail_getid.

Examples

use jail::RunningJail;

let running = RunningJail::from_name("testjail_from_name")
    .expect("Could not get testjail");

pub fn name(self: &RunningJail) -> Result<String, JailError>

Return the jail's name.

Examples

assert_eq!(running.name().unwrap(), "testjail_name");

pub fn path(self: &RunningJail) -> Result<PathBuf, JailError>

Return the jail's path.

Examples

let path = running.path()
    .expect("Could not get path");

pub fn hostname(self: &RunningJail) -> Result<String, JailError>

Return the jail's name.

The name will be internall resolved using jail_getname.

Examples

assert_eq!(running.hostname().unwrap(), "testjail.example.com");

pub fn ips(self: &RunningJail) -> Result<Vec<IpAddr>, JailError>

Get the IP addresses

Examples

let ips = running.ips()
    .expect("could not get ip addresses");
assert_eq!(ips[0], "127.0.1.2".parse::<IpAddr>().unwrap());
assert_eq!(ips[1], "fe80::2".parse::<IpAddr>().unwrap());

pub fn param(&self, name: &str) -> Result<Value, JailError>

Return a jail parameter.

Examples

let hostuuid = running.param("host.hostuuid")
    .expect("could not get jail hostuuid");

pub fn params(&self) -> Result<HashMap<String, Value>, JailError>

Return a HashMap of all jail parameters.

Examples

use jail::param;

let params = running.params()
    .expect("could not get all parameters");

assert_eq!(
    params.get("allow.raw_sockets"),
    Some(&param::Value::Int(1))
);

pub fn param_set(&self, name: &str, value: Value) -> Result<(), JailError>

Set a jail parameter.

Examples

use jail::param;
running.param_set("allow.raw_sockets", param::Value::Int(1))
    .expect("could not set parameter");

pub fn kill(self: RunningJail) -> Result<(), JailError>

Kill a running jail, consuming it.

This will kill all processes belonging to the jail, and remove any children of that jail.

Examples

running.kill();

pub fn save(self: &RunningJail) -> Result<StoppedJail, JailError>

Create a StoppedJail from a RunningJail, while not consuming the RunningJail.

This can be used to clone the config from a RunningJail.

If RCTL is enabled, then all RCTL rules matching the RunningJail subject will be saved.

Examples

let stopped = running
    .save()
    .expect("could not save jail configuration");

assert_eq!(stopped.name, Some("testjail_save".into()));
assert_eq!(stopped.hostname, Some("testjail_save.example.com".into()));

pub fn stop(self: RunningJail) -> Result<StoppedJail, JailError>

Stop a jail, keeping its configuration in a StoppedJail.

This is a wrapper around save and kill.

Examples

let stopped = running
    .stop()
    .expect("failed to stop jail");

//assert_eq!(stopped.name, Some("testjail_save".into()));
//assert_eq!(stopped.hostname, Some("testjail_save.example.com".into()));

pub fn restart(self: RunningJail) -> Result<RunningJail, JailError>

Restart a jail by stopping it and starting it again

This is a wrapper around RunningJail::stop and StoppedJail::start

Examples

let old_jid = running.jid;
let running = running.restart()
    .expect("failed to restart jail");
assert!(running.jid != old_jid);

pub fn all() -> RunningJails

Returns an Iterator over all running jails on this host.

Examples

use jail::RunningJail;

for running in RunningJail::all() {
    println!("jail: {}", running.name().unwrap());
}

pub fn racct_statistics(&self) -> Result<HashMap<Resource, usize>, JailError>

Get the RCTL / RACCT usage statistics for this jail.

Example

match running.racct_statistics() {
    Ok(stats) => println!("{:#?}", stats),
    Err(e) => println!("Error: {}", e),
};

pub fn attach(&self) -> Result<(), JailError>

Jail the current process into the given jail.

pub fn defer_cleanup(&self) -> Result<(), JailError>

Clear the persist flag on the Jail.

The kernel keeps track of jails using a per-jail resource counter. Every running process inside the jail increments this resource counter. The persist flag additionally increments the resource counter so that the jail will not be removed once all processes within the jail will have terminated.

Jails started with [StoppedJail::start] start with this flag set, since they would otherwise be immediately cleaned up again by the kernel. This method clears the persist flag and therefore delegates cleanup to the kernel once all jailed processes have terminated.

Example

use std::process::Command;
use jail::process::Jailed;

let jail = jail::StoppedJail::new("/rescue")
     .name("testjail_defer_cleanup")
     .start()
     .expect("could not start jail");

let mut child = Command::new("/sleep")
             .arg("3")
             .jail(&jail)
             .spawn()
             .expect("Failed to execute command");

jail.defer_cleanup().expect("could not defer cleanup");

child.wait().expect("Could not wait for child.");

jail.kill().expect_err("Jail should be dead by now.");

Trait Implementations

impl Clone for RunningJail

fn clone(&self) -> RunningJail

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Copy for RunningJail

impl Debug for RunningJail

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

Formats the value using the given formatter.

impl Eq for RunningJail

impl From<RunningJail> for Jail

fn from(running: RunningJail) -> Self

Performs the conversion.

impl Hash for RunningJail

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl Ord for RunningJail

fn cmp(&self, other: &RunningJail) -> Ordering

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

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

Restrict a value to a certain interval.

impl PartialEq<RunningJail> for RunningJail

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl PartialOrd<RunningJail> for RunningJail

fn partial_cmp(&self, other: &RunningJail) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &RunningJail) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &RunningJail) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &RunningJail) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &RunningJail) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralEq for RunningJail

impl StructuralPartialEq for RunningJail

impl TryFrom<RunningJail> for StoppedJail

type Error = JailError

The type returned in the event of a conversion error.

fn try_from(running: RunningJail) -> Result<StoppedJail, Self::Error>

Performs the conversion.

impl TryFrom<StoppedJail> for RunningJail

type Error = JailError

The type returned in the event of a conversion error.

fn try_from(stopped: StoppedJail) -> Result<RunningJail, Self::Error>

Performs the conversion.