Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,28 @@ microphone. Audio works with or without `--net`, and is not affected by
in a config file, and `SANDBOX_AUDIO=false` will override that for a single
run.

`--cpus=<CPUS>`::
Limit how many CPUs the sandbox can use. Fractional values such as `1.5` are
allowed. Negative values mean all but that many CPUs, so `--cpus=-2` on a 32
CPU machine lets the sandbox use 30. This limits the total CPU time the
sandbox gets, it does not pin it to specific CPUs, so tools like `nproc` will
still report every CPU.

`--memory=<SIZE>`::
Limit how much memory the sandbox can use, for example `512M` or `4G`.
Suffixes are binary (`1K` is 1024 bytes). Swap is not available to a sandbox
with a memory limit, and when the sandbox runs out of memory the kernel kills
its largest process.
+
Resource limits use cgroup v2 and apply to every process in the sandbox. They
are set when the sandbox starts, so you need to stop the sandbox to change
them. Use `unlimited` to remove a limit set in a config file, for example
`--cpus=unlimited` or `SANDBOX_MEMORY=unlimited`.
+
A sandbox started inside another sandbox can't set up limits of its own.
Instead it warns and shares the limits of the sandbox it's running in. Limits
may not be available at all when `sandbox` is run inside a container.

`--json`::
Formats action output as a JSON blob. Does nothing for sandboxed commands

Expand Down Expand Up @@ -278,6 +300,10 @@ These config files can set most of the CLI options:
mask=[
"~/.ssh",
]

# Resource limits
cpus=-2
memory="8G"
```

## Environment Variables
Expand All @@ -290,6 +316,8 @@ You can also set most of the options with environment variables if you wish:
SANDBOX_NET="none"
SANDBOX_LOG_LEVEL="info"
SANDBOX_BIND="/my/dir"
SANDBOX_CPUS="-2"
SANDBOX_MEMORY="8G"

```

Expand Down
2 changes: 2 additions & 0 deletions cspell.json
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
"cmdline",
"codegen",
"codespell",
"cpus",
"CREAT",
"cstring",
"czvf",
Expand Down Expand Up @@ -169,6 +170,7 @@
"PKGBUILD",
"powercap",
"prctl",
"procs",
"profdata",
"profraw",
"psub",
Expand Down
10 changes: 10 additions & 0 deletions src/actions/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ pub fn config(config: &Config, keys: Option<Vec<String>>) -> Result<()> {
"mask",
"no_default_binds",
"audio",
"cpus",
"memory",
"storage_dir",
"sandbox_dir",
"upper_cwd",
Expand Down Expand Up @@ -47,6 +49,12 @@ pub fn config(config: &Config, keys: Option<Vec<String>>) -> Result<()> {

let no_default_binds_str = format!("{}", config.no_default_binds);
let audio_str = format!("{}", config.audio);
let cpus_str = config
.cpus
.map_or("unlimited".to_string(), |cpus| cpus.to_string());
let memory_str = config
.memory
.map_or("unlimited".to_string(), |memory| memory.to_string());
let ignored_str = format!("{}", config.ignored);
let config_files_str = config
.config_files
Expand Down Expand Up @@ -78,6 +86,8 @@ pub fn config(config: &Config, keys: Option<Vec<String>>) -> Result<()> {
("no_default_binds", no_default_binds_str.as_str())
}
"audio" => ("audio", audio_str.as_str()),
"cpus" => ("cpus", cpus_str.as_str()),
"memory" => ("memory", memory_str.as_str()),
"name" => ("name", config.name.as_str()),
"log_level" => ("log_level", config.log_level.as_str()),
"ignored" => ("ignored", ignored_str.as_str()),
Expand Down
18 changes: 18 additions & 0 deletions src/config/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,24 @@ pub struct Args {
#[arg(long, global = true, action = clap::ArgAction::SetTrue)]
pub audio: bool,

/// Limit how many CPUs the sandbox can use. Fractional values such as 1.5
/// are allowed. Negative values mean all but that many CPUs, so -2 on a
/// 32 CPU machine allows the sandbox to use 30. Use "unlimited" to remove
/// a limit set in a config file. Requires cgroup v2.
#[arg(
long,
global = true,
allow_negative_numbers = true,
value_name = "CPUS"
)]
pub cpus: Option<String>,

/// Limit how much memory the sandbox can use, for example 512M or 4G.
/// Swap is not available to sandboxes with a memory limit. Use
/// "unlimited" to remove a limit set in a config file. Requires cgroup v2.
#[arg(long, global = true, value_name = "SIZE")]
pub memory: Option<String>,

/// Formats action output as a JSON blob. Does nothing for sandboxed commands.
#[arg(long, global = true, action = clap::ArgAction::SetTrue)]
pub json: bool,
Expand Down
203 changes: 203 additions & 0 deletions src/config/limits.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,203 @@
use anyhow::{Result, anyhow};
use serde::Deserialize;

/// The smallest CPU limit cgroups will accept: a 1ms quota per 100ms period
const MIN_CPUS: f64 = 0.01;

/// Removes a limit, e.g. to override one set in a config file
const UNLIMITED: &str = "unlimited";

fn is_unlimited(spec: &str) -> bool {
spec.trim().eq_ignore_ascii_case(UNLIMITED)
}

/// Number of CPUs this process may run on. This matches `nproc` unless we
/// are already running under a CPU quota, in which case the quota is used.
pub fn available_cpus() -> usize {
std::thread::available_parallelism()
.map(|n| n.get())
.unwrap_or(1)
}

/// Parses a CPU limit. Positive values are a number of CPUs and may be
/// fractional. Negative values mean all but that many of the `available`
/// CPUs, so -2 on a 32 CPU machine means 30. "unlimited" means no limit.
pub fn parse_cpus(spec: &str, available: usize) -> Result<Option<f64>> {
let invalid = || {
anyhow!(
"Invalid cpus value '{}': expected a number of CPUs such as 2 or 1.5, a negative number such as -2 to use all but that many CPUs, or unlimited",
spec
)
};

if is_unlimited(spec) {
return Ok(None);
}

let value: f64 = spec.trim().parse().map_err(|_| invalid())?;
if !value.is_finite() || value == 0.0 {
return Err(invalid());
}

let cpus = if value < 0.0 {
available as f64 + value
} else {
value
};

if cpus < MIN_CPUS {
return Err(anyhow!(
"Invalid cpus value '{}': this leaves {} of the {} available CPUs for the sandbox, the minimum is {}",
spec,
cpus.max(0.0),
available,
MIN_CPUS
));
}

Ok(Some(cpus))
}

/// Parses a memory size such as 512M, 4G, 1.5GiB or a plain number of bytes.
/// Suffixes are binary (K = 1024) and case insensitive. "unlimited" means no
/// limit.
pub fn parse_memory(spec: &str) -> Result<Option<u64>> {
let invalid = || {
anyhow!(
"Invalid memory value '{}': expected a size such as 512M or 4G, or unlimited",
spec
)
};

if is_unlimited(spec) {
return Ok(None);
}

let trimmed = spec.trim();
let split = trimmed
.find(|c: char| c.is_ascii_alphabetic())
.unwrap_or(trimmed.len());
let (number, suffix) = trimmed.split_at(split);

let multiplier: u64 = match suffix.to_ascii_lowercase().as_str() {
"" | "b" => 1,
"k" | "kb" | "kib" => 1 << 10,
"m" | "mb" | "mib" => 1 << 20,
"g" | "gb" | "gib" => 1 << 30,
"t" | "tb" | "tib" => 1 << 40,
_ => return Err(invalid()),
};

let number: f64 = number.trim().parse().map_err(|_| invalid())?;
let bytes = number * multiplier as f64;
if !bytes.is_finite() || bytes < 1.0 || bytes > u64::MAX as f64 {
return Err(invalid());
}

Ok(Some(bytes as u64))
}

/// Lets config files specify limits as either numbers or strings, e.g.
/// `cpus = -2` or `memory = "4G"`
pub(crate) fn deserialize_number_or_string<'de, D>(
deserializer: D,
) -> Result<Option<String>, D::Error>
where
D: serde::Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(untagged)]
enum NumberOrString {
Integer(i64),
Float(f64),
String(String),
}

Ok(
Option::<NumberOrString>::deserialize(deserializer)?.map(|value| {
match value {
NumberOrString::Integer(i) => i.to_string(),
NumberOrString::Float(f) => f.to_string(),
NumberOrString::String(s) => s,
}
}),
)
}

#[cfg(test)]
mod tests {
use super::*;

#[test]
fn test_parse_cpus() {
assert_eq!(parse_cpus("2", 32).unwrap(), Some(2.0));
assert_eq!(parse_cpus(" 1.5 ", 32).unwrap(), Some(1.5));
assert_eq!(parse_cpus("0.01", 32).unwrap(), Some(0.01));
assert_eq!(parse_cpus("64", 32).unwrap(), Some(64.0));
assert_eq!(parse_cpus("-2", 32).unwrap(), Some(30.0));
assert_eq!(parse_cpus("-0.5", 4).unwrap(), Some(3.5));
assert_eq!(parse_cpus("-31", 32).unwrap(), Some(1.0));
assert_eq!(parse_cpus("unlimited", 32).unwrap(), None);
assert_eq!(parse_cpus(" Unlimited ", 32).unwrap(), None);
}

#[test]
fn test_parse_cpus_invalid() {
for spec in ["", "abc", "0", "-0", "nan", "inf", "-inf", "2 cpus"] {
let err = parse_cpus(spec, 32).unwrap_err().to_string();
assert!(err.contains("expected a number of CPUs"), "{}", err);
}

let err = parse_cpus("-32", 32).unwrap_err().to_string();
assert!(err.contains("leaves 0 of the 32 available CPUs"), "{}", err);
let err = parse_cpus("-40", 32).unwrap_err().to_string();
assert!(err.contains("leaves 0 of the 32 available CPUs"), "{}", err);
let err = parse_cpus("0.001", 32).unwrap_err().to_string();
assert!(err.contains("the minimum is 0.01"), "{}", err);
}

#[test]
fn test_parse_memory() {
assert_eq!(parse_memory("1024").unwrap(), Some(1024));
assert_eq!(parse_memory("1024b").unwrap(), Some(1024));
assert_eq!(parse_memory("4k").unwrap(), Some(4096));
assert_eq!(parse_memory("4KiB").unwrap(), Some(4096));
assert_eq!(parse_memory("512M").unwrap(), Some(512 << 20));
assert_eq!(parse_memory("512mb").unwrap(), Some(512 << 20));
assert_eq!(parse_memory(" 4G ").unwrap(), Some(4 << 30));
assert_eq!(parse_memory("4 GiB").unwrap(), Some(4 << 30));
assert_eq!(parse_memory("1.5G").unwrap(), Some(3 << 29));
assert_eq!(parse_memory("2T").unwrap(), Some(2 << 40));
assert_eq!(parse_memory("unlimited").unwrap(), None);
assert_eq!(parse_memory("UNLIMITED").unwrap(), None);
}

#[test]
fn test_parse_memory_invalid() {
for spec in [
"", "G", "abc", "0", "0.5", "-1G", "4X", "4GBs", "1e30T", "inf",
] {
let err = parse_memory(spec).unwrap_err().to_string();
assert!(err.contains("expected a size"), "{}: {}", spec, err);
}
}

#[test]
fn test_deserialize_number_or_string() {
#[derive(Deserialize)]
struct Limits {
#[serde(
deserialize_with = "deserialize_number_or_string",
default
)]
value: Option<String>,
}

let parse = |s: &str| toml::from_str::<Limits>(s).unwrap().value;
assert_eq!(parse("value = -2"), Some("-2".to_string()));
assert_eq!(parse("value = 1.5"), Some("1.5".to_string()));
assert_eq!(parse("value = \"4G\""), Some("4G".to_string()));
assert_eq!(parse(""), None);
assert!(toml::from_str::<Limits>("value = true").is_err());
}
}
1 change: 1 addition & 0 deletions src/config/mod.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
pub mod cli;
pub mod impls;
pub mod limits;
pub mod resolve;
pub mod structs;

Expand Down
Loading
Loading