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
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,8 @@ const UMOUNT: &str = "/sbin/umount";
const UNMOUNT_WAIT: Duration = Duration::from_secs(60);
const REAP_WAIT: Duration = Duration::from_secs(5);
const OUTPUT: usize = 2048;
/// How long an inspection read waits for `mount` to print the table.
const TABLE_WAIT: Duration = Duration::from_millis(500);
/// How long it then waits for a `mount` it killed to end.
const TABLE_REAP: Duration = Duration::from_millis(500);
/// The most of the table that is read.
const TABLE: usize = 1 << 20;

/// Children a `umount` KILL or `mount` timeout did not release. Their exits
/// Children a `umount` KILL did not release. Their exits
/// are reaped by the shared retained queue
/// ([`layerfs_bridge::process::Retained`]), never by a second wait here.
static RETAINED: LazyLock<Retained> = LazyLock::new(Retained::default);
Expand Down Expand Up @@ -69,77 +63,10 @@ pub(crate) fn mount_line(line: &str) -> Option<(PathBuf, String)> {
Some((PathBuf::from(point), fs.to_owned()))
}

/// What `mount` prints, for an inspection read: one run with a fixed path,
/// no environment but the C locale and no input, given [`TABLE_WAIT`] to
/// end. A run that takes longer is killed and reaped, and is an error, as
/// is one that fails; the caller then reads without a table. `mount`
/// lists the kernel's table as it is (`getfsstat` with `MNT_NOWAIT`) and
/// asks no mounted server, so it is not expected to wait; the deadline is
/// for a host where it does.
pub(crate) fn mount_table() -> io::Result<String> {
RETAINED.reap();
let mut child = Command::new(MOUNT)
.env_clear()
.env("LC_ALL", "C")
.stdin(Stdio::null())
.stdout(Stdio::piped())
.stderr(Stdio::null())
.spawn()?;
// a pipe that cannot be read without waiting is not read
let mut pipe = child.stdout.take().and_then(|pipe| {
fcntl(&pipe, FcntlArg::F_SETFL(OFlag::O_NONBLOCK))
.ok()
.map(|_| pipe)
});
let mut text = Vec::new();
let mut read = |text: &mut Vec<u8>| {
let mut bytes = [0; 4096];
while let Some(Ok(count @ 1..)) = pipe.as_mut().map(|pipe| pipe.read(&mut bytes)) {
text.extend_from_slice(&bytes[..count.min(TABLE.saturating_sub(text.len()))]);
}
};
let deadline = Instant::now() + TABLE_WAIT;
let ended = loop {
read(&mut text);
match child.try_wait() {
Ok(Some(status)) => break Ok(status),
Ok(None) if Instant::now() < deadline => std::thread::sleep(Duration::from_millis(2)),
Ok(None) => {
break Err(io::Error::new(
io::ErrorKind::TimedOut,
"mount took too long",
))
}
Err(error) => break Err(error),
}
};
match ended {
Ok(status) if status.success() => {
read(&mut text);
Ok(String::from_utf8_lossy(&text).into_owned())
}
Ok(status) => Err(io::Error::other(format!("mount listing failed: {status}"))),
Err(error) => {
let pid = child.id();
let _ = child.kill();
let deadline = Instant::now() + TABLE_REAP;
let reaped = loop {
match child.try_wait() {
Ok(Some(status)) => break Some(status),
Ok(None) if Instant::now() < deadline => {
std::thread::sleep(Duration::from_millis(2));
}
Ok(None) | Err(_) => break None,
}
};
match reaped {
Some(status) => RETAINED.record(pid, status),
None => RETAINED.retain(child),
}
Err(error)
}
}
}
/// What `mount` prints, for an inspection read: the shared bounded listing
/// ([`layerfs_bridge::process::mount_table`]). An error means the caller
/// reads without a table.
pub(crate) use layerfs_bridge::process::mount_table;

/// Forces the mount at `point` off once; a point no longer mounted is done.
pub(crate) fn force_unmount(point: &Path) -> io::Result<()> {
Expand Down
12 changes: 10 additions & 2 deletions control/crates/layerfs-sandbox/src/workspace/serve.rs
Original file line number Diff line number Diff line change
Expand Up @@ -281,17 +281,25 @@ pub fn unmount(host: &Host, path: Option<&str>, discard: bool, force: bool) -> O
let mut control = crate::daemon::trace::control(&state.controls)?;
sent = true;
let mut api = workspace(&mut control);
// A request whose sending was never attempted reached no daemon:
// the attempt's record is undone like a call that never connected.
let mut answered = |failure: Box<crate::OperationFailure>| {
if matches!(&failure.cause, OperationCause::Exchange(exchange) if !exchange.attempted) {
sent = false;
}
operation(failure)
};
// Forced: one abort write ends the connection, also after a normal
// unmount stalled at Join; uncommitted changes are dropped.
if force {
match api.unmount(token, true).map_err(operation)? {
match api.unmount(token, true).map_err(&mut answered)? {
Some(outcome) => Ok(values::force_unmounted(&outcome)),
None => values::unmounted(&Unmounted::Closed),
}
} else {
match api.unmount_checked(token, discard) {
Ok(answer) => values::unmounted(&answer),
Err(error) => Err(operation(error)),
Err(error) => Err(answered(error)),
}
}
})();
Expand Down
5 changes: 3 additions & 2 deletions docs/architecture/api/sdk/workspace.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,8 +225,9 @@ established without dialling again. The one exception is a record the daemon
itself answered `Retained` at stage `Detach`: its export is still held and one
forced client unmount is what finishes it, so `force` may replace that record
with a forced attempt (the daemon's guard remains the real gate, and `Busy`,
`Dirty`, or an unsent call restores the earlier record). A `Failed` answer
without a stage — a send or connect failure, or a refusal before any effect —
`Dirty`, or a call whose request was never sent restores the earlier record:
a connect failure, or an exchange that failed before sending was attempted).
A `Failed` answer without a stage — a send that was attempted, or a refusal —
and an in-progress, `Unknown`, already-forced, other-stage or pre-`forced`
record keeps its answer and is not forceable. The record is versioned (`v`):
version 1 adds `forced` and the daemon's `stage` to version 0's `state`,
Expand Down
4 changes: 2 additions & 2 deletions docs/architecture/engine/daemon/control-calls.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ differs. `Exported`, `ExportLeaving` and `ExportKept` mirror `Ready`,
| --- | --- | --- |
| Attach | Serve the engine mount as one loopback NFSv3 export on a fresh port; the client mounts it with the mount helper; Ready only after the helper reports the mount, and the host's mount table is read once to record whether the mount is listed. The receipt has `abi_major == 0` and `mount_id` = the port | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) |
| Commit | Flush first (flush helper, or the export volume's own flush: `sync_volume_np(<dir>, SYNC_VOLUME_WAIT)` on macOS, `sync(2)` elsewhere; a failed flush refuses the Commit as `Failed` at `commit:flush`), close the export's descriptors, run the unchanged Commit; after an install of another root, close them again | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs), [`invalidate.rs`](../../../../engine/crates/layerfs-daemon/src/control/invalidate.rs) |
| Unmount | Helper unmount (busy is reversible), stop the export, revoke, Close. A failed or timed-out helper is settled by the mount table: a mount listed at Attach and gone now completes teardown, while a still-listed one or an unreadable table keeps `Retained(Detach)` | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) |
| Unmount | Helper unmount (busy is reversible), stop the export, revoke, Close. A failed or timed-out helper is settled by the mount table: a mount listed at Attach and gone now completes teardown once the helper has ended, while a still-listed one, an unreadable table or a helper still running keeps `Retained(Detach)` | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) |
| ForceUnmount | Force helper once, then the same teardown; also finishes an export kept at `Detach` whose client mount stayed | same |
| Helper run | One attempt, at most `HELPER_WAIT` 60 s, then killed and reported; a child still unreaped past `REAP_WAIT` 5 s enters the retained queue and is polled by its one background reaper | [`export_helper.rs`](../../../../engine/crates/layerfs-daemon/src/control/export_helper.rs), [`process/retained.rs`](../../../../engine/crates/layerfs-bridge/src/process/retained.rs) |

Expand Down Expand Up @@ -200,7 +200,7 @@ reply ForceUnmounted { token, ForcedOutcome { facts, work, cleanup } }
| The abort write uses the connection's own control, bound from the daemon's `fusectl` tree at Attach; without it Force is refused before any effect | [`force.rs`](../../../../engine/crates/layerfs-daemon/src/control/force.rs), [`application/filesystem.rs`](../../../../engine/crates/layerfs-daemon/src/application/filesystem.rs) |
| A normal unmount stalled at `Join` with its abort unused is forced from its retained session; its plain detach counts as the one detach | [`force.rs`](../../../../engine/crates/layerfs-daemon/src/control/force.rs), [`serving.rs`](../../../../engine/crates/layerfs-daemon/src/control/serving.rs) |
| An export kept at `Detach` whose export and receipt are still held and whose forced facts are unset is forced by the one forced client unmount (`umount -f` on macOS, `umount -f -l` on Linux); a still-listed mount keeps `Retained(Detach)` with forced facts. On Linux that helper detaches lazily, so its failure never counts as a detach even when the table no longer lists the mount | [`force.rs`](../../../../engine/crates/layerfs-daemon/src/control/force.rs), [`export_custody.rs`](../../../../engine/crates/layerfs-daemon/src/control/export_custody.rs) `ExportKept::forceable` |
| Normal NFS `Unmount` keeps `Retained(Detach)` when Attach never saw the mount listed (`Exported::tracked` false), when the table still lists it or cannot be read (`detached_export`), or when the helper detaches lazily (`-l`/`--lazy` in its own words: the mount leaves the table before the kernel gives its superblock back, so the table proves nothing); the mount point itself is never resolved (`listed` compares the configured path and the name below canonical mount home) | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs), [`export_helper.rs`](../../../../engine/crates/layerfs-daemon/src/control/export_helper.rs) |
| Normal NFS `Unmount` keeps `Retained(Detach)` when Attach never saw the mount listed (`Exported::tracked` false), when the table still lists it or cannot be read (`detached_export`), when the killed helper's exit was not observed (`Ran::ended`: a plain Linux `umount` leaves the table before the superblock's shutdown flushes through the export), or when the helper detaches lazily (`-l`/`--lazy` in its own words: the mount leaves the table before the kernel gives its superblock back, so the table proves nothing); the mount point itself is never resolved (`listed` compares the configured path and the name below canonical mount home) | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs), [`export_helper.rs`](../../../../engine/crates/layerfs-daemon/src/control/export_helper.rs) |
| A helper past `KILL` and `REAP_WAIT` enters the retained queue, whose one background thread reaps and records its exit (shared with the macOS driver's `umount -f`). Its bound is one thread and 64 recorded exits, not time: a child whose exit never comes keeps that thread polling for as long as the custody lasts, because a deadline would drop the only handle that can reap it. For tests only, `ExportServingConfig` adds `mount_table`, `reap_wait` and `helper_wait`, and `ExportServing::reaped_helpers` reads observed exits | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs), [`process/retained.rs`](../../../../engine/crates/layerfs-bridge/src/process/retained.rs) |
| `relinquish_unknown` permits local disposal of stopped unknown Commit custody; the receipt keeps it `Unknown` | [`force.rs`](../../../../engine/crates/layerfs-daemon/src/control/force.rs) |
| On the NFS route the force helper is the abort | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) |
Expand Down
4 changes: 2 additions & 2 deletions docs/architecture/engine/kernel-routes/nfs.md
Original file line number Diff line number Diff line change
Expand Up @@ -346,9 +346,9 @@ or container, where the environment is passed differently.
| Mount-table and helper rule | Source |
| --- | --- |
| Every step above is one attempt; the mount table is the only witness for a failed or timed-out unmount helper. | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) |
| Attach reads the host's mount table once after the mount helper returns: one `/sbin/mount` run (macOS) or `/proc/self/mountinfo` read (Linux) per Attach; unmount timing is unaffected. | `Exported::tracked` in [`export_custody.rs`](../../../../engine/crates/layerfs-daemon/src/control/export_custody.rs) |
| Attach reads the host's mount table once after the mount helper returns: one `/sbin/mount` run (macOS) or `/proc/self/mountinfo` read (Linux) per Attach; unmount timing is unaffected. The macOS run is bounded (500 ms, then killed and read as an unreadable table) by the listing the driver's inspection reads share, [`process::mount_table`](../../../../engine/crates/layerfs-bridge/src/process/mount_table.rs). | `Exported::tracked` in [`export_custody.rs`](../../../../engine/crates/layerfs-daemon/src/control/export_custody.rs) |
| The mount point itself is never resolved (a lookup through a wedged mount can block or fail); `listed` compares the configured path and the same name below the canonical mount home. | [`export_helper.rs`](../../../../engine/crates/layerfs-daemon/src/control/export_helper.rs) `listed` |
| A failed or timed-out unmount helper completes teardown only when Attach saw it listed and the table no longer does; a still-listed mount, an unreadable table, or a helper that detaches lazily (`-l`) keeps `Retained(Detach)` and the export serving. | `detached_export` in [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) |
| A failed or timed-out unmount helper completes teardown only when Attach saw it listed, the helper has ended, and the table no longer lists it; a still-listed mount, an unreadable table, a helper that detaches lazily (`-l`), or a killed helper whose exit was not observed keeps `Retained(Detach)` and the export serving. A plain Linux `umount` drops the table entry before the superblock's shutdown, which flushes the client's writes through this export, so only an ended helper lets the table witness the end (`Ran::ended`). | `detached_export` in [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) |
| A helper past `KILL` and `REAP_WAIT` is reaped in the background by the shared retained queue, with nothing waiting for it or signalling twice. | [`process/retained.rs`](../../../../engine/crates/layerfs-bridge/src/process/retained.rs) |

| MOUNT procedure | Answer |
Expand Down
7 changes: 6 additions & 1 deletion engine/crates/layerfs-bridge/src/process/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,23 @@
//! from `/proc` on Linux (`linux.rs`) and `proc_pidinfo`/`sysctl` on macOS
//! (`darwin.rs`, this crate's one audited `unsafe` file), and the retained
//! child custody both the daemon's NFS helpers and the macOS driver's
//! `umount -f` use after a KILL (`retained.rs`). It sits below the
//! `umount -f` use after a KILL (`retained.rs`), and the macOS mount table
//! under a deadline (`mount_table.rs`). It sits below the
//! control layer so the home and the drivers share it without an edge
//! between them.
#[cfg(target_os = "macos")]
mod darwin;
mod identity;
#[cfg(target_os = "linux")]
mod linux;
#[cfg(target_os = "macos")]
mod mount_table;
mod retained;
#[cfg(target_os = "macos")]
pub use darwin::{boot, processes, stat, sync_volume_wait};
pub use identity::{pid, LocalProcess, Stat};
#[cfg(target_os = "linux")]
pub use linux::{boot, processes, stat};
#[cfg(target_os = "macos")]
pub use mount_table::mount_table;
pub use retained::Retained;
93 changes: 93 additions & 0 deletions engine/crates/layerfs-bridge/src/process/mount_table.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
//! The macOS mount table under a deadline: one `/sbin/mount` run with a fixed
//! path, the C locale and no input. The daemon's NFS route (Attach tracking,
//! failed-unmount checks, reclaim) and the macOS driver's inspection reads
//! share it (layerfs-project#178 security rule 8, layerfs-project#136).
//! `mount` lists the kernel's table as it is (`getfsstat` with `MNT_NOWAIT`)
//! and asks no mounted server, so it is not expected to wait; the deadline is
//! for a host where it does.
use super::Retained;
use nix::fcntl::{fcntl, FcntlArg, OFlag};
use std::{
io::{self, Read},
process::{Command, Stdio},
sync::LazyLock,
time::{Duration, Instant},
};

const MOUNT: &str = "/sbin/mount";
/// How long one listing waits for `mount` to print the table.
const TABLE_WAIT: Duration = Duration::from_millis(500);
/// How long it then waits for a `mount` it killed to end.
const TABLE_REAP: Duration = Duration::from_millis(500);
/// The most of the table that is read.
const TABLE: usize = 1 << 20;
const PAUSE: Duration = Duration::from_millis(2);

/// Listings a KILL did not release; the shared retained queue reaps them.
static RETAINED: LazyLock<Retained> = LazyLock::new(Retained::default);

/// What `mount` prints. A run that takes longer than [`TABLE_WAIT`] is
/// killed and is an error, as is one that fails; a killed run whose exit is
/// not seen within [`TABLE_REAP`] goes to the retained queue.
pub fn mount_table() -> io::Result<String> {
RETAINED.reap();
let mut child = Command::new(MOUNT)
.env_clear()
.env("LC_ALL", "C")
.stdin(Stdio::null())
.stdout(Stdio::piped())
.stderr(Stdio::null())
.spawn()?;
// a pipe that cannot be read without waiting is not read
let mut pipe = child.stdout.take().and_then(|pipe| {
fcntl(&pipe, FcntlArg::F_SETFL(OFlag::O_NONBLOCK))
.ok()
.map(|_| pipe)
});
let mut text = Vec::new();
let mut read = |text: &mut Vec<u8>| {
let mut bytes = [0; 4096];
while let Some(Ok(count @ 1..)) = pipe.as_mut().map(|pipe| pipe.read(&mut bytes)) {
text.extend_from_slice(&bytes[..count.min(TABLE.saturating_sub(text.len()))]);
}
};
let deadline = Instant::now() + TABLE_WAIT;
let ended = loop {
read(&mut text);
match child.try_wait() {
Ok(Some(status)) => break Ok(status),
Ok(None) if Instant::now() < deadline => std::thread::sleep(PAUSE),
Ok(None) => {
break Err(io::Error::new(
io::ErrorKind::TimedOut,
"mount took too long",
))
}
Err(error) => break Err(error),
}
};
match ended {
Ok(status) if status.success() => {
read(&mut text);
Ok(String::from_utf8_lossy(&text).into_owned())
}
Ok(status) => Err(io::Error::other(format!("mount listing failed: {status}"))),
Err(error) => {
let pid = child.id();
let _ = child.kill();
let deadline = Instant::now() + TABLE_REAP;
let reaped = loop {
match child.try_wait() {
Ok(Some(status)) => break Some(status),
Ok(None) if Instant::now() < deadline => std::thread::sleep(PAUSE),
Ok(None) | Err(_) => break None,
}
};
match reaped {
Some(status) => RETAINED.record(pid, status),
None => RETAINED.retain(child),
}
Err(error)
}
}
}
Loading