beach 0.2.1

Sandboxing utilities for Ocean.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

use std::{
    ffi::{OsStr, OsString},
    path::Path,
    process::Command,
};

/// A wrapper for [`chroot(1)`](https://www.gnu.org/software/coreutils/chroot).
///
/// **Note:** Running `chroot` requires root privileges.
///
/// # Examples
///
/// ```
/// # return;
/// beach::Chroot::new()
///     .user_group("nvzqz", "everyone")
///     .command("/path/to/root", "ls")
///     .arg("/")
///     .spawn();
/// ```
#[derive(Clone, Debug)]
pub struct Chroot {
    skip_chdir: bool,
    user_spec: Option<OsString>,
    groups: Option<OsString>,
}

impl Default for Chroot {
    #[inline]
    fn default() -> Self {
        Self::new()
    }
}

impl Chroot {
    /// Creates an instance suitable for setting up a `Command` to execute a
    /// program through `chroot`.
    #[inline]
    pub const fn new() -> Self {
        Self {
            skip_chdir: false,
            user_spec: None,
            groups: None,
        }
    }

    /// Do not change the working directory to `/`.
    #[inline]
    pub fn skip_chdir(mut self) -> Self {
        self.skip_chdir = true;
        self
    }

    /// Specify the user to use.
    pub fn user<U>(mut self, user: U) -> Self
    where
        U: AsRef<OsStr>,
    {
        let mut user_spec = OsString::from("--userspec=");
        user_spec.push(user);
        self.user_spec = Some(user_spec);
        self
    }

    /// Specify the user and group (ID or name) to use.
    pub fn user_group<U, G>(mut self, user: U, group: G) -> Self
    where
        U: AsRef<OsStr>,
        G: AsRef<OsStr>,
    {
        let mut user_spec = OsString::from("--userspec=");
        user_spec.push(user);
        user_spec.push(":");
        user_spec.push(group);
        self.user_spec = Some(user_spec);
        self
    }

    /// Specifies supplementary groups.
    pub fn groups<G>(mut self, groups: G) -> Self
    where
        G: IntoIterator,
        G::Item: AsRef<OsStr>,
    {
        let mut groups = groups.into_iter();

        if let Some(group) = groups.next() {
            // Only add the `groups` argument if the iterator is non-empty.
            let mut arg = OsString::from("--groups=");
            arg.push(group);

            // Add remaining groups as a comma-separated list.
            for group in groups {
                arg.push(",");
                arg.push(group);
            }

            self.groups = Some(arg);
        }

        self
    }

    // Monomorphized form of `command` to reduce binary size.
    fn command_impl(&self, root: &OsStr, program: &OsStr) -> Command {
        let mut command = Command::new("chroot");

        if self.skip_chdir {
            command.arg("--skip-chdir");
        }

        if let Some(user_spec) = &self.user_spec {
            command.arg(user_spec);
        }

        if let Some(groups) = &self.groups {
            command.arg(groups);
        }

        command.arg(root);
        command.arg(program);

        command
    }

    /// Returns a `Command` suitable for spawning `program` with `root` as `/`.
    #[inline]
    pub fn command<R, P>(&self, root: R, program: P) -> Command
    where
        R: AsRef<Path>,
        P: AsRef<OsStr>,
    {
        self.command_impl(root.as_ref().as_os_str(), program.as_ref())
    }
}