phoebus_os/installer-rs/crates/phoebus-executor/src/snapshot.rs
2026-10-09 05:24:39 -07:00

535 lines
18 KiB
Rust

//! Btrfs snapshot creation and transaction history.
//!
//! Snapshots are read-only and live under the `@snapshots` subvolume
//! (`/.snapshots`). A record is appended to the history before the operation
//! and marked committed only afterwards. Real rollback (default-subvolume
//! switching plus `/boot` handling) is deliberately *not* implemented here; the
//! foundations are.
//!
//! `/home` is a separate subvolume and is intentionally not snapshotted by
//! default, so a future system rollback cannot discard user documents.
use std::path::{Path, PathBuf};
use phoebus_core::rollback::{
snapshot_retention_deletions, DEFAULT_KEEP_SNAPSHOTS, MIN_FREE_SPACE_BYTES,
};
use phoebus_core::snapshot::{snapshot_name, SnapshotHistory, SnapshotRecord, SnapshotStatus};
use crate::auth::DestructiveAuthorization;
use crate::command::CommandSpec;
use crate::error::{ExecError, Result};
use crate::exec::Exec;
pub const SNAPSHOT_DIR: &str = ".snapshots";
pub const HISTORY_REL: &str = "var/lib/phoebus/snapshot-history.toml";
/// The separately mounted `/var` subvolume holding package-manager state.
pub const VAR_SUBVOL: &str = "@var";
pub fn snapshots_path(root: &Path) -> PathBuf {
root.join(SNAPSHOT_DIR)
}
pub fn history_path(root: &Path) -> PathBuf {
root.join(HISTORY_REL)
}
/// Read the transaction history, surfacing a corrupt file instead of hiding it.
///
/// A missing or zero-length file is empty; anything else is an error so a
/// caller never mistakes an unreadable history for "no snapshots".
pub fn read_history(root: &Path) -> Result<SnapshotHistory> {
SnapshotHistory::load(&history_path(root)).map_err(ExecError::Core)
}
/// The transaction history, or a logged warning and the last-known-empty
/// history. Only for read paths that must not fail a `sys` query.
pub fn read_history_lossy(exec: &Exec, root: &Path) -> SnapshotHistory {
match read_history(root) {
Ok(history) => history,
Err(e) => {
exec.logger.warn(format!(
"snapshot history is unreadable: {e}; treating as unavailable"
));
SnapshotHistory::default()
}
}
}
pub fn write_history(root: &Path, history: &SnapshotHistory) -> Result<()> {
use std::os::unix::fs::PermissionsExt;
let target = phoebus_core::TargetRoot::new(root);
let text = toml::to_string_pretty(history)
.map_err(|e| ExecError::operation("snapshot", "serialize history", e.to_string()))?;
let path = target.write(HISTORY_REL, text)?;
// This contains snapshot identifiers/status, not credentials. `sys history`
// is a normal-user query; keep its metadata readable and root writable.
if let Some(parent) = path.parent() {
std::fs::set_permissions(parent, std::fs::Permissions::from_mode(0o755))
.map_err(|e| ExecError::io(parent.to_path_buf(), e))?;
}
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644))
.map_err(|e| ExecError::io(path, e))?;
Ok(())
}
fn now_unix() -> u64 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0)
}
/// Create a read-only snapshot of `source_subvol` (usually the mounted root).
pub fn create(
exec: &Exec,
_auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
operation: &str,
) -> Result<SnapshotRecord> {
let dir = snapshots_path(root);
std::fs::create_dir_all(&dir).map_err(|e| ExecError::io(dir.clone(), e))?;
let unix = now_unix();
let name = snapshot_name("@", unix, operation);
let dest = dir.join(&name);
exec.run(
CommandSpec::new("snapshot", format!("create snapshot {name}"), "btrfs")
.args(["subvolume", "snapshot", "-r"])
.arg(source_subvol)
.arg(dest.to_string_lossy().to_string()),
)?;
let record = SnapshotRecord {
id: name.clone(),
created_unix: unix,
operation: operation.to_string(),
source_subvol: source_subvol.to_string(),
snapshot_subvol: name,
var_snapshot: None,
status: SnapshotStatus::Created,
};
Ok(record)
}
/// Create a read-only snapshot of one source subvolume by explicit name.
pub fn create_named(
exec: &Exec,
_auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
name: &str,
) -> Result<()> {
let dir = snapshots_path(root);
std::fs::create_dir_all(&dir).map_err(|e| ExecError::io(dir.clone(), e))?;
let dest = dir.join(name);
exec.run(
CommandSpec::new("snapshot", format!("create snapshot {name}"), "btrfs")
.args(["subvolume", "snapshot", "-r"])
.arg(source_subvol)
.arg(dest.to_string_lossy().to_string()),
)?;
Ok(())
}
/// Snapshot the mounted root and, when `/var` is a separate Btrfs subvolume,
/// its `/var` volume under the same timestamp/operation name.
///
/// `/home` is intentionally excluded so a system rollback cannot discard user
/// documents.
pub fn create_set(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
operation: &str,
) -> Result<SnapshotRecord> {
let var_source = if var_is_separate_subvol(root) {
Some("/var")
} else {
None
};
create_set_at(exec, auth, root, source_subvol, var_source, operation)
}
/// As `create_set`, but with an explicit `/var` source so the installer can
/// capture the target's `@var` (whose mount point is not the host `/var`).
pub fn create_set_at(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
var_source: Option<&str>,
operation: &str,
) -> Result<SnapshotRecord> {
let unix = now_unix();
let name = snapshot_name("@", unix, operation);
create_named(exec, auth, root, source_subvol, &name)?;
let var_snapshot = match var_source {
Some(source) => {
let var_name = snapshot_name("@var", unix, operation);
create_named(exec, auth, root, source, &var_name)?;
Some(var_name)
}
None => None,
};
Ok(SnapshotRecord {
id: name.clone(),
created_unix: unix,
operation: operation.to_string(),
source_subvol: source_subvol.to_string(),
snapshot_subvol: name,
var_snapshot,
status: SnapshotStatus::Created,
})
}
/// Whether `/var` is a separate Btrfs subvolume of the running system.
///
/// `/home` and `/var` are separate subvolumes in the proven layout. A target
/// root that is not the running `/` (the installer) has no separate `/var`, and
/// tests use a temporary directory, so this is false there.
pub fn var_is_separate_subvol(root: &Path) -> bool {
if root != Path::new("/") {
return false;
}
match std::fs::read_to_string("/proc/self/mountinfo") {
Ok(text) => parse_mountinfo_var(&text),
Err(_) => false,
}
}
/// Pure parser used by `var_is_separate_subvol` so the decision is testable.
pub fn parse_mountinfo_var(text: &str) -> bool {
for line in text.lines() {
// mountinfo: id parent maj:min root mountpoint opts... - fstype source ...
let fields: Vec<&str> = line.split_whitespace().collect();
let Some(sep) = fields.iter().position(|f| *f == "-") else {
continue;
};
let mountpoint = fields.get(4).copied();
let fstype = fields.get(sep + 1).copied();
if mountpoint == Some("/var") && fstype == Some("btrfs") {
return true;
}
}
false
}
/// Create a snapshot set and record it as committed in the history.
pub fn create_set_and_record(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
operation: &str,
) -> Result<SnapshotRecord> {
create_set_and_record_at(exec, auth, root, source_subvol, None, operation)
}
/// As `create_set_and_record`, with an explicit `/var` source (installer).
pub fn create_set_and_record_at(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
var_source: Option<&str>,
operation: &str,
) -> Result<SnapshotRecord> {
let mut record = if var_source.is_some() {
create_set_at(exec, auth, root, source_subvol, var_source, operation)?
} else {
create_set(exec, auth, root, source_subvol, operation)?
};
record.status = SnapshotStatus::Committed;
let mut history = read_history(root)?;
history.append(record.clone());
write_history(root, &history)?;
exec.logger
.info(format!("snapshot committed: {}", record.id));
Ok(record)
}
/// Create a snapshot and record it as committed in the history.
///
/// This captures the root and the separately mounted `/var` together so a
/// restored system has consistent package-manager state.
pub fn create_and_record(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
operation: &str,
) -> Result<SnapshotRecord> {
create_set_and_record(exec, auth, root, source_subvol, operation)
}
pub fn list(_exec: &Exec, root: &Path) -> Result<Vec<String>> {
let dir = snapshots_path(root);
if !dir.is_dir() {
return Ok(Vec::new());
}
let mut names: Vec<String> = std::fs::read_dir(&dir)
.map_err(|e| ExecError::io(dir.clone(), e))?
.flatten()
.map(|e| e.file_name().to_string_lossy().to_string())
.collect();
names.sort();
Ok(names)
}
pub fn delete(exec: &Exec, _auth: &DestructiveAuthorization, root: &Path, id: &str) -> Result<()> {
let target = snapshots_path(root).join(id);
exec.run(
CommandSpec::new("snapshot", format!("delete snapshot {id}"), "btrfs")
.args(["subvolume", "delete"])
.arg(target.to_string_lossy().to_string()),
)?;
Ok(())
}
/// Parse the available-bytes figure from `df -B1 --output=avail` output.
pub fn parse_df_avail(text: &str) -> Option<u64> {
text.lines()
.rev()
.find_map(|line| line.trim().parse::<u64>().ok())
}
/// Free bytes on the filesystem backing `path`, or an error if it cannot be
/// determined. A rollback refuses to run when space cannot be checked.
pub fn free_space_bytes(exec: &Exec, path: &Path) -> Result<u64> {
let out = exec.run_capture(
CommandSpec::new("snapshot", "check free space", "df")
.args(["-B1", "--output=avail"])
.arg(path.to_string_lossy().to_string()),
)?;
parse_df_avail(&out.stdout_lossy()).ok_or_else(|| {
ExecError::operation(
"snapshot",
"check free space",
format!("could not parse df output for {}", path.display()),
)
})
}
/// Require at least `min_bytes` free before a space-consuming operation.
pub fn require_free_space(exec: &Exec, path: &Path, min_bytes: u64) -> Result<u64> {
let avail = free_space_bytes(exec, path)?;
if avail < min_bytes {
return Err(ExecError::operation(
"snapshot",
"check free space",
format!(
"only {avail} bytes free on {}; {min_bytes} required",
path.display()
),
));
}
Ok(avail)
}
/// Prune committed snapshots beyond `keep`, protecting the latest and any
/// in-flight rollback target. Returns the ids that were deleted.
pub fn apply_retention(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
) -> Result<Vec<String>> {
apply_retention_with(exec, auth, root, DEFAULT_KEEP_SNAPSHOTS, &[])
}
pub fn apply_retention_with(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
keep: usize,
protect: &[String],
) -> Result<Vec<String>> {
let history = read_history(root)?;
let deletions = snapshot_retention_deletions(&history, keep, protect);
if deletions.is_empty() {
return Ok(Vec::new());
}
for id in &deletions {
if let Some(record) = history.records.iter().find(|r| &r.id == id) {
if let Some(var) = &record.var_snapshot {
let _ = delete(exec, auth, root, var);
}
}
delete(exec, auth, root, id)?;
exec.logger.info(format!("pruned snapshot {id}"));
}
// Drop the pruned records from the history so it stays truthful.
let mut pruned = SnapshotHistory::default();
for record in history.records {
if !deletions.contains(&record.id) {
pruned.append(record);
}
}
write_history(root, &pruned)?;
Ok(deletions)
}
/// The minimum free space a rollback requires.
pub fn rollback_space_requirement() -> u64 {
MIN_FREE_SPACE_BYTES
}
#[cfg(test)]
mod tests {
use super::*;
use crate::command::RecordingRunner;
use crate::log::Logger;
use phoebus_core::Redactor;
fn make_exec(runner: RecordingRunner) -> Exec {
let path = tempfile::tempdir().unwrap().keep();
let logger = Logger::open(path.join("l.log"), Redactor::new(), false);
Exec::new(Box::new(runner), logger, false, path.join("root"), path)
}
#[test]
fn snapshot_metadata_remains_readable_after_private_bootstrap() {
use std::os::unix::fs::PermissionsExt;
let exec = make_exec(RecordingRunner::new());
let path = history_path(&exec.root);
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(&path, "").unwrap();
std::fs::set_permissions(
path.parent().unwrap(),
std::fs::Permissions::from_mode(0o700),
)
.unwrap();
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).unwrap();
write_history(&exec.root, &SnapshotHistory::default()).unwrap();
assert_eq!(
std::fs::metadata(&path).unwrap().permissions().mode() & 0o777,
0o644
);
assert_eq!(
std::fs::metadata(path.parent().unwrap())
.unwrap()
.permissions()
.mode()
& 0o777,
0o755
);
assert!(read_history(&exec.root).unwrap().records.is_empty());
}
#[test]
fn create_uses_readonly_btrfs_snapshot() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
let auth = crate::auth::authorize(&crate::auth::AutoConfirm, "p", "f").unwrap();
let record = create(&exec, &auth, Path::new(&exec.root), "/", "sys update").unwrap();
assert_eq!(record.status, SnapshotStatus::Created);
let spec = &runner.recorded()[0];
assert_eq!(spec.program, "btrfs");
assert_eq!(&spec.args[0..3], &["subvolume", "snapshot", "-r"]);
assert!(spec.args.iter().any(|a| a.contains(".snapshots")));
}
#[test]
fn create_and_record_commits_history() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
let auth = crate::auth::authorize(&crate::auth::AutoConfirm, "p", "f").unwrap();
let record = create_and_record(&exec, &auth, Path::new(&exec.root), "/", "risk").unwrap();
assert_eq!(record.status, SnapshotStatus::Committed);
let history = read_history(Path::new(&exec.root)).unwrap();
assert_eq!(history.records.len(), 1);
assert_eq!(history.latest().unwrap().id, record.id);
}
#[test]
fn corrupt_history_is_surfaced() {
let runner = RecordingRunner::new();
let exec = make_exec(runner);
let history_path = history_path(Path::new(&exec.root));
std::fs::create_dir_all(history_path.parent().unwrap()).unwrap();
std::fs::write(&history_path, "not = = toml [[[").unwrap();
assert!(read_history(Path::new(&exec.root)).is_err());
// The lossy variant keeps read paths working but does not pretend the
// history was empty.
let lossy = read_history_lossy(&exec, Path::new(&exec.root));
assert!(lossy.records.is_empty());
}
#[test]
fn coordinated_snapshot_captures_var_when_explicit() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
let auth = crate::auth::authorize(&crate::auth::AutoConfirm, "p", "f").unwrap();
let record = create_set_at(
&exec,
&auth,
Path::new(&exec.root),
"/mnt/phoebus",
Some("/mnt/phoebus/var"),
"sys update",
)
.unwrap();
assert!(record.var_snapshot.is_some());
let args: Vec<String> = runner
.recorded()
.iter()
.flat_map(|s| s.args.clone())
.collect();
assert!(args.iter().any(|a| a.contains("@var")));
}
#[test]
fn df_avail_parser_takes_the_last_numeric_line() {
assert_eq!(parse_df_avail("Avail\n1073741824\n"), Some(1_073_741_824));
assert_eq!(parse_df_avail("10\n20\n30\n"), Some(30));
assert_eq!(parse_df_avail("no numbers here\n"), None);
}
#[test]
fn mountinfo_detects_a_separate_var() {
let line = "25 30 0:23 / /var rw,relatime - btrfs /dev/vda2 rw,subvolid=258,subvol=/@var";
assert!(parse_mountinfo_var(line));
assert!(!parse_mountinfo_var(
"1 0 8:1 / / ext4 rw - ext4 /dev/sda1 rw"
));
}
#[test]
fn retention_prunes_old_committed_and_rewrites_history() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
let auth = crate::auth::authorize(&crate::auth::AutoConfirm, "p", "f").unwrap();
let root = Path::new(&exec.root);
let mut history = SnapshotHistory::default();
for i in 0..4u64 {
history.append(SnapshotRecord {
id: format!("@-{i}"),
created_unix: i,
operation: "op".into(),
source_subvol: "@".into(),
snapshot_subvol: format!("@-{i}"),
var_snapshot: Some(format!("@var-{i}")),
status: SnapshotStatus::Committed,
});
}
// Materialise the snapshot directories so existence is realistic.
let dir = snapshots_path(root);
for i in 0..4u64 {
std::fs::create_dir_all(dir.join(format!("@-{i}"))).unwrap();
std::fs::create_dir_all(dir.join(format!("@var-{i}"))).unwrap();
}
write_history(root, &history).unwrap();
let deletions = apply_retention_with(&exec, &auth, root, 2, &[]).unwrap();
assert_eq!(deletions, vec!["@-0", "@-1"]);
let after = read_history(root).unwrap();
assert_eq!(after.records.len(), 2);
assert!(!after.records.iter().any(|r| r.id == "@-0"));
}
#[test]
fn space_and_retention_constants_are_sane() {
assert!(rollback_space_requirement() >= 512 * 1024 * 1024);
}
}