pub struct Sandbox { /* private fields */ }Expand description
A configured OS-level sandbox for one workspace.
Cheap to clone, safe to share: host layout is resolved at construction and
Sandbox::argv only assembles vectors.
Implementations§
Source§impl Sandbox
impl Sandbox
Sourcepub fn new(
backend: SandboxBackend,
workspace: &Path,
options: SandboxOptions,
) -> Result<Self, String>
pub fn new( backend: SandboxBackend, workspace: &Path, options: SandboxOptions, ) -> Result<Self, String>
Build a sandbox for workspace using backend.
The workspace is canonicalized so the bind target and --chdir value
agree with what tools see.
Sourcepub fn backend(&self) -> SandboxBackend
pub fn backend(&self) -> SandboxBackend
The backend implementing this sandbox.
Sourcepub fn workspace(&self) -> &Path
pub fn workspace(&self) -> &Path
The canonicalized workspace root, exposed read-write inside the sandbox.
Sourcepub fn options(&self) -> &SandboxOptions
pub fn options(&self) -> &SandboxOptions
The options this sandbox was built with.
Sourcepub fn locate(backend: SandboxBackend) -> Option<PathBuf>
pub fn locate(backend: SandboxBackend) -> Option<PathBuf>
Locate backend’s binary on PATH.
Deliberately does not shell out to which: a lookup that only touches
PATH works everywhere without spawning anything.
Sourcepub fn available() -> Vec<SandboxBackend>
pub fn available() -> Vec<SandboxBackend>
Every backend whose binary is installed, in preference order.
Sourcepub fn detect(workspace: &Path, options: SandboxOptions) -> Result<Self, String>
pub fn detect(workspace: &Path, options: SandboxOptions) -> Result<Self, String>
Build a sandbox on the best installed backend (bwrap first).
The Err explains that neither is available and how to get one; the
caller turns it into a startup message rather than a hard failure, so a
machine without sandbox tooling still starts.
Sourcepub fn from_setting(
value: &str,
workspace: &Path,
options: SandboxOptions,
) -> Result<Self, String>
pub fn from_setting( value: &str, workspace: &Path, options: SandboxOptions, ) -> Result<Self, String>
Resolve a backend name (from --sandbox=<value> or sandbox.backend)
into a sandbox.
auto/empty → Sandbox::detect; an explicit name → that backend,
with an actionable error if it is not installed.
Sourcepub fn argv(
&self,
command: &str,
cwd: Option<&Path>,
) -> (PathBuf, Vec<OsString>)
pub fn argv( &self, command: &str, cwd: Option<&Path>, ) -> (PathBuf, Vec<OsString>)
Assemble the full argv that runs command through /bin/sh inside
this sandbox.
Returns (program, args). cwd becomes the sandbox’s --chdir value
when given; the caller must have already established that it is inside
the workspace, because an out-of-tree directory is simply not visible
in the sandbox mount tree and the command would fail confusingly.
Sourcepub fn argv_with_env(
&self,
command: &str,
cwd: Option<&Path>,
extra: &[(String, String)],
) -> (PathBuf, Vec<OsString>)
pub fn argv_with_env( &self, command: &str, cwd: Option<&Path>, extra: &[(String, String)], ) -> (PathBuf, Vec<OsString>)
Sandbox::argv with extra environment variables for the sandboxed
process.
Needed because bwrap runs --clearenv: variables set on the outer
bwrap process (custom tools’ TH_* parameters, for instance) do not
reach the sandboxed shell, so they have to travel as --setenv
arguments. firejail inherits the parent environment, where extra is
ignored — the caller should still set it on the spawned command so both
backends behave the same.