vmette 0.5.0

Run untrusted agents in a hardware-isolated Linux microVM on macOS — a security boundary built on Apple's Virtualization.framework
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! Top-level [`run`] orchestration. `run` is a thin, CLI-facing wrapper
//! over a one-shot [`Session`]: it owns the terminal (raw mode + signal
//! handlers) and the user-visible banner, starts a session, blocks until
//! it ends, and exits the process with the guest's code.
//!
//! The VM lifecycle itself — building the config, the delegate, the vsock
//! listener, the timeout, and pumping the run loop — lives in
//! [`crate::session`] so it is reusable in-process (the daemon hosts many
//! sessions). `run` is the only place that calls `std::process::exit`, so
//! its happy path still never returns; the `Result<RunOutput, Error>`
//! shape is for setup errors (invalid config, snapshot unsupported, …).

use crate::error::Error;
use crate::session::{Session, SessionEnd};
use crate::terminal::{enter_raw_mode, install_signal_handlers, restore_terminal};
use crate::Config;

/// Result of a completed [`run`]. Currently only carries the exit code,
/// but kept as a struct so we can grow it without breaking callers.
#[derive(Debug, Clone, Copy)]
pub struct RunOutput {
    pub exit_code: i32,
}

/// Boot the configured guest, exec the command, block until poweroff,
/// then exit the process with the guest's exit code.
///
/// Note: on success the function does not return — it calls
/// `std::process::exit` once the session ends. The `Result<RunOutput, Error>`
/// shape is for error paths (config invalid, VM failed to start, snapshot
/// unsupported, etc).
pub fn run(config: &Config) -> Result<RunOutput, Error> {
    // Snapshot dispatch — both build and resume go through here.
    if let Some(p) = &config.build_snapshot {
        crate::vz::snapshot::build(config, p)?;
        return Ok(RunOutput { exit_code: 0 });
    }
    if let Some(p) = &config.resume_snapshot {
        let code = crate::vz::snapshot::resume(config, p)?;
        return Ok(RunOutput { exit_code: code });
    }

    install_signal_handlers();
    enter_raw_mode();

    // Start the session (creates + starts the VM but does not yet pump the
    // run loop). Print the banner before wait(): nothing services the VM's
    // queue between start() and wait(), so no guest serial output can race
    // ahead of the banner.
    let session = match Session::start(config) {
        Ok(s) => s,
        Err(e) => {
            // enter_raw_mode() already ran; don't leave the user's terminal raw.
            restore_terminal();
            return Err(e);
        }
    };
    if !config.quiet {
        eprint_banner(config, session.cmdline(), session.vsock_port());
    }

    let end = session.wait();
    restore_terminal();
    match end {
        SessionEnd::Exited(code) => {
            if !config.quiet {
                eprintln!("\r\n[vmette] guest stopped (exit {})\r", code);
            }
            std::process::exit(code);
        }
        SessionEnd::TimedOut => {
            if !config.quiet {
                eprintln!(
                    "\r\n[vmette] timeout {}s reached; guest force-stopped (exit 124)\r",
                    config.timeout_seconds.unwrap_or(0)
                );
            }
            std::process::exit(124);
        }
        SessionEnd::Stopped => {
            if !config.quiet {
                eprintln!("\r\n[vmette] guest stopped (exit 0)\r");
            }
            std::process::exit(0);
        }
        SessionEnd::Error(msg) => {
            // An error is always worth surfacing, even under --quiet.
            eprintln!("\r\n[vmette] guest stopped with error: {}\r", msg);
            std::process::exit(1);
        }
    }
}

fn eprint_banner(config: &Config, cmdline: &str, vsock_port: Option<u32>) {
    let rootfs = if let Some(rb) = &config.rootfs_block {
        format!("{} ({} block, ro)", rb.path.display(), rb.fstype)
    } else if let Some(r) = &config.rootfs_share {
        format!(
            "{}{}",
            r.path.display(),
            if r.read_only { " (ro)" } else { "" }
        )
    } else {
        "(none)".into()
    };
    let vsock = match vsock_port {
        None => "(disabled)".into(),
        Some(p) => p.to_string(),
    };
    eprintln!(
        "[vmette] kernel       {}\n\
         [vmette] initramfs    {}\n\
         [vmette] cmdline      {}\n\
         [vmette] rootfs       {}\n\
         [vmette] shares       {}\n\
         [vmette] disks        {}\n\
         [vmette] exec         {}\n\
         [vmette] vsock-port   {}\n\
         [vmette] switch-root  {}\n\
         [vmette] net          {}\n\
         [vmette] timeout      {}s\n\
         [vmette] vcpus        {}, memMiB {}\n",
        config.kernel.display(),
        config.initramfs.display(),
        cmdline,
        rootfs,
        config.shares.len(),
        config.disks.len(),
        config.exec_cmd.as_deref().unwrap_or("(none — interactive)"),
        vsock,
        if config.switch_root { "yes" } else { "no" },
        if config.net { "yes (NAT)" } else { "no" },
        config.timeout_seconds.unwrap_or(0),
        config.vcpus,
        config.mem_mib,
    );
}