ms2k/lazaret
SHA256
Watch
0
Code Releases 3 Activity

Bound and configure the per-Domain runsc dcache

Browse source
This commit is contained in:
ms2k 2026-07-24 23:34:02 +09:00
commit db9a561d0c
13 changed files with 157 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

11
crates/lazaret-core/src/configuration.rs
View file

@ -10,8 +10,8 @@ use sha2::{Digest, Sha256};
use crate::identity::{ConfigurationFingerprint, DeviceId, DomainId, HostPath, InodeId, MountId};
use crate::records::{
ConfigurationFingerprintRecordV1, MailboxRequest, ResolvedAutoApprovalRule, ResolvedVolume,
TRUSTED_HOST_CONFIGURATION_SCHEMA_ID, TrustedHostConfigurationV1, VolumeKind,
ConfigurationFingerprintRecordV1, MAX_RUNSC_DCACHE, MailboxRequest, ResolvedAutoApprovalRule,
ResolvedVolume, TRUSTED_HOST_CONFIGURATION_SCHEMA_ID, TrustedHostConfigurationV1, VolumeKind,
};
use confined_io::{io_error, open_absolute_directory, validate_executable};
use validation::validate_sandbox_path;
@ -27,6 +27,7 @@ pub enum ConfigurationErrorKind {
InvalidProfile,
InvalidPath,
PathConflict,
InvalidRuntime,
InvalidNetwork,
MissingEnvironment,
InvalidVolume,
@ -72,6 +73,7 @@ const fn error_label(kind: ConfigurationErrorKind) -> &'static str {
ConfigurationErrorKind::InvalidProfile => "invalid profile",
ConfigurationErrorKind::InvalidPath => "invalid path",
ConfigurationErrorKind::PathConflict => "path conflict",
ConfigurationErrorKind::InvalidRuntime => "invalid runtime configuration",
ConfigurationErrorKind::InvalidNetwork => "invalid network policy",
ConfigurationErrorKind::MissingEnvironment => "invalid environment reference",
ConfigurationErrorKind::InvalidVolume => "invalid volume",
@ -679,6 +681,11 @@ impl ResolvedDomainConfiguration {
&self.fingerprint_record
}
#[must_use]
pub const fn runsc_dcache(&self) -> u32 {
self.fingerprint_record.runsc_dcache
}
#[must_use]
pub fn effective_allow_prefixes(&self) -> &[Ipv4Prefix] {
&self.effective_allow_prefixes

1
crates/lazaret-core/src/configuration/loading.rs
View file

@ -343,6 +343,7 @@ pub fn load_trusted_configuration(
selected_profile: request.selected_profile.clone(),
storage_root: host_path(&storage_canonical),
runtime_root: host_path(&runtime_canonical),
runsc_dcache: configuration.runtime().runsc_dcache,
image: selected.image.clone(),
isolate_gitignored: selected.isolate_gitignored,
persistent_dirs,

9
crates/lazaret-core/src/configuration/validation.rs
View file

@ -4,7 +4,7 @@ use super::confined_io::{
};
use super::{
ConfigurationError, ConfigurationErrorKind, ConfigurationFingerprint,
ConfigurationFingerprintRecordV1, Digest, DomainId, Sha256,
ConfigurationFingerprintRecordV1, Digest, DomainId, MAX_RUNSC_DCACHE, Sha256,
TRUSTED_HOST_CONFIGURATION_SCHEMA_ID, TrustedHostConfigurationV1,
};
@ -33,6 +33,7 @@ pub fn derive_configuration_fingerprint(
push_bytes(&mut preimage, record.selected_profile.as_bytes())?;
push_bytes(&mut preimage, record.storage_root.as_bytes())?;
push_bytes(&mut preimage, record.runtime_root.as_bytes())?;
preimage.extend_from_slice(&record.runsc_dcache.to_be_bytes());
push_bytes(&mut preimage, record.image.as_bytes())?;
push_bool(&mut preimage, record.isolate_gitignored);
@ -87,6 +88,12 @@ pub(super) fn validate_structural_configuration(
"unknown configuration schema",
));
}
if configuration.runtime().runsc_dcache > MAX_RUNSC_DCACHE {
return Err(ConfigurationError::new(
ConfigurationErrorKind::InvalidRuntime,
format!("runsc_dcache exceeds {MAX_RUNSC_DCACHE} entries"),
));
}
for (name, profile) in configuration.profiles() {
validate_profile_name(name)?;
validate_text(&profile.image, "profile image")?;

31
crates/lazaret-core/src/records/configuration.rs
View file

@ -6,6 +6,8 @@ pub const DOMAIN_STORE_SCHEMA_VERSION: u32 = 1;
pub const STORAGE_CATALOG_SCHEMA_VERSION: u32 = 1;
pub const TRUSTED_HOST_CONFIGURATION_SCHEMA_ID: &str = "lazaret-trusted-host-config-v1";
pub const DEFAULT_PERSISTENT_DIRS: [&str; 5] = ["/root", "/usr", "/var", "/etc", "/opt"];
pub const DEFAULT_RUNSC_DCACHE: u32 = 50_000;
pub const MAX_RUNSC_DCACHE: u32 = 262_144;
#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
@ -23,6 +25,25 @@ pub struct NetworkConfigurationV1 {
pub default_deny: Vec<String>,
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct RuntimeConfigurationV1 {
#[serde(default = "default_runsc_dcache")]
pub runsc_dcache: u32,
}
impl Default for RuntimeConfigurationV1 {
fn default() -> Self {
Self {
runsc_dcache: DEFAULT_RUNSC_DCACHE,
}
}
}
const fn default_runsc_dcache() -> u32 {
DEFAULT_RUNSC_DCACHE
}
#[derive(Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum VolumeKind {
@ -103,6 +124,7 @@ pub struct TrustedHostConfigurationV1 {
schema_id: String,
storage: StorageConfigurationV1,
network: NetworkConfigurationV1,
runtime: RuntimeConfigurationV1,
profiles: BTreeMap<String, ProfileConfigurationV1>,
}
@ -122,6 +144,11 @@ impl TrustedHostConfigurationV1 {
&self.network
}
#[must_use]
pub const fn runtime(&self) -> &RuntimeConfigurationV1 {
&self.runtime
}
#[must_use]
pub const fn profiles(&self) -> &BTreeMap<String, ProfileConfigurationV1> {
&self.profiles
@ -142,6 +169,8 @@ impl<'de> Deserialize<'de> for TrustedHostConfigurationV1 {
storage: StorageConfigurationV1,
#[serde(default)]
network: NetworkConfigurationV1,
#[serde(default)]
runtime: RuntimeConfigurationV1,
profiles: BTreeMap<String, ProfileConfigurationV1>,
}
@ -160,6 +189,7 @@ impl<'de> Deserialize<'de> for TrustedHostConfigurationV1 {
schema_id: fields.schema_id,
storage: fields.storage,
network: fields.network,
runtime: fields.runtime,
profiles: fields.profiles,
})
}
@ -192,6 +222,7 @@ pub struct ConfigurationFingerprintRecordV1 {
pub selected_profile: String,
pub storage_root: HostPath,
pub runtime_root: HostPath,
pub runsc_dcache: u32,
pub image: String,
pub isolate_gitignored: bool,
pub persistent_dirs: Vec<String>,

53
crates/lazaret-core/tests/configuration.rs
View file

@ -13,8 +13,8 @@ use lazaret_core::configuration::{
};
use lazaret_core::identity::HostPath;
use lazaret_core::records::{
ConfigurationFingerprintRecordV1, EnvironmentReference, ResolvedAutoApprovalRule,
ResolvedVolume, VolumeAccess, VolumeKind,
ConfigurationFingerprintRecordV1, DEFAULT_RUNSC_DCACHE, EnvironmentReference, MAX_RUNSC_DCACHE,
ResolvedAutoApprovalRule, ResolvedVolume, VolumeAccess, VolumeKind,
};
use static_assertions::assert_not_impl_any;
@ -150,6 +150,7 @@ image = "example.invalid/agent:v1"
assert!(parsed.storage().data_root.is_none());
assert!(parsed.network().default_allow.is_empty());
assert!(parsed.network().default_deny.is_empty());
assert_eq!(parsed.runtime().runsc_dcache, DEFAULT_RUNSC_DCACHE);
for (value, expected) in [
("[]", Vec::<String>::new()),
@ -212,6 +213,47 @@ volumes = [{ host = "/source", container = "/root/source", kind = "socket" }]
}
}
#[test]
fn runtime_dcache_defaults_accepts_budget_bounds_and_rejects_excess() {
let minimal = r#"schema = "lazaret-trusted-host-config-v1"
[profiles.default]
image = "example.invalid/agent:v1"
"#;
assert_eq!(
parse_trusted_configuration(minimal.as_bytes())
.unwrap()
.runtime()
.runsc_dcache,
DEFAULT_RUNSC_DCACHE
);
for value in [0, MAX_RUNSC_DCACHE] {
let explicit = minimal.replace(
"[profiles.default]",
&format!("[runtime]\nrunsc_dcache = {value}\n[profiles.default]"),
);
assert_eq!(
parse_trusted_configuration(explicit.as_bytes())
.unwrap()
.runtime()
.runsc_dcache,
value
);
}
let excessive = minimal.replace(
"[profiles.default]",
&format!(
"[runtime]\nrunsc_dcache = {}\n[profiles.default]",
MAX_RUNSC_DCACHE + 1
),
);
assert_eq!(
parse_trusted_configuration(excessive.as_bytes())
.unwrap_err()
.kind(),
ConfigurationErrorKind::InvalidRuntime
);
}
#[test]
fn sandbox_layout_is_closed_normalized_and_requires_workspace() {
assert!(SandboxLayoutV1::from_protected_destinations(["/proc".into()]).is_err());
@ -834,6 +876,7 @@ fn digest_vectors_are_framed_and_order_independent() {
selected_profile: "default".into(),
storage_root: HostPath::new(b"/data".to_vec()),
runtime_root: HostPath::new(b"/run/user/1000/lazaret".to_vec()),
runsc_dcache: DEFAULT_RUNSC_DCACHE,
image: "example.invalid/agent:v1".into(),
isolate_gitignored: true,
persistent_dirs: vec!["/var".into(), "/root".into()],
@ -867,9 +910,9 @@ fn digest_vectors_are_framed_and_order_independent() {
assert_eq!(
first.as_bytes(),
&[
0xd3, 0xba, 0xef, 0x91, 0x21, 0x0f, 0x98, 0x31, 0x6c, 0xea, 0x34, 0xfb, 0x41, 0xbd,
0x6c, 0xa5, 0x07, 0xf0, 0xb8, 0x9b, 0x90, 0x77, 0xaf, 0x0a, 0x0e, 0xd0, 0x6a, 0xd6,
0x46, 0xc7, 0x2d, 0xbf,
0x5f, 0x1d, 0xeb, 0x46, 0xa4, 0xb5, 0x90, 0xc3, 0x47, 0x0b, 0xa0, 0xdf, 0xd6, 0x6e,
0x9d, 0x91, 0xdb, 0xf3, 0x75, 0xf6, 0xbe, 0x50, 0x9a, 0x8d, 0xba, 0x4a, 0x3d, 0xae,
0xf3, 0x05, 0x97, 0x56,
]
);
record.persistent_dirs.reverse();

1
crates/lazaret-core/tests/schema_records.rs
View file

@ -195,6 +195,7 @@ struct RawTrustedHostConfigurationV1 {
schema_id: String,
storage: StorageConfigurationV1,
network: NetworkConfigurationV1,
runtime: RuntimeConfigurationV1,
profiles: BTreeMap<String, ProfileConfigurationV1>,
}

1
crates/lazaret-core/tests/schema_records/documents.rs
View file

@ -189,6 +189,7 @@ fn trusted_host_configuration_postcard_dispatch_rejects_unknown_schema() {
schema_id: schema_id.into(),
storage: StorageConfigurationV1::default(),
network: NetworkConfigurationV1::default(),
runtime: RuntimeConfigurationV1::default(),
profiles: profiles.clone(),
};
assert!(matches!(

5
crates/lazaret-core/tests/schema_records/encoding.rs
View file

@ -569,6 +569,7 @@ persistent_dirs = []
selected_profile: "trusted".into(),
storage_root: HostPath::new(b"/data/lazaret".to_vec()),
runtime_root: HostPath::new(b"/run/user/1000/lazaret".to_vec()),
runsc_dcache: DEFAULT_RUNSC_DCACHE,
image: "example.invalid/agent:v1".into(),
isolate_gitignored: true,
persistent_dirs: vec!["/root".into()],
@ -641,8 +642,8 @@ persistent_dirs = []
assert_eq!(
seen.digest(),
[
245, 169, 157, 164, 67, 211, 165, 23, 129, 62, 119, 92, 247, 248, 131, 4, 252, 42, 34,
214, 207, 60, 126, 219, 81, 68, 159, 6, 26, 88, 233, 108,
23, 80, 80, 177, 148, 141, 234, 213, 240, 108, 167, 148, 252, 121, 212, 128, 5, 195,
176, 126, 71, 76, 141, 196, 174, 125, 212, 31, 115, 155, 178, 139,
]
);
}

6
crates/lazaret-runtime-supervisor/src/sandbox.rs
View file

@ -693,7 +693,11 @@ fn build_sandbox_bundle_from_source(
.map_err(oci_error)?;
let specification_json = canonical_specification_json(&specification)?;
let bundle_authorization = Sha256::digest(&specification_json).into();
let command = build_runsc_command(&paths, bundle_authorization);
let command = build_runsc_command(
&paths,
request.configuration.runsc_dcache(),
bundle_authorization,
);
let runtime_sources =
handoff_runtime_sources(&paths, request.terminal.as_ref(), &specification_json);
Ok(SandboxBundle {

2
crates/lazaret-runtime-supervisor/src/sandbox/runtime_sources.rs
View file

@ -278,6 +278,7 @@ pub(super) fn build_linux() -> Result<oci_spec::runtime::Linux, SandboxBuildErro
pub(super) fn build_runsc_command(
paths: &RuntimePaths,
dcache: u32,
bundle_authorization: [u8; 32],
) -> RunscCommand {
RunscCommand::new(
@ -292,6 +293,7 @@ pub(super) fn build_runsc_command(
)),
OsString::from("-network=host"),
OsString::from("-ignore-cgroups"),
OsString::from(format!("-dcache={dcache}")),
OsString::from(format!(
"-overlay2=root:dir={}",
paths

34
crates/lazaret-runtime-supervisor/tests/sandbox_builder.rs
View file

@ -373,6 +373,7 @@ fn assert_runtime_command(bundle: &SandboxBundle, fixture: &Fixture) {
format!("-root={runtime_domain}/runsc"),
"-network=host".to_owned(),
"-ignore-cgroups".to_owned(),
"-dcache=50000".to_owned(),
format!(
"-overlay2=root:dir={runtime_domain}/runsc-overlay/{}",
"11".repeat(32)
@ -402,6 +403,39 @@ fn assert_runtime_command(bundle: &SandboxBundle, fixture: &Fixture) {
}));
}
#[test]
fn configured_dcache_is_fingerprinted_and_passed_to_runsc() {
let fixture = Fixture::new();
let configuration_path = fixture.tree.path().join("configuration/lazaret.toml");
let source = fs::read_to_string(&configuration_path).unwrap();
fs::write(
&configuration_path,
source.replace("[network]", "[runtime]\nrunsc_dcache = 12345\n\n[network]"),
)
.unwrap();
let configuration = fixture.reload_configuration();
assert_eq!(configuration.runsc_dcache(), 12_345);
assert_ne!(
configuration.configuration_fingerprint(),
fixture.configuration.configuration_fingerprint()
);
let bundle = build_sandbox_bundle(SandboxBuildRequest {
configuration: &configuration,
container_id: ContainerId::new([0x11; 32]),
expected_network_namespace: current_network_namespace(),
root_process: root_process([]),
terminal: None,
prepared_root: fixture.tree.path().join("prepared-root"),
})
.unwrap();
assert!(
bundle
.command()
.arguments()
.contains(&"-dcache=12345".into())
);
}
#[test]
fn product_init_role_has_exact_terminal_neutral_rootless_bundle_shape() {
let fixture = Fixture::new();

3
docs/example.toml
View file

@ -8,6 +8,9 @@ data_root = "~/.local/share/lazaret"
[network]
default_allow = ["192.0.2.53/32", "198.51.100.53/32"]
[runtime]
runsc_dcache = 50000
[profiles.default]
image = "docker.io/library/debian:trixie"
isolate_gitignored = true

11
docs/specification.md
View file

@ -299,6 +299,17 @@ An omitted profile `persistent_dirs` field selects `/root`, `/usr`, `/var`,
`/etc`, and `/opt`. An explicit list replaces that default in full, including an
empty list or paths used by an unorthodox distribution.
The optional `runtime.runsc_dcache` field sets the maximum number of
zero-reference dentries retained by the global runsc gofer-client cache in each
Domain sandbox. It defaults to 50,000 and accepts values from 0 through 262,144
inclusive; zero disables zero-reference dentry retention. The maximum keeps the
cache-entry ceiling at half of the 524,288 per-process descriptor budget,
leaving nominal headroom for referenced files and non-cache activity.
Configured capacity is allocated on demand, while populated capacity consumes
Domain-local sentry and routed-workspace descriptors and memory. Concurrent
Domains have independent caches and their host resource consumption is
additive.
The loader resolves environment references only after structural, path, and
network validation. A missing, non-UTF-8, or NUL-containing host value refuses
the selected profile. Resolved values live only in one move-owned,