From 61e10a6e97ac791ab11b5f877d90360437e4c1e9 Mon Sep 17 00:00:00 2001 From: rsclarke Date: Mon, 4 May 2026 13:05:36 +0800 Subject: [PATCH 01/57] perf(proxy): raise smoltcp TCP buffers to 4 MiB With TCP window scaling (RFC 1323), 4 MiB rx/tx ring buffers lift the Bandwidth-Delay Product ceiling from ~2 MB/s (at the previous 64 KiB) to ~70 MB/s at 50 ms RTT. This change is a prerequisite for the BDP gain from the upcoming event-driven poll loop; in isolation it does not move throughput because the 1 ms thread::sleep poll loop bounds the smoltcp \xe2\x86\x94 guest internal RTT before the receive window matters. --- crates/shuru-proxy/src/stack.rs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/crates/shuru-proxy/src/stack.rs b/crates/shuru-proxy/src/stack.rs index 50aadc8..c34a0bf 100644 --- a/crates/shuru-proxy/src/stack.rs +++ b/crates/shuru-proxy/src/stack.rs @@ -21,8 +21,11 @@ const PREFIX_LEN: u8 = 24; /// Gateway MAC address (locally administered). const GATEWAY_MAC: EthernetAddress = EthernetAddress([0x02, 0x00, 0x00, 0x00, 0x00, 0x01]); -const TCP_RX_BUF_SIZE: usize = 65536; -const TCP_TX_BUF_SIZE: usize = 65536; +// 4 MiB per direction: with TCP window scaling (RFC 1323) this lifts the +// Bandwidth-Delay Product ceiling to ~70 MB/s at 50 ms RTT. Each established +// connection costs (RX + TX) of host RAM in smoltcp ring buffers. +const TCP_RX_BUF_SIZE: usize = 4 * 1024 * 1024; +const TCP_TX_BUF_SIZE: usize = 4 * 1024 * 1024; /// A new TCP connection from the guest, ready to be proxied. pub struct TcpConnection { From c66dc573c075718d3d945cf4410e659d13a0eb91 Mon Sep 17 00:00:00 2001 From: rsclarke Date: Mon, 4 May 2026 14:17:32 +0800 Subject: [PATCH 02/57] perf(proxy): replace sleep-driven poll with AsyncFd select loop The smoltcp poll loop previously slept on a 1 ms timer between iterations, which inflated the smoltcp <-> guest internal RTT and capped in-VM throughput at ~1 MB/s regardless of buffer sizes. Real network RTT to a CDN is tens of milliseconds, but the sleep added a ~1 ms floor that prevented smoltcp's congestion window from opening past a single MTU per round. Replace the dedicated thread's blocking sleep loop with a Tokio current-thread runtime hosting an AsyncFd-based select! over: 1. Host AF_UNIX FD readability (frame from guest) 2. cmd_rx.recv() (StackCommand from proxy engine) 3. sleep_until(poll_delay) (smoltcp's own retransmit / delayed ACK) This keeps the netstack on its own OS thread (so a busy smoltcp poll cannot starve the proxy's TLS / DNS / MITM workers on the shared multi-thread runtime) while making it react in microseconds instead of milliseconds. The 1 ms floor and 50 ms clamp on poll_delay are removed; the loop now honors smoltcp's timer exactly, including Some(0) which means continue immediately. Burst commands are coalesced via try_recv after each recv().await wake. device.rs surfaces a DrainStatus { WouldBlock | HitCap | Error } so the loop can avoid awaiting when the kernel buffer still has frames (cap hit) and can correctly hand off readiness to AsyncFd otherwise. The host FD remains in blocking mode for sends; reads continue to use MSG_DONTWAIT so AsyncFd's readable() never resolves into a blocking read. Measured throughput on a 90 MB Cloudflare speed-test download (speed.cloudflare.com/__down?bytes=90000000): ~1.12 MB/s -> ~65 MB/s (~58x), reaching ~66% of host-native throughput on the same network. Proxy CPU rises from ~3% (sleep-bound) to ~15% (actual work). --- crates/shuru-proxy/src/device.rs | 78 +++++++++++-- crates/shuru-proxy/src/stack.rs | 181 ++++++++++++++++++++++--------- 2 files changed, 194 insertions(+), 65 deletions(-) diff --git a/crates/shuru-proxy/src/device.rs b/crates/shuru-proxy/src/device.rs index 6f7d3ed..109e250 100644 --- a/crates/shuru-proxy/src/device.rs +++ b/crates/shuru-proxy/src/device.rs @@ -1,4 +1,5 @@ use std::collections::VecDeque; +use std::io; use std::os::unix::io::RawFd; use smoltcp::phy::{self, Checksum, Device, DeviceCapabilities, Medium}; @@ -7,6 +8,31 @@ use smoltcp::time::Instant; const MTU: usize = 1514; // 14-byte Ethernet header + 1500-byte IP payload const MAX_PENDING_FRAMES: usize = 256; +/// Result of pulling a single frame from the host AF_UNIX socket. +enum RecvOne { + /// A frame was read into the buffer. + Frame(Vec), + /// `recv()` returned `EAGAIN`/`EWOULDBLOCK`: the socket is fully drained. + WouldBlock, + /// `recv()` returned a real error or 0-byte EOF. + Error(io::Error), +} + +/// Outcome of [`VZDevice::drain_recv`]. Drives readiness bookkeeping in the +/// event-driven poll loop: we may only `clear_ready()` on the host FD when +/// the kernel has actually told us `WouldBlock`. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum DrainStatus { + /// Drained until `recv()` returned `EWOULDBLOCK` — no more frames. + WouldBlock, + /// Stopped early because `pending_rx` reached `MAX_PENDING_FRAMES`. The + /// kernel buffer may still hold data; the loop must re-poll without + /// clearing FD readiness. + HitCap, + /// `recv()` returned an error (other than `EWOULDBLOCK`) or EOF. + Error, +} + /// smoltcp Device backed by a Unix datagram socketpair fd. /// /// One end of the socketpair is given to VZFileHandleNetworkDeviceAttachment @@ -28,8 +54,20 @@ impl VZDevice { } } + /// The host end of the AF_UNIX socketpair. Used by the network stack to + /// register readiness with the async runtime. + pub fn fd(&self) -> RawFd { + self.fd + } + + /// Whether any pre-read frames are still queued for smoltcp to consume. + pub fn pending_rx_empty(&self) -> bool { + self.pending_rx.is_empty() + } + /// Non-blocking read of a single frame from the socketpair. - fn recv_one_frame(&mut self) -> Option> { + /// Distinguishes "no data right now" (`WouldBlock`) from real errors. + fn recv_one_frame(&mut self) -> RecvOne { let n = unsafe { libc::recv( self.fd, @@ -38,10 +76,18 @@ impl VZDevice { libc::MSG_DONTWAIT, ) }; - if n <= 0 { - return None; + if n > 0 { + return RecvOne::Frame(self.recv_buf[..n as usize].to_vec()); + } + if n == 0 { + return RecvOne::Error(io::Error::new(io::ErrorKind::UnexpectedEof, "fd closed")); + } + let err = io::Error::last_os_error(); + // On Darwin/Linux EAGAIN == EWOULDBLOCK; match on the value once. + match err.raw_os_error() { + Some(libc::EAGAIN) => RecvOne::WouldBlock, + _ => RecvOne::Error(err), } - Some(self.recv_buf[..n as usize].to_vec()) } /// Drain all available frames from the socketpair (non-blocking). @@ -51,14 +97,19 @@ impl VZDevice { /// DNS (UDP 53). Without this filter, smoltcp auto-replies to ICMP /// echo requests for any IP (due to any_ip=true), which leaks a /// response channel even though no data actually reaches the internet. - pub fn drain_recv(&mut self) { + pub fn drain_recv(&mut self) -> DrainStatus { while self.pending_rx.len() < MAX_PENDING_FRAMES { match self.recv_one_frame() { - Some(frame) if Self::is_icmp(&frame) => continue, - Some(frame) => self.pending_rx.push_back(frame), - None => break, + RecvOne::Frame(frame) if Self::is_icmp(&frame) => continue, + RecvOne::Frame(frame) => self.pending_rx.push_back(frame), + RecvOne::WouldBlock => return DrainStatus::WouldBlock, + RecvOne::Error(e) => { + tracing::debug!("host_fd recv error: {e}"); + return DrainStatus::Error; + } } } + DrainStatus::HitCap } /// Check if a raw Ethernet frame carries an ICMP packet. @@ -124,10 +175,13 @@ impl Device for VZDevice { // socketpair for frames that arrived during poll. Drop ICMP in both // paths to match the filter in drain_recv(). loop { - let buffer = self - .pending_rx - .pop_front() - .or_else(|| self.recv_one_frame())?; + let buffer = match self.pending_rx.pop_front() { + Some(b) => b, + None => match self.recv_one_frame() { + RecvOne::Frame(b) => b, + RecvOne::WouldBlock | RecvOne::Error(_) => return None, + }, + }; if Self::is_icmp(&buffer) { continue; } diff --git a/crates/shuru-proxy/src/stack.rs b/crates/shuru-proxy/src/stack.rs index c34a0bf..1686588 100644 --- a/crates/shuru-proxy/src/stack.rs +++ b/crates/shuru-proxy/src/stack.rs @@ -10,10 +10,12 @@ use smoltcp::wire::{ EthernetAddress, EthernetFrame, HardwareAddress, IpAddress, IpCidr, IpEndpoint, IpListenEndpoint, Ipv4Address, Ipv4Packet, TcpPacket, }; +use tokio::io::unix::AsyncFd; +use tokio::io::Interest; use tokio::sync::mpsc; use tracing::{debug, warn}; -use crate::device::VZDevice; +use crate::device::{DrainStatus, VZDevice}; /// Gateway IP inside the virtual network (host-side smoltcp). pub const GATEWAY_IP: Ipv4Address = Ipv4Address::new(10, 0, 0, 1); @@ -134,73 +136,135 @@ impl NetworkStack { } } - /// Run the poll loop. Blocks the current thread. + /// Run the poll loop. Blocks the current thread until the proxy engine + /// drops `cmd_tx` or the host FD closes. + /// + /// Internally this hosts a Tokio current-thread runtime so the loop can + /// `select!` over (a) host FD readiness via [`AsyncFd`], (b) commands on + /// `cmd_rx`, and (c) smoltcp's own timer (`poll_delay`). This replaces a + /// previous `thread::sleep(1ms)` busy-wait that bounded the smoltcp ↔ + /// guest internal RTT and capped throughput at ~1 MB/s regardless of + /// buffer sizes. pub fn run(&mut self) { - loop { - self.process_commands(); + let rt = tokio::runtime::Builder::new_current_thread() + .enable_io() + .enable_time() + .build() + .expect("failed to build current-thread runtime for netstack"); + rt.block_on(self.run_async()); + } - // Drain all available frames and inspect for TCP SYN - self.device.drain_recv(); - self.inspect_pending_frames(); + async fn run_async(&mut self) { + let async_fd = match AsyncFd::with_interest(self.device.fd(), Interest::READABLE) { + Ok(fd) => fd, + Err(e) => { + warn!("AsyncFd registration failed for host_fd: {e}"); + return; + } + }; + loop { + // Synchronous work phase: drain everything available right now. + // (Commands are drained inside the select! arm so they share a + // single waker; this top-of-loop drain is just for frames.) + let drain_status = self.device.drain_recv(); + self.inspect_pending_frames(); self.iface .poll(Self::now(), &mut self.device, &mut self.sockets); - self.poll_tcp_sockets(); self.drain_pending_sends(); self.poll_dns_socket(); - let delay = self - .iface - .poll_delay(Self::now(), &self.sockets) - .map(|d| { - let micros = d.total_micros(); - if micros == 0 { - std::time::Duration::from_millis(1) - } else { - std::time::Duration::from_micros(micros.min(50_000)) - } - }) - .unwrap_or(std::time::Duration::from_millis(1)); + let poll_delay = self.iface.poll_delay(Self::now(), &self.sockets); + + // If there is still local work, do not await — loop immediately. + // This covers: drain stopped at MAX_PENDING_FRAMES with the + // kernel buffer still non-empty, smoltcp wants an immediate + // re-poll, or pre-read frames remain queued (e.g. produced by + // smoltcp itself during the previous poll). + let immediate = matches!(drain_status, DrainStatus::HitCap) + || !self.device.pending_rx_empty() + || matches!(poll_delay, Some(d) if d.total_micros() == 0); + if immediate { + tokio::task::yield_now().await; + continue; + } - std::thread::sleep(delay); + // Convert smoltcp's poll_delay into a tokio sleep deadline. + let sleep_micros = poll_delay.map(|d| d.total_micros()); + + tokio::select! { + biased; + // (1) Frame arrived from guest. + ready = async_fd.readable() => { + match ready { + Ok(mut guard) => { + // Acknowledge readiness; the next loop iteration + // will drain via MSG_DONTWAIT. If we are wrong and + // the FD isn't really readable yet, drain_recv() + // will return WouldBlock and we re-await. + guard.clear_ready(); + } + Err(e) => { + warn!("AsyncFd readable error: {e}"); + return; + } + } + } + // (2) Command arrived from proxy engine. Drain the rest with + // try_recv() so a burst of commands costs one wake. + maybe_cmd = self.cmd_rx.recv() => { + match maybe_cmd { + Some(cmd) => { + self.handle_command(cmd); + while let Ok(cmd) = self.cmd_rx.try_recv() { + self.handle_command(cmd); + } + } + None => { + // Proxy engine dropped its cmd_tx — shut down. + return; + } + } + } + // (3) smoltcp's own timer (retransmit / delayed ACK). + _ = sleep_or_pending(sleep_micros) => {} + } } } - fn process_commands(&mut self) { - while let Ok(cmd) = self.cmd_rx.try_recv() { - match cmd { - StackCommand::Send { id, payload } => { - // Ignore sends for connections already removed by poll_tcp_sockets - if !self.connections.contains_key(&id.0) { - continue; - } - self.pending_send.entry(id.0).or_default().extend(&payload); + fn handle_command(&mut self, cmd: StackCommand) { + match cmd { + StackCommand::Send { id, payload } => { + // Ignore sends for connections already removed by poll_tcp_sockets + if !self.connections.contains_key(&id.0) { + return; } - StackCommand::Close { id } => { - // Connection may have already been cleaned up by poll_tcp_sockets - if !self.connections.contains_key(&id.0) { - self.pending_send.remove(&id.0); - self.closing.remove(&id.0); - continue; - } - // Defer close until pending_send is drained so we don't - // drop data that hasn't been pushed to smoltcp yet. - if self.pending_send.get(&id.0).map_or(true, |p| p.is_empty()) { - // Nothing pending — close immediately - let socket = self.sockets.get_mut::(id.0); - socket.close(); - self.connections.remove(&id.0); - self.pending_send.remove(&id.0); - } else { - self.closing.insert(id.0); - } + self.pending_send.entry(id.0).or_default().extend(&payload); + } + StackCommand::Close { id } => { + // Connection may have already been cleaned up by poll_tcp_sockets + if !self.connections.contains_key(&id.0) { + self.pending_send.remove(&id.0); + self.closing.remove(&id.0); + return; } - StackCommand::DnsResponse { dst, payload } => { - let socket = self.sockets.get_mut::(self.dns_handle); - if let Err(e) = socket.send_slice(&payload, dst) { - warn!("failed to send DNS response: {e}"); - } + // Defer close until pending_send is drained so we don't + // drop data that hasn't been pushed to smoltcp yet. + if self.pending_send.get(&id.0).map_or(true, |p| p.is_empty()) { + // Nothing pending — close immediately + let socket = self.sockets.get_mut::(id.0); + socket.close(); + self.connections.remove(&id.0); + self.pending_send.remove(&id.0); + } else { + self.closing.insert(id.0); + } + } + StackCommand::DnsResponse { dst, payload } => { + let socket = self.sockets.get_mut::(self.dns_handle); + if let Err(e) = socket.send_slice(&payload, dst) { + warn!("failed to send DNS response: {e}"); } } } @@ -401,3 +465,14 @@ impl NetworkStack { Instant::from_micros(ts.as_micros() as i64) } } + +/// Sleep for `micros` microseconds, or never resolve if `None`. +/// Used as the third arm of `select!` so the loop wakes when smoltcp's own +/// timer fires (delayed ACK / retransmit) but stays asleep otherwise. +async fn sleep_or_pending(micros: Option) { + match micros { + Some(0) => {} // immediate; loop will continue without awaiting wakers + Some(us) => tokio::time::sleep(std::time::Duration::from_micros(us)).await, + None => std::future::pending::<()>().await, + } +} From a8914eed7dacb09371fa7f3959e4ed5135a28d6b Mon Sep 17 00:00:00 2001 From: rsclarke Date: Mon, 4 May 2026 14:17:51 +0800 Subject: [PATCH 03/57] perf(proxy): raise host_fd ingress cap from 256 to 4096 frames With the sleep-driven poll loop replaced by an event-driven select loop, the 256-frame ingress cap no longer prevents kernel buffer drops (the loop wakes immediately on FD readability), but it still fragments a full 4 MiB BDP burst (~2 800 frames) across ~11 mini-poll cycles. Each cycle runs a complete iface.poll, socket walk, drain_pending_sends and DNS poll over what is effectively the same data window. Raising the cap to 4096 lets a typical BDP-sized burst fit in a single batch: - one smoltcp poll instead of ~11 - one ACK round (better cwnd growth) instead of ~11 - less HashMap churn in inspect_pending_frames - HitCap returns to being a real backstop for runaway flows rather than the steady-state path Memory is bounded by MAX_PENDING_FRAMES * MTU = 4096 * 1514 ~ 6 MiB transient, freed each poll cycle, well below the existing kernel SO_RCVBUF (4 MiB) ceiling. Measured impact at this stage is small (within trial-to-trial noise on the 90 MB Cloudflare workload) because the next binding constraint is per-frame syscall and allocation overhead in the RX path. The real value of this commit is correctness/clarity: HitCap is now a genuine backstop for runaway flows rather than the steady-state path. --- crates/shuru-proxy/src/device.rs | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/crates/shuru-proxy/src/device.rs b/crates/shuru-proxy/src/device.rs index 109e250..89d5bea 100644 --- a/crates/shuru-proxy/src/device.rs +++ b/crates/shuru-proxy/src/device.rs @@ -6,7 +6,13 @@ use smoltcp::phy::{self, Checksum, Device, DeviceCapabilities, Medium}; use smoltcp::time::Instant; const MTU: usize = 1514; // 14-byte Ethernet header + 1500-byte IP payload -const MAX_PENDING_FRAMES: usize = 256; +// Sized to comfortably hold a full 4 MiB BDP burst (≈ 2 800 frames) in a +// single drain, so smoltcp processes it as one batch (one ACK round, one +// socket walk) instead of fragmenting across many poll iterations. The +// upper bound on memory is `MAX_PENDING_FRAMES × MTU` ≈ 6 MiB transient, +// freed each poll cycle. Real ceiling on RX is the kernel SO_RCVBUF (4 MiB) +// set in `lib.rs::create_socketpair`. +const MAX_PENDING_FRAMES: usize = 4096; /// Result of pulling a single frame from the host AF_UNIX socket. enum RecvOne { From d3d773cc6f6cb8b0ba6654f268cbeca9f1fdf64c Mon Sep 17 00:00:00 2001 From: rsclarke Date: Mon, 4 May 2026 13:15:47 +0800 Subject: [PATCH 04/57] test(proxy): cover VZDevice::drain_recv status semantics Add focused unit tests for the new DrainStatus return type added with the event-driven poll loop: - drain_recv_returns_wouldblock_on_empty_fd - drain_recv_accumulates_non_icmp_frames - drain_recv_discards_icmp_frames - drain_recv_returns_hit_cap_when_pending_rx_fills A small RAII Pair helper wraps an AF_UNIX SOCK_DGRAM socketpair with generous send/recv buffers so the cap test can queue >MAX_PENDING_FRAMES datagrams without blocking. Tests run synchronously (drain_recv is sync, relies on MSG_DONTWAIT) so they need no tokio runtime. --- crates/shuru-proxy/src/device.rs | 112 +++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/crates/shuru-proxy/src/device.rs b/crates/shuru-proxy/src/device.rs index 89d5bea..a660a35 100644 --- a/crates/shuru-proxy/src/device.rs +++ b/crates/shuru-proxy/src/device.rs @@ -262,4 +262,116 @@ mod tests { assert!(!VZDevice::is_icmp(&[])); assert!(!VZDevice::is_icmp(&[0u8; 23])); // too short to read proto field } + + /// RAII socketpair: `(host_fd, peer_fd)` closed on drop. The host_fd is + /// the end given to a `VZDevice`; the peer_fd is the test driver's end. + struct Pair { + host_fd: RawFd, + peer_fd: RawFd, + } + + impl Pair { + fn new() -> Self { + let mut fds = [0i32; 2]; + let r = unsafe { + libc::socketpair(libc::AF_UNIX, libc::SOCK_DGRAM, 0, fds.as_mut_ptr()) + }; + assert_eq!(r, 0, "socketpair failed"); + // Generous buffer so we can queue >MAX_PENDING_FRAMES frames. + let bufsize: libc::c_int = 16 * 1024 * 1024; + for fd in fds.iter() { + unsafe { + libc::setsockopt( + *fd, + libc::SOL_SOCKET, + libc::SO_SNDBUF, + &bufsize as *const _ as _, + std::mem::size_of::() as _, + ); + libc::setsockopt( + *fd, + libc::SOL_SOCKET, + libc::SO_RCVBUF, + &bufsize as *const _ as _, + std::mem::size_of::() as _, + ); + } + } + Pair { + host_fd: fds[1], + peer_fd: fds[0], + } + } + + fn send(&self, frame: &[u8]) { + let n = unsafe { + libc::send( + self.peer_fd, + frame.as_ptr() as *const libc::c_void, + frame.len(), + 0, + ) + }; + assert!(n > 0, "send failed: {}", std::io::Error::last_os_error()); + } + } + + impl Drop for Pair { + fn drop(&mut self) { + unsafe { + libc::close(self.host_fd); + libc::close(self.peer_fd); + } + } + } + + #[test] + fn drain_recv_returns_wouldblock_on_empty_fd() { + let pair = Pair::new(); + let mut device = VZDevice::new(pair.host_fd); + assert_eq!(device.drain_recv(), DrainStatus::WouldBlock); + assert!(device.pending_rx_empty()); + } + + #[test] + fn drain_recv_accumulates_non_icmp_frames() { + let pair = Pair::new(); + let frame = make_frame(6); // TCP + for _ in 0..3 { + pair.send(&frame); + } + let mut device = VZDevice::new(pair.host_fd); + assert_eq!(device.drain_recv(), DrainStatus::WouldBlock); + assert_eq!(device.pending_rx.len(), 3); + } + + #[test] + fn drain_recv_discards_icmp_frames() { + let pair = Pair::new(); + pair.send(&make_frame(1)); // ICMP — should be dropped + pair.send(&make_frame(6)); // TCP — should be kept + pair.send(&make_frame(1)); // ICMP — should be dropped + pair.send(&make_frame(17)); // UDP — should be kept + let mut device = VZDevice::new(pair.host_fd); + assert_eq!(device.drain_recv(), DrainStatus::WouldBlock); + assert_eq!(device.pending_rx.len(), 2); + } + + #[test] + fn drain_recv_returns_hit_cap_when_pending_rx_fills() { + let pair = Pair::new(); + let frame = make_frame(6); // TCP + // Send slightly more than MAX_PENDING_FRAMES so HitCap is unambiguous. + for _ in 0..(MAX_PENDING_FRAMES + 16) { + pair.send(&frame); + } + let mut device = VZDevice::new(pair.host_fd); + assert_eq!(device.drain_recv(), DrainStatus::HitCap); + assert_eq!(device.pending_rx.len(), MAX_PENDING_FRAMES); + // A second drain should pick up the rest and end at WouldBlock. + device.pending_rx.clear(); + let status = device.drain_recv(); + assert!(matches!(status, DrainStatus::WouldBlock | DrainStatus::HitCap)); + } + } From dfcbdbf4b7c9b0a00f235126457b038a058106ba Mon Sep 17 00:00:00 2001 From: rsclarke Date: Mon, 4 May 2026 16:15:21 +0800 Subject: [PATCH 05/57] perf(proxy): set jumbo IP-MTU 65535 on VZ network attachment VZFileHandleNetworkDeviceAttachment defaults its MTU to 1500 unless setMaximumTransmissionUnit: is called. We never called it, so every guest TCP segment was capped at the wire MTU and host smoltcp paid per-1.5-KiB-frame syscall + checksum + TCP processing costs. Apple's API supports IP-MTUs up to 65535. Setting it to the maximum hands smoltcp ~64 KiB super-frames per syscall, collapsing per-frame costs ~40x. In our host<->guest topology there is no wire NIC to fragment past, so jumbo frames are strictly free. Coordinated changes: - shuru-darwin: FileHandleNetworkAttachment::new(fd, mtu) now calls setMaximumTransmissionUnit:. - shuru-vm: pass NET_IP_MTU = 65535 from sandbox. - shuru-proxy: device::MTU = 65549 (14 + 65535) so smoltcp matches the attachment frame size; MAX_PENDING_FRAMES 4096 -> 256 to keep transient buffer ~16 MiB at the new frame size. - shuru-proxy: SO_RCVBUF 4 -> 8 MiB, SO_SNDBUF 1 -> 2 MiB to hold ~128 in-flight super-frames per Apple's 4x ratio guidance. - shuru-linux: signature parity for the non-Darwin stub. Cloudflare 90 MB download in-VM: ~65 MB/s -> ~89.9 MB/s mean (4 trials, cold-start dropped). Now ~91% of host-native (~99 MB/s). All 20 shuru-proxy unit tests pass; --allow-host enforcement still blocks non-allowed domains at the DNS gate. --- crates/shuru-darwin/src/network.rs | 20 +++++++++++++------- crates/shuru-linux/src/network.rs | 4 +++- crates/shuru-proxy/src/device.rs | 18 ++++++++++-------- crates/shuru-proxy/src/lib.rs | 9 +++++++-- crates/shuru-vm/src/sandbox.rs | 8 +++++++- 5 files changed, 40 insertions(+), 19 deletions(-) diff --git a/crates/shuru-darwin/src/network.rs b/crates/shuru-darwin/src/network.rs index 5a91f41..b36b2d8 100644 --- a/crates/shuru-darwin/src/network.rs +++ b/crates/shuru-darwin/src/network.rs @@ -20,19 +20,25 @@ impl FileHandleNetworkAttachment { /// Creates a network attachment from a connected datagram socket fd. /// The fd should be one end of `socketpair(AF_UNIX, SOCK_DGRAM)`. /// VZ takes ownership of this fd (closes on dealloc). - pub fn new(fd: RawFd) -> Self { + /// + /// `mtu` is the IP-layer MTU (1500..=65535). VZ defaults to 1500 if + /// `setMaximumTransmissionUnit:` is never called. Apple requires the + /// associated socket's `SO_SNDBUF`/`SO_RCVBUF` to be sized for the + /// chosen MTU (`SO_RCVBUF` >= 2× `SO_SNDBUF`, recommended 4×) — see + /// `shuru_proxy::create_socketpair`. + pub fn new(fd: RawFd, mtu: i64) -> Self { unsafe { let file_handle = NSFileHandle::initWithFileDescriptor_closeOnDealloc( NSFileHandle::alloc(), fd, true, ); - FileHandleNetworkAttachment { - inner: VZFileHandleNetworkDeviceAttachment::initWithFileHandle( - VZFileHandleNetworkDeviceAttachment::alloc(), - &file_handle, - ), - } + let inner = VZFileHandleNetworkDeviceAttachment::initWithFileHandle( + VZFileHandleNetworkDeviceAttachment::alloc(), + &file_handle, + ); + inner.setMaximumTransmissionUnit(mtu as isize); + FileHandleNetworkAttachment { inner } } } } diff --git a/crates/shuru-linux/src/network.rs b/crates/shuru-linux/src/network.rs index 266135a..fd53643 100644 --- a/crates/shuru-linux/src/network.rs +++ b/crates/shuru-linux/src/network.rs @@ -8,7 +8,9 @@ pub struct FileHandleNetworkAttachment { impl FileHandleNetworkAttachment { /// Creates a network attachment from a connected datagram socket fd. /// The fd should be one end of `socketpair(AF_UNIX, SOCK_DGRAM)`. - pub fn new(fd: RawFd) -> Self { + /// `mtu` is accepted for API parity with the Darwin implementation + /// and ignored on this platform (Linux build is a stub). + pub fn new(fd: RawFd, _mtu: i64) -> Self { FileHandleNetworkAttachment { fd } } } diff --git a/crates/shuru-proxy/src/device.rs b/crates/shuru-proxy/src/device.rs index a660a35..1126b2e 100644 --- a/crates/shuru-proxy/src/device.rs +++ b/crates/shuru-proxy/src/device.rs @@ -5,14 +5,16 @@ use std::os::unix::io::RawFd; use smoltcp::phy::{self, Checksum, Device, DeviceCapabilities, Medium}; use smoltcp::time::Instant; -const MTU: usize = 1514; // 14-byte Ethernet header + 1500-byte IP payload -// Sized to comfortably hold a full 4 MiB BDP burst (≈ 2 800 frames) in a -// single drain, so smoltcp processes it as one batch (one ACK round, one -// socket walk) instead of fragmenting across many poll iterations. The -// upper bound on memory is `MAX_PENDING_FRAMES × MTU` ≈ 6 MiB transient, -// freed each poll cycle. Real ceiling on RX is the kernel SO_RCVBUF (4 MiB) -// set in `lib.rs::create_socketpair`. -const MAX_PENDING_FRAMES: usize = 4096; +// 14-byte Ethernet header + 65535-byte IP payload. Must match the IP-MTU +// passed to `FileHandleNetworkAttachment::new` in `shuru-vm::sandbox.rs`. +// Jumbo frames collapse the per-frame syscall + checksum + smoltcp TCP +// processing cost by ~40× vs the 1500-byte default. +const MTU: usize = 65549; +// At 65 KiB per frame, this caps transient buffer usage to ~16 MiB +// (`MAX_PENDING_FRAMES × MTU`), still freed each poll cycle. Real ceiling +// on RX is the kernel SO_RCVBUF (8 MiB) set in `lib.rs::create_socketpair`, +// which itself holds ~128 super-frames before back-pressuring the guest. +const MAX_PENDING_FRAMES: usize = 256; /// Result of pulling a single frame from the host AF_UNIX socket. enum RecvOne { diff --git a/crates/shuru-proxy/src/lib.rs b/crates/shuru-proxy/src/lib.rs index 35be1d8..94fd8e5 100644 --- a/crates/shuru-proxy/src/lib.rs +++ b/crates/shuru-proxy/src/lib.rs @@ -72,9 +72,14 @@ pub fn create_socketpair() -> anyhow::Result<(RawFd, RawFd)> { let host_fd = fds[1]; // Apple recommends SO_RCVBUF >= 2x SO_SNDBUF for VZFileHandleNetworkDeviceAttachment + // (recommended 4×). With the 65535-byte jumbo IP-MTU set on the attachment + // (see `shuru-vm::sandbox.rs`), each datagram can be ~64 KiB, so 8 MiB + // rcvbuf holds ~128 in-flight super-frames — enough headroom for the BDP + // window before back-pressure trips. macOS `kern.ipc.maxsockbuf` may cap + // these silently; setsockopt errors are ignored as best-effort tuning. unsafe { - let sndbuf: libc::c_int = 1024 * 1024; - let rcvbuf: libc::c_int = 4 * 1024 * 1024; + let sndbuf: libc::c_int = 2 * 1024 * 1024; + let rcvbuf: libc::c_int = 8 * 1024 * 1024; libc::setsockopt( host_fd, libc::SOL_SOCKET, diff --git a/crates/shuru-vm/src/sandbox.rs b/crates/shuru-vm/src/sandbox.rs index a7d0000..0f10f9b 100644 --- a/crates/shuru-vm/src/sandbox.rs +++ b/crates/shuru-vm/src/sandbox.rs @@ -186,7 +186,13 @@ impl VmConfigBuilder { config.set_storage_devices(&[&block_device]); if let Some(fd) = self.network_fd { - let net_attachment = FileHandleNetworkAttachment::new(fd); + // IP-MTU 65535: hands smoltcp/host one ~64 KiB super-frame per + // syscall instead of segmenting at 1500 B. Must match + // `shuru_proxy::device::MTU` (Ethernet frame size = 14 + this). + // The associated socket buffers are sized in + // `shuru_proxy::create_socketpair`. + const NET_IP_MTU: i64 = 65535; + let net_attachment = FileHandleNetworkAttachment::new(fd, NET_IP_MTU); let net_device = VirtioNetworkDevice::new_with_attachment(&net_attachment); net_device.set_mac_address(&MACAddress::random_local()); config.set_network_devices(&[net_device]); From 4bdc3ee4034e0007b04a0a6f667382b95c4dee48 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 06:07:15 +0530 Subject: [PATCH 06/57] kernel: enable container runtime support and move to 6.12.114 Adds cgroup v2 controllers, BPF for cgroup device filtering, seccomp filter, veth, bridge netfilter and the xtables/nftables pieces Docker needs. Everything stays built in, no modules. --- kernel/shuru_defconfig | 48 +++++++++++++++++++++++++++++++++++++++++ scripts/build-kernel.sh | 4 ++-- 2 files changed, 50 insertions(+), 2 deletions(-) diff --git a/kernel/shuru_defconfig b/kernel/shuru_defconfig index 5c0da8e..91df6e8 100644 --- a/kernel/shuru_defconfig +++ b/kernel/shuru_defconfig @@ -190,3 +190,51 @@ CONFIG_RTC_DRV_PL031=y # CONFIG_MEDIA_SUPPORT is not set # CONFIG_POWER_SUPPLY is not set # CONFIG_MD is not set + +# Container runtime support (Docker, containerd, runc on cgroup v2) +# cgroup v2 controllers runc expects: cpu (with bandwidth), cpuset, io, memory, pids +CONFIG_CPUSETS=y +CONFIG_FAIR_GROUP_SCHED=y +CONFIG_CFS_BANDWIDTH=y +CONFIG_BLK_CGROUP=y +CONFIG_BLK_DEV_THROTTLING=y +# runc joins a session keyring per container +CONFIG_KEYS=y +# cgroup v2 device access control is an eBPF program attached to the cgroup. +# Unprivileged bpf() stays off so containers cannot reach the verifier. +CONFIG_BPF=y +CONFIG_BPF_SYSCALL=y +CONFIG_CGROUP_BPF=y +CONFIG_BPF_UNPRIV_DEFAULT_OFF=y +# Default Docker seccomp profile +CONFIG_SECCOMP=y +CONFIG_SECCOMP_FILTER=y +# Bridge networking: veth pairs on docker0, bridge traffic through iptables +CONFIG_VETH=y +CONFIG_BRIDGE_NETFILTER=y +# iptables-nft rules installed by dockerd (xt matches run through nft compat) +CONFIG_NETFILTER_XT_MATCH_ADDRTYPE=y +CONFIG_NETFILTER_XT_MATCH_COMMENT=y +CONFIG_NETFILTER_XT_MARK=y +CONFIG_NETFILTER_XT_NAT=y +CONFIG_NETFILTER_XT_TARGET_MASQUERADE=y +CONFIG_NFT_COMPAT=y +CONFIG_NFT_MASQ=y +CONFIG_NFT_FIB_IPV4=y +CONFIG_NFT_FIB_IPV6=y +CONFIG_NFT_REJECT=y +CONFIG_IP_NF_MANGLE=y +CONFIG_IP_NF_RAW=y +CONFIG_IP_NF_TARGET_REJECT=y +CONFIG_IP6_NF_IPTABLES=y +CONFIG_IP6_NF_FILTER=y +CONFIG_IP6_NF_MANGLE=y +CONFIG_IP6_NF_NAT=y +CONFIG_IP6_NF_RAW=y +CONFIG_IP6_NF_TARGET_MASQUERADE=y +CONFIG_IP6_NF_TARGET_REJECT=y +# overlay2 stores security xattrs on the backing ext4 +CONFIG_EXT4_FS_SECURITY=y +# Expose the running config so moby check-config.sh can audit the guest +CONFIG_IKCONFIG=y +CONFIG_IKCONFIG_PROC=y diff --git a/scripts/build-kernel.sh b/scripts/build-kernel.sh index f038979..0b61706 100755 --- a/scripts/build-kernel.sh +++ b/scripts/build-kernel.sh @@ -1,9 +1,9 @@ #!/bin/bash set -euo pipefail -KERNEL_VERSION="${KERNEL_VERSION:-6.12.17}" +KERNEL_VERSION="${KERNEL_VERSION:-6.12.114}" KERNEL_MAJOR="${KERNEL_VERSION%%.*}" -DATA_DIR="${HOME}/.local/share/shuru" +DATA_DIR="${SHURU_DATA_DIR:-${HOME}/.local/share/shuru}" SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" REPO_DIR="$(dirname "$SCRIPT_DIR")" DEFCONFIG="${REPO_DIR}/kernel/shuru_defconfig" From ae9d36d03b4f4a40615c509cd685f8b471d9a575 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 06:07:22 +0530 Subject: [PATCH 07/57] guest: mount /run, /dev/shm and cgroup2 at boot Size capped tmpfs for /run (64m) and /dev/shm (256m). cgroup2 is mounted with nsdelegate and memory_recursiveprot and every available controller is enabled in the root subtree so container runtimes get memory, cpu, pids and io limits. --- crates/shuru-guest/src/main.rs | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/crates/shuru-guest/src/main.rs b/crates/shuru-guest/src/main.rs index 179772f..57d12b1 100644 --- a/crates/shuru-guest/src/main.rs +++ b/crates/shuru-guest/src/main.rs @@ -103,6 +103,40 @@ mod guest { Some("newinstance,ptmxmode=0666"), ); mount_fs("tmpfs", "/tmp", "tmpfs", None); + // Runtime state lives on tmpfs so pid files and sockets never land in + // a checkpoint. A stale /run/docker.pid otherwise blocks dockerd on + // the next boot. + // Both are guest RAM, so cap them well below the VM memory. + mount_fs("tmpfs", "/run", "tmpfs", Some("mode=0755,size=64m")); + std::fs::create_dir_all("/run/lock").ok(); + std::fs::create_dir_all("/dev/shm").ok(); + mount_fs("tmpfs", "/dev/shm", "tmpfs", Some("mode=1777,size=256m")); + mount_cgroup2(); + } + + /// Unified cgroup hierarchy with every controller delegated below the + /// root, which is what runc and containerd expect to find. + fn mount_cgroup2() { + if !mount_fs( + "cgroup2", + "/sys/fs/cgroup", + "cgroup2", + Some("nsdelegate,memory_recursiveprot"), + ) { + return; + } + let controllers = match std::fs::read_to_string("/sys/fs/cgroup/cgroup.controllers") { + Ok(c) => c, + Err(_) => return, + }; + for name in controllers.split_whitespace() { + if let Err(e) = std::fs::write( + "/sys/fs/cgroup/cgroup.subtree_control", + format!("+{}", name), + ) { + eprintln!("shuru-guest: failed to enable cgroup controller {}: {}", name, e); + } + } } fn process_mount(req: &MountRequest) -> MountResponse { From fe2ef7ba2c2a5be7d4f718bbc8b83e0fd655f34c Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 06:07:28 +0530 Subject: [PATCH 08/57] vm: honour SHURU_DATA_DIR for the data directory Lets builds and tests use an isolated set of kernel, initramfs, rootfs and checkpoints without touching the installed ones. --- crates/shuru-vm/src/lib.rs | 8 ++++++++ scripts/prepare-rootfs.sh | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/crates/shuru-vm/src/lib.rs b/crates/shuru-vm/src/lib.rs index b3bd872..72f3895 100644 --- a/crates/shuru-vm/src/lib.rs +++ b/crates/shuru-vm/src/lib.rs @@ -34,7 +34,15 @@ pub fn validate_checkpoint_name(name: &str) -> Result<(), String> { Ok(()) } +/// Where assets, checkpoints and instances live. `SHURU_DATA_DIR` overrides +/// the default so a build or a test run can use its own kernel, rootfs and +/// checkpoints without touching the installed ones. pub fn default_data_dir() -> String { + if let Ok(dir) = std::env::var("SHURU_DATA_DIR") { + if !dir.is_empty() { + return dir; + } + } let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string()); format!("{}/.local/share/shuru", home) } diff --git a/scripts/prepare-rootfs.sh b/scripts/prepare-rootfs.sh index 122073c..6c97441 100755 --- a/scripts/prepare-rootfs.sh +++ b/scripts/prepare-rootfs.sh @@ -2,7 +2,7 @@ set -euo pipefail DEBIAN_RELEASE="trixie" -DATA_DIR="${HOME}/.local/share/shuru" +DATA_DIR="${SHURU_DATA_DIR:-${HOME}/.local/share/shuru}" ROOTFS_IMG="${DATA_DIR}/rootfs.ext4" KERNEL_PATH="${DATA_DIR}/Image" INITRAMFS_PATH="${DATA_DIR}/initramfs.cpio.gz" From 58fb3e472510f408af32c6607645fcedab326f36 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 06:07:35 +0530 Subject: [PATCH 09/57] scripts: Docker checkpoint builder and HF Jobs kernel build prepare-docker-checkpoint.sh creates a checkpoint with pinned docker-ce, containerd.io and a digest pinned nginx-unprivileged image, with the trixie security and updates archives enabled. build-kernel-hf.sh cross compiles the kernel on Hugging Face Jobs for hosts without the disk for a local build. --- scripts/build-kernel-hf.sh | 95 ++++++++++++++++++ scripts/prepare-docker-checkpoint.sh | 139 +++++++++++++++++++++++++++ 2 files changed, 234 insertions(+) create mode 100755 scripts/build-kernel-hf.sh create mode 100755 scripts/prepare-docker-checkpoint.sh diff --git a/scripts/build-kernel-hf.sh b/scripts/build-kernel-hf.sh new file mode 100755 index 0000000..3b24990 --- /dev/null +++ b/scripts/build-kernel-hf.sh @@ -0,0 +1,95 @@ +#!/bin/bash +# Build the Shuru guest kernel on a Hugging Face Job instead of local Docker. +# +# Same defconfig and kernel version as build-kernel.sh, cross-compiled on an +# x86_64 CPU job. The job uploads the Image and the resolved .config to a +# private dataset repo, and this script downloads them into the data dir. +# Nothing is written to the data dir until the download at the end, so the +# installed kernel is untouched until then. Point SHURU_DATA_DIR somewhere +# else to keep the result fully isolated. +# +# Requires: hf CLI logged in (hf auth whoami), a billable HF account. +set -euo pipefail + +KERNEL_VERSION="${KERNEL_VERSION:-6.12.114}" +KERNEL_MAJOR="${KERNEL_VERSION%%.*}" +DATA_DIR="${SHURU_DATA_DIR:-${HOME}/.local/share/shuru}" +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +REPO_DIR="$(dirname "$SCRIPT_DIR")" +DEFCONFIG="${REPO_DIR}/kernel/shuru_defconfig" +HF_FLAVOR="${HF_FLAVOR:-cpu-upgrade}" +HF_USER="$(hf auth whoami --format json | python3 -I -c 'import json,sys; print(json.load(sys.stdin)["user"])')" +HF_REPO="${HF_REPO:-${HF_USER}/shuru-kernel-build}" +JOB_NAME="shuru-kernel-${KERNEL_VERSION//./-}" + +if [ ! -f "$DEFCONFIG" ]; then + echo "ERROR: Defconfig not found at ${DEFCONFIG}" + exit 1 +fi + +export HF_TOKEN="${HF_TOKEN:-$(hf auth token)}" +DEFCONFIG_B64="$(base64 < "$DEFCONFIG" | tr -d '\n')" + +echo "==> Building kernel ${KERNEL_VERSION} on Hugging Face Jobs (${HF_FLAVOR})" +echo " artifacts: https://huggingface.co/datasets/${HF_REPO} (private)" + +hf repos create "$HF_REPO" --type dataset --private --exist-ok > /dev/null + +read -r -d '' JOB_SCRIPT << 'JOBEOF' || true +set -euxo pipefail +export DEBIAN_FRONTEND=noninteractive +apt-get update -qq > /dev/null +apt-get install -y -qq build-essential bc flex bison libelf-dev libssl-dev \ + gcc-aarch64-linux-gnu curl xz-utils ca-certificates python3 python3-venv > /dev/null +curl -LsSf https://hf.co/cli/install.sh | bash > /dev/null +export PATH="$HOME/.local/bin:$PATH" + +cd /tmp +curl -sSLO "https://cdn.kernel.org/pub/linux/kernel/v${KERNEL_MAJOR}.x/linux-${KERNEL_VERSION}.tar.xz" +curl -sSL "https://cdn.kernel.org/pub/linux/kernel/v${KERNEL_MAJOR}.x/sha256sums.asc" \ + | grep " linux-${KERNEL_VERSION}.tar.xz$" | sha256sum -c - +tar xf "linux-${KERNEL_VERSION}.tar.xz" +cd "linux-${KERNEL_VERSION}" + +echo "$DEFCONFIG_B64" | base64 -d > arch/arm64/configs/shuru_defconfig +make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- shuru_defconfig +make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- -j"$(nproc)" Image 2>&1 | tail -3 + +cp arch/arm64/boot/Image "/tmp/Image-${KERNEL_VERSION}" +cp .config "/tmp/config-${KERNEL_VERSION}" +(cd /tmp && sha256sum "Image-${KERNEL_VERSION}" | tee "Image-${KERNEL_VERSION}.sha256") +hf upload "$HF_REPO" "/tmp/Image-${KERNEL_VERSION}" "Image-${KERNEL_VERSION}" --type dataset > /dev/null +hf upload "$HF_REPO" "/tmp/Image-${KERNEL_VERSION}.sha256" "Image-${KERNEL_VERSION}.sha256" --type dataset > /dev/null +hf upload "$HF_REPO" "/tmp/config-${KERNEL_VERSION}" "config-${KERNEL_VERSION}" --type dataset > /dev/null +echo "KERNEL_BUILD_DONE" +JOBEOF + +JOB_ID="$(hf jobs run debian:trixie-slim bash -c "$JOB_SCRIPT" \ + --ssh --detach --flavor "$HF_FLAVOR" --timeout 2h \ + --name "$JOB_NAME" \ + --secrets HF_TOKEN \ + --env "KERNEL_VERSION=${KERNEL_VERSION}" \ + --env "KERNEL_MAJOR=${KERNEL_MAJOR}" \ + --env "HF_REPO=${HF_REPO}" \ + --env "DEFCONFIG_B64=${DEFCONFIG_B64}" \ + --format quiet)" +echo "==> Job ${JOB_ID} launched" + +echo "==> SSH access check (dry run)" +hf jobs ssh "$JOB_ID" --dry-run || true + +echo "==> Waiting for the build (10 to 20 minutes on ${HF_FLAVOR})..." +hf jobs wait "$JOB_ID" --timeout 2h +hf jobs logs "$JOB_ID" | tail -5 | grep -q KERNEL_BUILD_DONE + +mkdir -p "$DATA_DIR" +DL_DIR="$(mktemp -d)" +hf download "$HF_REPO" "Image-${KERNEL_VERSION}" "Image-${KERNEL_VERSION}.sha256" "config-${KERNEL_VERSION}" \ + --type dataset --local-dir "$DL_DIR" > /dev/null +(cd "$DL_DIR" && sha256sum -c "Image-${KERNEL_VERSION}.sha256") +cp "${DL_DIR}/Image-${KERNEL_VERSION}" "${DATA_DIR}/Image" +cp "${DL_DIR}/config-${KERNEL_VERSION}" "${DATA_DIR}/Image.config" +rm -rf "$DL_DIR" + +echo "==> Kernel ready at ${DATA_DIR}/Image ($(du -h "${DATA_DIR}/Image" | cut -f1))" +echo " Resolved config saved to ${DATA_DIR}/Image.config" diff --git a/scripts/prepare-docker-checkpoint.sh b/scripts/prepare-docker-checkpoint.sh new file mode 100755 index 0000000..0757154 --- /dev/null +++ b/scripts/prepare-docker-checkpoint.sh @@ -0,0 +1,139 @@ +#!/bin/bash +# Create a Shuru checkpoint with Docker Engine installed and one pinned image +# pulled, so `shuru run --from docker -- with-dockerd docker run ...` works +# with networking disabled. +# +# Everything is pinned: Docker apt packages by exact version, the apt signing +# key by SHA-256, the image by manifest digest. The VM that performs the +# install only reaches the hosts listed below. +# +# Needs a kernel and guest init with container support (RFC 0003). Until a +# release ships them, point SHURU_KERNEL and SHURU_INITRD at a local build. +set -euo pipefail + +SHURU_BIN="${SHURU_BIN:-shuru}" +CHECKPOINT_NAME="${CHECKPOINT_NAME:-docker}" +FROM_CHECKPOINT="${FROM_CHECKPOINT:-}" +DISK_SIZE_MB="${DISK_SIZE_MB:-4096}" +MEMORY_MB="${MEMORY_MB:-2048}" + +DOCKER_VERSION="${DOCKER_VERSION:-5:29.9.2-1~debian.13~trixie}" +CONTAINERD_VERSION="${CONTAINERD_VERSION:-2.4.2-3~debian.13~trixie}" +# Docker Release (CE deb), fingerprint 9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88 +DOCKER_GPG_SHA256="${DOCKER_GPG_SHA256:-1500c1f56fa9e26b9b8f42452a553675796ade0807cdce11975eb98170b3a570}" +# nginxinc/nginx-unprivileged 1.31.7-alpine-slim, multi-arch index digest, +# runs as uid 101 and listens on 8080. +DOCKER_IMAGE="${DOCKER_IMAGE:-nginxinc/nginx-unprivileged:1.31.7-alpine-slim@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7}" + +WITH_DOCKERD_B64="$(base64 << 'HELPER' | tr -d '\n' +#!/bin/sh +# Start dockerd, run a command, then stop dockerd so the disk is consistent. +# usage: with-dockerd CMD [ARGS...] +set -eu +if [ "$#" -eq 0 ]; then + echo "usage: with-dockerd CMD [ARGS...]" >&2 + exit 64 +fi +LOG=/var/log/dockerd.log +if docker info > /dev/null 2>&1; then + exec "$@" +fi +dockerd > "$LOG" 2>&1 & +DOCKERD_PID=$! +i=0 +until docker info > /dev/null 2>&1; do + i=$((i + 1)) + if ! kill -0 "$DOCKERD_PID" 2> /dev/null; then + echo "with-dockerd: dockerd exited during startup" >&2 + tail -n 30 "$LOG" >&2 + exit 1 + fi + if [ "$i" -ge 300 ]; then + echo "with-dockerd: dockerd not ready after 60s" >&2 + tail -n 30 "$LOG" >&2 + kill "$DOCKERD_PID" 2> /dev/null || true + exit 1 + fi + sleep 0.2 +done +set +e +"$@" +STATUS=$? +set -e +kill -TERM "$DOCKERD_PID" 2> /dev/null || true +j=0 +while kill -0 "$DOCKERD_PID" 2> /dev/null && [ "$j" -lt 150 ]; do + sleep 0.2 + j=$((j + 1)) +done +sync +exit "$STATUS" +HELPER +)" + +GUEST_SCRIPT="$(cat << EOF +set -eu +export DEBIAN_FRONTEND=noninteractive +echo "==> Upgrading Debian base (main, security and updates archives)" +cat > /etc/apt/sources.list.d/debian.sources << SRCEOF +Types: deb +URIs: http://deb.debian.org/debian +Suites: trixie trixie-updates +Components: main +Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg + +Types: deb +URIs: http://security.debian.org/debian-security +Suites: trixie-security +Components: main +Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg +SRCEOF +rm -f /etc/apt/sources.list +apt-get update -qq +apt-get upgrade -y -qq --no-install-recommends +echo "==> Adding Docker apt repository (key pinned by SHA-256)" +install -m 0755 -d /etc/apt/keyrings +curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc +echo "${DOCKER_GPG_SHA256} /etc/apt/keyrings/docker.asc" | sha256sum -c - +chmod a+r /etc/apt/keyrings/docker.asc +echo "deb [arch=arm64 signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian trixie stable" > /etc/apt/sources.list.d/docker.list +apt-get update -qq +echo "==> Installing docker-ce ${DOCKER_VERSION}, containerd.io ${CONTAINERD_VERSION}" +apt-get install -y -qq --no-install-recommends \ + "docker-ce=${DOCKER_VERSION}" "docker-ce-cli=${DOCKER_VERSION}" "containerd.io=${CONTAINERD_VERSION}" +apt-mark hold docker-ce docker-ce-cli containerd.io > /dev/null +apt-get clean +rm -rf /var/lib/apt/lists/* +mkdir -p /etc/docker +printf '{\n "no-new-privileges": true\n}\n' > /etc/docker/daemon.json +echo "${WITH_DOCKERD_B64}" | base64 -d > /usr/local/bin/with-dockerd +chmod 755 /usr/local/bin/with-dockerd +echo "==> Pulling ${DOCKER_IMAGE}" +with-dockerd sh -c 'docker pull "${DOCKER_IMAGE}" && docker image ls --digests' +echo "==> Installed versions" +docker --version +containerd --version +runc --version | head -n 1 +EOF +)" +GUEST_SCRIPT_B64="$(printf '%s\n' "$GUEST_SCRIPT" | base64 | tr -d '\n')" + +ARGS=(checkpoint create "$CHECKPOINT_NAME" + --allow-net + --disk-size "$DISK_SIZE_MB" + --memory "$MEMORY_MB" + --allow-host deb.debian.org + --allow-host security.debian.org + --allow-host download.docker.com + --allow-host "*.docker.io" + --allow-host "*.docker.com" + --allow-host "*.cloudflarestorage.com") +if [ -n "$FROM_CHECKPOINT" ]; then + ARGS+=(--from "$FROM_CHECKPOINT") +fi +if [ -n "${VERBOSE:-}" ]; then + ARGS+=(--verbose) +fi + +echo "==> Creating checkpoint '${CHECKPOINT_NAME}' with Docker ${DOCKER_VERSION}" +exec "$SHURU_BIN" "${ARGS[@]}" -- sh -c "echo ${GUEST_SCRIPT_B64} | base64 -d | sh" From 17680346a8dc8dadcb782a217582d98f5793a837 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 06:07:42 +0530 Subject: [PATCH 10/57] docs: RFC 0003 Docker on Shuru with integration tests and evidence Nine ignored integration tests cover non-root execution with default isolation, HTTP through port forwarding, egress policy, host isolation, resource limits and volume persistence across daemon and VM restarts. --- CHANGELOG.md | 22 ++ README.md | 27 ++ crates/shuru-cli/tests/docker.rs | 413 ++++++++++++++++++++ docs/rfcs/0003-docker-on-shuru-evidence.log | 136 +++++++ docs/rfcs/0003-docker-on-shuru.md | 329 ++++++++++++++++ 5 files changed, 927 insertions(+) create mode 100644 crates/shuru-cli/tests/docker.rs create mode 100644 docs/rfcs/0003-docker-on-shuru-evidence.log create mode 100644 docs/rfcs/0003-docker-on-shuru.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 62a476e..4af50ac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,27 @@ # Changelog +## Unreleased + +### Docker Engine runs inside the VM + +`scripts/prepare-docker-checkpoint.sh` builds a checkpoint with pinned +docker-ce 29.9.2 and containerd 2.4.2 and one pre-pulled image, and +`with-dockerd CMD` runs a command with the daemon up. Containers get the +same boundary as any guest process: no egress without `--allow-net`, the +host allowlist applied by the proxy, host ports only through `-p`. + +To support it, the guest kernel gains cgroup v2 controllers, cgroup BPF, +seccomp filters, veth, and the netfilter targets dockerd installs, and moves +to Linux 6.12.114. The guest init now mounts cgroup2 on /sys/fs/cgroup and +tmpfs on /run and /dev/shm. `/run` is therefore no longer persisted into +checkpoints. + +`SHURU_DATA_DIR` overrides the data directory so builds and tests can use +their own kernel, initramfs and checkpoints. `scripts/build-kernel-hf.sh` +builds the kernel on a Hugging Face CPU job. + +See docs/rfcs/0003-docker-on-shuru.md. + ## 0.7.0 ### Secrets can be refreshed while the VM runs diff --git a/README.md b/README.md index 0131ef1..19a79b3 100644 --- a/README.md +++ b/README.md @@ -207,6 +207,33 @@ uv run --with browser-use --with openai examples/browser-use.py The example keeps Chromium inside the microVM and exposes only its CDP port to the host. +## Docker + +Docker Engine runs inside the VM. Install it into a checkpoint once, then run +containers from that checkpoint with networking disabled: + +```sh +# One-time: pinned docker-ce + containerd, with one image pre-pulled +./scripts/prepare-docker-checkpoint.sh + +# Serve the pre-pulled nginx-unprivileged image on host port 8080 +shuru run --from docker -p 8080:8080 -- with-dockerd sh -c \ + 'docker run -d -p 8080:8080 nginxinc/nginx-unprivileged:1.31.7-alpine-slim && sleep 300' +curl http://127.0.0.1:8080/ +``` + +`with-dockerd CMD` starts dockerd, runs `CMD`, then stops dockerd so the disk +is consistent for checkpointing. Pulling other images needs `--allow-net`, +and the usual `--allow-host` allowlist applies to container traffic too: +containers reach the internet only through the Shuru proxy, and nothing at +all without `--allow-net`. + +Docker isolation inside the VM stays at its defaults (seccomp, no new +privileges). Do not use `--privileged` or mount the Docker socket into a +container; neither crosses the VM boundary, but there is no reason to weaken +the inner layer. See docs/rfcs/0003-docker-on-shuru.md for the full design, +limits, and verification evidence. + ## Changelog See [CHANGELOG.md](CHANGELOG.md) for release notes and breaking changes. diff --git a/crates/shuru-cli/tests/docker.rs b/crates/shuru-cli/tests/docker.rs new file mode 100644 index 0000000..89a26c0 --- /dev/null +++ b/crates/shuru-cli/tests/docker.rs @@ -0,0 +1,413 @@ +//! Docker Engine inside a Shuru VM (RFC 0003). Boots real VMs from the +//! checkpoint built by scripts/prepare-docker-checkpoint.sh, so every test +//! is #[ignore]d. Run with: +//! +//! SHURU_BIN=target/debug/shuru cargo test -p shuru-cli --test docker -- --ignored +//! +//! Environment: +//! SHURU_BIN codesigned shuru binary (required). cargo test +//! relinks target/debug/shuru and drops its +//! signature, so sign a copy elsewhere and point +//! SHURU_BIN at that. +//! SHURU_DOCKER_CHECKPOINT checkpoint name (default "docker") +//! SHURU_DOCKER_IMAGE image reference baked into the checkpoint +//! SHURU_TEST_NET=1 also run the tests that need real egress +//! +//! SHURU_DATA_DIR, SHURU_KERNEL and SHURU_INITRD are inherited by the CLI, +//! so a run can use an isolated kernel and checkpoint directory. + +use std::io::{Read, Write}; +use std::net::{TcpListener, TcpStream}; +use std::process::{Command, Output, Stdio}; +use std::time::{Duration, Instant}; + +use base64::Engine; +const DEFAULT_IMAGE: &str = "nginxinc/nginx-unprivileged:1.31.7-alpine-slim@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7"; + +fn shuru_bin() -> String { + std::env::var("SHURU_BIN") + .expect("SHURU_BIN not set: point it at a codesigned shuru binary (e.g. just build)") +} + +fn checkpoint() -> String { + std::env::var("SHURU_DOCKER_CHECKPOINT").unwrap_or_else(|_| "docker".to_string()) +} + +fn image() -> String { + std::env::var("SHURU_DOCKER_IMAGE").unwrap_or_else(|_| DEFAULT_IMAGE.to_string()) +} + +fn net_tests_enabled() -> bool { + std::env::var("SHURU_TEST_NET").map(|v| v == "1").unwrap_or(false) +} + +/// Build the guest command: the script is base64 encoded so no quoting +/// survives the trip through argv into `sh -c`. +fn guest_cmd(script: &str) -> Vec { + let script = script.replace("IMAGE", &image()); + let b64 = base64::engine::general_purpose::STANDARD.encode(script.as_bytes()); + vec![ + "sh".into(), + "-c".into(), + format!("echo {} | base64 -d | sh", b64), + ] +} + +/// Runs the script in a fresh VM and echoes the output so a `--nocapture` +/// run doubles as an evidence log. +fn shuru_run(extra: &[&str], script: &str) -> Output { + let mut cmd = Command::new(shuru_bin()); + cmd.args(["run", "--from", &checkpoint()]); + cmd.args(extra); + cmd.arg("--"); + cmd.args(guest_cmd(script)); + cmd.stdin(Stdio::null()); + let out = cmd.output().expect("failed to spawn shuru"); + eprintln!("$ shuru run --from {} {}\n{}", checkpoint(), extra.join(" "), text(&out)); + out +} + +fn text(out: &Output) -> String { + format!( + "--- stdout ---\n{}\n--- stderr ---\n{}", + String::from_utf8_lossy(&out.stdout), + String::from_utf8_lossy(&out.stderr) + ) +} + +fn stdout(out: &Output) -> String { + String::from_utf8_lossy(&out.stdout).to_string() +} + +fn free_port() -> u16 { + TcpListener::bind("127.0.0.1:0") + .unwrap() + .local_addr() + .unwrap() + .port() +} + +fn http_get(port: u16, path: &str) -> Option { + let mut s = TcpStream::connect_timeout( + &format!("127.0.0.1:{}", port).parse().unwrap(), + Duration::from_secs(2), + ) + .ok()?; + s.set_read_timeout(Some(Duration::from_secs(5))).ok()?; + write!( + s, + "GET {} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n", + path + ) + .ok()?; + let mut body = String::new(); + s.read_to_string(&mut body).ok()?; + Some(body) +} + +#[test] +#[ignore] +fn dockerd_runs_pinned_image_as_non_root_with_default_isolation() { + let out = shuru_run( + &[], + r#" +set -e +with-dockerd sh -c ' +docker info --format "{{.CgroupDriver}} cgroup-v{{.CgroupVersion}} storage={{.Driver}} kernel={{.KernelVersion}} security={{.SecurityOptions}}" +docker version --format "docker={{.Server.Version}} containerd={{(index .Server.Components 1).Version}} runc={{(index .Server.Components 2).Version}}" +docker image inspect --format "digest={{index .RepoDigests 0}} user={{.Config.User}}" IMAGE +echo "uid=$(docker run --rm IMAGE id -u)" +docker run -d --name web IMAGE > /dev/null +sleep 1 +PID=$(docker inspect --format "{{.State.Pid}}" web) +echo "nginx-master-$(grep ^Uid: /proc/$PID/status | tr -s "\t" " ")" +echo "privileged=$(docker inspect --format "{{.HostConfig.Privileged}}" web)" +echo "seccomp=$(docker inspect --format "{{.HostConfig.SecurityOpt}}" web)" +echo "no-new-privs=$(docker exec web grep NoNewPrivs /proc/1/status)" +echo "seccomp-mode=$(docker exec web grep Seccomp: /proc/1/status)" +docker rm -f web > /dev/null +' +"#, + ); + assert!(out.status.success(), "{}", text(&out)); + let s = stdout(&out); + assert!(s.contains("cgroup-v2"), "{}", s); + assert!(s.contains("storage=overlayfs"), "{}", s); + assert!(s.contains("name=seccomp,profile=builtin"), "{}", s); + assert!(s.contains("name=no-new-privileges"), "{}", s); + assert!(s.contains("digest=nginxinc/nginx-unprivileged@sha256:a8cb0f33"), "{}", s); + assert!(s.contains("user=101"), "{}", s); + assert!(s.contains("\nuid=101\n"), "{}", s); + assert!(s.contains("nginx-master-Uid: 101 101 101 101"), "{}", s); + assert!(s.contains("privileged=false"), "{}", s); + assert!(s.contains("seccomp=[]"), "{}", s); + assert!(s.contains("NoNewPrivs:\t1"), "{}", s); + assert!(s.contains("Seccomp:\t2"), "{}", s); +} + +#[test] +#[ignore] +fn http_through_port_forward_reaches_container() { + let port = free_port(); + let token = format!("shuru-docker-{}", std::process::id()); + let script = format!( + r#" +set -e +mkdir -p /srv/www +echo "{token}" > /srv/www/index.html +with-dockerd sh -c ' +docker run -d --name web -p 8080:8080 -v /srv/www:/usr/share/nginx/html:ro IMAGE > /dev/null +echo READY +i=0 +until docker logs web 2>&1 | grep -q "GET /done"; do + sleep 0.2 + i=$((i + 1)) + if [ "$i" -ge 300 ]; then echo TIMEOUT; break; fi +done +docker rm -f web > /dev/null +echo STOPPED +' +"# + ); + + let child = Command::new(shuru_bin()) + .args(["run", "--from", &checkpoint(), "-p", &format!("{}:8080", port), "--"]) + .args(guest_cmd(&script)) + .stdin(Stdio::null()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .expect("failed to spawn shuru"); + + let deadline = Instant::now() + Duration::from_secs(90); + let mut body = None; + while Instant::now() < deadline { + if let Some(b) = http_get(port, "/") { + if b.contains(&token) { + body = Some(b); + break; + } + } + std::thread::sleep(Duration::from_millis(300)); + } + let _ = http_get(port, "/done"); + let out = child.wait_with_output().unwrap(); + eprintln!("$ shuru run --from {} -p {}:8080\n{}", checkpoint(), port, text(&out)); + if let Some(b) = &body { + eprintln!("$ GET http://127.0.0.1:{}/\n{}", port, b); + } + + let body = body.unwrap_or_else(|| panic!("no HTTP response with token on host port {}\n{}", port, text(&out))); + assert!(body.starts_with("HTTP/1.1 200"), "{}", body); + assert!(body.contains("Server: nginx"), "{}", body); + assert!(stdout(&out).contains("STOPPED"), "{}", text(&out)); + assert!(!stdout(&out).contains("TIMEOUT"), "{}", text(&out)); +} + +#[test] +#[ignore] +fn container_has_no_egress_without_allow_net() { + let out = shuru_run( + &[], + r#" +with-dockerd sh -c ' +echo "guest-eth0=$(ip -o link show eth0 2>&1 | head -c 40)" +docker run --rm IMAGE sh -c "wget -T 5 -qO- http://example.com && echo EGRESS_OK || echo EGRESS_BLOCKED" +docker run --rm IMAGE sh -c "nslookup example.com 2>&1 | tail -n 1; wget -T 5 -qO- http://93.184.215.14 && echo IP_OK || echo IP_BLOCKED" +' +"#, + ); + let s = stdout(&out); + assert!(s.contains("guest-eth0=Device \"eth0\" does not exist"), "{}", text(&out)); + assert!(s.contains("EGRESS_BLOCKED"), "{}", text(&out)); + assert!(s.contains("IP_BLOCKED"), "{}", text(&out)); + assert!(!s.contains("EGRESS_OK"), "{}", text(&out)); +} + +#[test] +#[ignore] +fn container_egress_follows_host_allowlist() { + if !net_tests_enabled() { + eprintln!("skipped: set SHURU_TEST_NET=1"); + return; + } + let out = shuru_run( + &["--allow-net", "--allow-host", "example.com"], + r#" +with-dockerd sh -c ' +docker run --rm IMAGE sh -c "wget -T 15 -qO- http://example.com | grep -o \"[^<]*\" && echo ALLOWED_OK || echo ALLOWED_FAIL" +docker run --rm IMAGE sh -c "wget -T 5 -qO- http://www.iana.org/ > /dev/null 2>&1 && echo DOMAIN_LEAK || echo DOMAIN_BLOCKED" +docker run --rm IMAGE sh -c "wget -T 5 -qO- http://1.1.1.1/ > /dev/null 2>&1 && echo IP_LEAK || echo IP_BLOCKED" +docker run --rm --dns 8.8.8.8 IMAGE sh -c "wget -T 5 -qO- http://example.com > /dev/null 2>&1 && echo DNS_LEAK || echo DNS_BLOCKED" +' +"#, + ); + let s = stdout(&out); + assert!(s.contains("Example Domain"), "{}", text(&out)); + assert!(s.contains("ALLOWED_OK"), "{}", text(&out)); + assert!(s.contains("DOMAIN_BLOCKED"), "{}", text(&out)); + assert!(s.contains("IP_BLOCKED"), "{}", text(&out)); + assert!(s.contains("DNS_BLOCKED"), "{}", text(&out)); + assert!(!s.contains("LEAK"), "{}", text(&out)); +} + +/// A listener on the host loopback must be unreachable from a container, +/// with and without networking. The gateway address and host.shuru.internal +/// are the only names a guest could try. +#[test] +#[ignore] +fn container_cannot_reach_host_loopback_services() { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let port = listener.local_addr().unwrap().port(); + listener.set_nonblocking(true).unwrap(); + + let script = format!( + r#" +with-dockerd sh -c ' +docker run --rm IMAGE sh -c "wget -T 5 -qO- http://10.0.0.1:{port}/ > /dev/null 2>&1 && echo GATEWAY_REACHED || echo GATEWAY_BLOCKED" +docker run --rm IMAGE sh -c "wget -T 5 -qO- http://host.shuru.internal:{port}/ > /dev/null 2>&1 && echo HOSTNAME_REACHED || echo HOSTNAME_BLOCKED" +' +"# + ); + + for extra in [&[][..], &["--allow-net"][..]] { + let out = shuru_run(extra, &script); + let s = stdout(&out); + assert!(s.contains("GATEWAY_BLOCKED"), "{:?}\n{}", extra, text(&out)); + assert!(s.contains("HOSTNAME_BLOCKED"), "{:?}\n{}", extra, text(&out)); + assert!(!s.contains("REACHED"), "{:?}\n{}", extra, text(&out)); + } + assert!( + listener.accept().is_err(), + "host listener on {} received a connection from the sandbox", + port + ); +} + +#[test] +#[ignore] +fn container_cannot_write_to_host_through_default_mount() { + // Mounts must live under the CWD, which cargo sets to the crate dir. + let tmp = tempfile::tempdir_in(std::env::current_dir().unwrap()).unwrap(); + std::fs::write(tmp.path().join("host.txt"), "from-host\n").unwrap(); + let spec = format!("{}:/workspace", tmp.path().to_str().unwrap()); + + let out = shuru_run( + &["--mount", &spec], + r#" +with-dockerd sh -c ' +docker run --rm --user 0 -v /workspace:/w IMAGE sh -c "cat /w/host.txt; echo escaped > /w/escaped.txt && echo WROTE_IN_GUEST" +docker run --rm -v /:/vmroot IMAGE sh -c "ls /vmroot/Users > /dev/null 2>&1 && echo HOST_FS_VISIBLE || echo HOST_FS_ABSENT" +' +"#, + ); + let s = stdout(&out); + assert!(s.contains("from-host"), "{}", text(&out)); + assert!(s.contains("WROTE_IN_GUEST"), "{}", text(&out)); + assert!(s.contains("HOST_FS_ABSENT"), "{}", text(&out)); + assert!( + !tmp.path().join("escaped.txt").exists(), + "container write reached the host through a read-only mount" + ); +} + +#[test] +#[ignore] +fn resource_limits_apply_inside_containers() { + let out = shuru_run( + &[], + r#" +with-dockerd sh -c ' +docker run --rm --memory 64m --cpus 0.5 --pids-limit 20 IMAGE sh -c "echo memory.max=\$(cat /sys/fs/cgroup/memory.max); echo cpu.max=\$(cat /sys/fs/cgroup/cpu.max); echo pids.max=\$(cat /sys/fs/cgroup/pids.max)" +docker run --rm --memory 32m IMAGE sh -c "a=\$(head -c 200m /dev/zero | tr \"\\0\" a); echo survived" +echo "oom-exit=$?" +docker run --rm --pids-limit 5 IMAGE sh -c "for i in 1 2 3 4 5 6 7 8 9 10; do sleep 3 & done; wait; echo forked-all" 2>&1 | tail -n 1 +' +"#, + ); + let s = stdout(&out); + assert!(s.contains("memory.max=67108864"), "{}", text(&out)); + assert!(s.contains("cpu.max=50000 100000"), "{}", text(&out)); + assert!(s.contains("pids.max=20"), "{}", text(&out)); + assert!(s.contains("oom-exit=137"), "{}", text(&out)); + assert!(!s.contains("survived"), "{}", text(&out)); + assert!(!s.contains("forked-all"), "{}", text(&out)); +} + +#[test] +#[ignore] +fn named_volume_persists_across_container_and_daemon_restart() { + let token = format!("persisted-{}", std::process::id()); + let script = format!( + r#" +set -e +with-dockerd sh -c ' +docker volume create vdata > /dev/null +docker create --name keeper -v vdata:/tmp IMAGE sleep 120 > /dev/null +docker start keeper > /dev/null +docker exec keeper sh -c "echo {token} > /tmp/marker" +docker stop -t 1 keeper > /dev/null +docker start keeper > /dev/null +echo "after-container-restart=$(docker exec keeper cat /tmp/marker)" +docker rm -f keeper > /dev/null +' +with-dockerd sh -c ' +echo "after-daemon-restart=$(docker run --rm -v vdata:/tmp IMAGE cat /tmp/marker)" +' +"# + ); + let out = shuru_run(&[], &script); + assert!(out.status.success(), "{}", text(&out)); + let s = stdout(&out); + assert!(s.contains(&format!("after-container-restart={}", token)), "{}", s); + assert!(s.contains(&format!("after-daemon-restart={}", token)), "{}", s); +} + +/// Shuru resets the disk on every run, so persistence across a VM stop and +/// start goes through a checkpoint. with-dockerd stops dockerd before the +/// checkpoint is taken, so the volume store is consistent on disk. +#[test] +#[ignore] +fn named_volume_persists_across_vm_stop_start_via_checkpoint() { + let name = format!("shuru-test-docker-data-{}", std::process::id()); + let token = format!("vm-persisted-{}", std::process::id()); + + let write = format!( + r#" +set -e +with-dockerd sh -c ' +docker volume create vdata > /dev/null +docker run --rm -v vdata:/tmp IMAGE sh -c "echo {token} > /tmp/marker" +' +"# + ); + let create = Command::new(shuru_bin()) + .args(["checkpoint", "create", &name, "--from", &checkpoint(), "--"]) + .args(guest_cmd(&write)) + .stdin(Stdio::null()) + .output() + .unwrap(); + assert!(create.status.success(), "{}", text(&create)); + + let read = Command::new(shuru_bin()) + .args(["run", "--from", &name, "--"]) + .args(guest_cmd( + r#"with-dockerd sh -c 'echo "after-vm-restart=$(docker run --rm -v vdata:/tmp IMAGE cat /tmp/marker)"'"#, + )) + .stdin(Stdio::null()) + .output() + .unwrap(); + + let _ = Command::new(shuru_bin()) + .args(["checkpoint", "delete", &name]) + .output(); + eprintln!("$ shuru checkpoint create {} --from {}\n{}", name, checkpoint(), text(&create)); + eprintln!("$ shuru run --from {}\n{}", name, text(&read)); + + assert!(read.status.success(), "{}", text(&read)); + assert!( + stdout(&read).contains(&format!("after-vm-restart={}", token)), + "{}", + text(&read) + ); +} diff --git a/docs/rfcs/0003-docker-on-shuru-evidence.log b/docs/rfcs/0003-docker-on-shuru-evidence.log new file mode 100644 index 0000000..d23af31 --- /dev/null +++ b/docs/rfcs/0003-docker-on-shuru-evidence.log @@ -0,0 +1,136 @@ + +running 9 tests +test container_cannot_reach_host_loopback_services ... $ shuru run --from docker +--- stdout --- +GATEWAY_BLOCKED +HOSTNAME_BLOCKED + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +$ shuru run --from docker --allow-net +--- stdout --- +GATEWAY_BLOCKED +HOSTNAME_BLOCKED + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +ok +test container_cannot_write_to_host_through_default_mount ... $ shuru run --from docker --mount /.tmpAWI21I:/workspace +--- stdout --- +from-host +WROTE_IN_GUEST +HOST_FS_ABSENT + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +ok +test container_egress_follows_host_allowlist ... $ shuru run --from docker --allow-net --allow-host example.com +--- stdout --- +Example Domain +ALLOWED_OK +DOMAIN_BLOCKED +IP_BLOCKED +DNS_BLOCKED + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +ok +test container_has_no_egress_without_allow_net ... $ shuru run --from docker +--- stdout --- +guest-eth0=Device "eth0" does not exist. +EGRESS_BLOCKED + +IP_BLOCKED + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +wget: bad address 'example.com' +wget: can't connect to remote host (93.184.215.14): Network unreachable + +ok +test dockerd_runs_pinned_image_as_non_root_with_default_isolation ... $ shuru run --from docker +--- stdout --- +cgroupfs cgroup-v2 storage=overlayfs kernel=6.12.114 security=[name=seccomp,profile=builtin name=cgroupns name=no-new-privileges] +docker=29.9.2 containerd=v2.4.2 runc=1.5.2 +digest=nginxinc/nginx-unprivileged@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 user=101 +uid=101 +nginx-master-Uid: 101 101 101 101 +privileged=false +seccomp=[] +no-new-privs=NoNewPrivs: 1 +seccomp-mode=Seccomp: 2 + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +ok +test http_through_port_forward_reaches_container ... $ shuru run --from docker -p 61346:8080 +--- stdout --- +READY +STOPPED + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: forwarding 127.0.0.1:61346 -> guest:8080 + +$ GET http://127.0.0.1:61346/ +HTTP/1.1 200 OK +Server: nginx/1.31.7 +Date: Mon, 26 Oct 2026 00:21:17 GMT +Content-Type: text/html +Content-Length: 19 +Last-Modified: Mon, 26 Oct 2026 00:21:15 GMT +Connection: close +ETag: "6ade9cfb-13" +Accept-Ranges: bytes + +shuru-docker-72816 + +ok +test named_volume_persists_across_container_and_daemon_restart ... $ shuru run --from docker +--- stdout --- +after-container-restart=persisted-72816 +after-daemon-restart=persisted-72816 + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +ok +test named_volume_persists_across_vm_stop_start_via_checkpoint ... $ shuru checkpoint create shuru-test-docker-data-72816 --from docker +--- stdout --- + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: saving checkpoint 'shuru-test-docker-data-72816'... +shuru: checkpoint 'shuru-test-docker-data-72816' saved + +$ shuru run --from shuru-test-docker-data-72816 +--- stdout --- +after-vm-restart=vm-persisted-72816 + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +ok +test resource_limits_apply_inside_containers ... $ shuru run --from docker +--- stdout --- +memory.max=67108864 +cpu.max=50000 100000 +pids.max=20 +oom-exit=137 +sh: can't fork: Resource temporarily unavailable + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +WARNING: Your kernel does not support swap limit capabilities or the cgroup is not mounted. Memory limited without swap. +WARNING: Your kernel does not support swap limit capabilities or the cgroup is not mounted. Memory limited without swap. + +ok + +test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 123.84s + +exit=0 diff --git a/docs/rfcs/0003-docker-on-shuru.md b/docs/rfcs/0003-docker-on-shuru.md new file mode 100644 index 0000000..204b679 --- /dev/null +++ b/docs/rfcs/0003-docker-on-shuru.md @@ -0,0 +1,329 @@ +# RFC 0003: Docker Engine inside a Shuru VM + +- Status: Implemented +- Date: 2026-10-26 +- Scope: kernel/shuru_defconfig, shuru-guest init, shuru-vm data dir, scripts, shuru-cli integration tests + +## Summary + +Run an unmodified Docker Engine inside a Shuru microVM and start one small, +maintained, non-root HTTP server image pinned by digest: + + nginxinc/nginx-unprivileged:1.31.7-alpine-slim + @sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 + +Docker is not baked into the base rootfs. It is installed into a checkpoint +with the existing `shuru checkpoint create` flow, pinned to exact package +versions from the Docker apt repository, with the image pre-pulled. The guest +kernel gains the options a container runtime needs, and the guest init mounts +cgroup v2 and the tmpfs directories any container runtime assumes. + +Nothing about the sandbox boundary changes. Containers sit inside the VM, the +VM sits inside the existing proxy, port forwarding, and mount policy. Docker +isolation inside the VM stays at its defaults: seccomp on, no privileged +containers, no host socket, no host networking. + +## Motivation + +Agents increasingly need to run a service exactly as it ships, which means a +container image. Today that requires either translating a Dockerfile into apt +commands by hand or giving the agent the host Docker socket, which is the +opposite of what Shuru exists for. A VM that can run dockerd gives the agent +the real tool while the host keeps the same boundary it has for everything +else Shuru runs. + +## Non-goals + +- Docker Desktop style integration (host CLI talking to a VM daemon). The + daemon socket stays inside the guest. +- Rootless dockerd. The guest already runs everything as root inside a VM; + rootless would add complexity without changing the host boundary. +- Swarm, IPVS, overlay networks, VXLAN. Not enabled in the kernel. +- GPU or device passthrough. +- Nested virtualization. + +## Design + +### Kernel + +`kernel/shuru_defconfig` grows a "Container runtime support" section. The +required set is what moby's `contrib/check-config.sh` lists, minus IPVS: + +- cgroup v2 controllers runc uses: cpu with bandwidth (`CFS_BANDWIDTH`), + cpuset, io (`BLK_CGROUP`), memory and pids were already on. +- `CGROUP_BPF` and `BPF_SYSCALL`: on cgroup v2, device access rules are an + eBPF program. Without it runc refuses to start a non-userns container. + `BPF_UNPRIV_DEFAULT_OFF` keeps bpf() root-only inside the guest. +- `SECCOMP_FILTER`: the default Docker seccomp profile. +- `KEYS`: runc joins a session keyring per container. +- `VETH`, `BRIDGE_NETFILTER`, and the xt matches and targets dockerd installs + through iptables-nft (`addrtype`, `conntrack`, `comment`, `mark`, DNAT, + MASQUERADE, raw and mangle tables, plus the ip6 equivalents). `NFT_COMPAT` + is what lets iptables-nft load xt extensions at all. +- `EXT4_FS_SECURITY` for overlay2 security xattrs. +- `IKCONFIG_PROC` so `check-config.sh` can audit the running guest. + +The kernel version default moves from 6.12.17 to 6.12.114, the current 6.12 +LTS release. Both build scripts honour `SHURU_DATA_DIR` so a build can land +somewhere other than the installed assets. `scripts/build-kernel-hf.sh` builds +the same defconfig on a Hugging Face CPU job for hosts without Docker or disk. + +### Guest init + +`mount_filesystems` in shuru-guest additionally mounts: + +- `tmpfs` on `/run` (with `/run/lock`). Pid files and sockets no longer leak + into checkpoints, which otherwise leaves dockerd refusing to start from a + checkpoint because of a stale `/run/docker.pid`. +- `tmpfs` on `/dev/shm`, mode 1777. +- `cgroup2` on `/sys/fs/cgroup` with `nsdelegate,memory_recursiveprot`, and + every available controller enabled in the root `cgroup.subtree_control`. + +These are what a normal init does and they apply to every sandbox, not only +Docker ones. The behaviour change is that `/run` is no longer persisted into +checkpoints. + +### Docker checkpoint + +`scripts/prepare-docker-checkpoint.sh` creates a checkpoint (default name +`docker`) by running, inside a VM with a strict host allowlist: + +1. Enable the trixie-security and trixie-updates archives (debootstrap only + lists main) and `apt-get upgrade`. +2. Add the Docker apt repository with its signing key verified against a + pinned SHA-256, then install `docker-ce`, `docker-ce-cli` and + `containerd.io` at exact pinned versions. +3. Write `/etc/docker/daemon.json` with `no-new-privileges: true`. Everything + else stays at Docker defaults (iptables on, userland proxy on, seccomp + default profile, overlay2, json-file logs). +4. Install `/usr/local/bin/with-dockerd`, which starts containerd and dockerd, + waits for the socket, runs the given command, then stops dockerd cleanly so + the disk is consistent for checkpointing. +5. `docker pull` the pinned image so the checkpoint runs it without network. + +The checkpoint is the unit users reuse: `shuru run --from docker -p 8080:8080 +-- with-dockerd docker run ...`. + +### Data dir isolation + +`default_data_dir()` in shuru-vm reads `SHURU_DATA_DIR` before falling back +to `~/.local/share/shuru`. This is what lets the whole verification run with +its own kernel, initramfs, checkpoints and instances without touching the +installed assets, and what the integration tests use. + +### How traffic flows + +- Host `127.0.0.1:P` to container: existing vsock forward to guest + `127.0.0.1:P`, answered by docker-proxy, which relays to the container. +- Container egress: container to docker0, MASQUERADE in the guest, eth0, the + smoltcp proxy on the host. The proxy sees ordinary guest TCP and DNS, so the + domain allowlist and DNS pinning apply unchanged. Without `--allow-net` + there is no eth0 and containers have no egress at all. +- Container DNS: the default bridge copies the guest `/etc/resolv.conf`, + which points at 10.0.0.1, the proxy. A container that sets `--dns 8.8.8.8` + sends UDP to an address the proxy does not serve, so it gets nothing. + +## Security + +What stays the same: the host boundary. Containers run as processes of a +guest kernel inside the VM. The only paths out are the ones Shuru already +exposes to any guest process: the proxy (policy applied), explicit port +forwards (host dials in, never out), and explicit mounts (read-only overlay +by default). + +What this adds inside the guest: bpf() and keyctl() syscalls, seccomp, and +netfilter surface, all reachable only by root in the guest. The container to +guest-root boundary is Docker's own and is left at its defaults. The guest +root to host boundary is unchanged. + +Residual risks and limits: + +- A container escape to guest root gains what any sandbox command already + has. That is the same as today. +- The host disk only resets on exit. A long lived VM running a malicious + container has the same egress policy as a malicious `curl` in the guest. +- `--privileged`, `--cap-add`, and `-v /var/run/docker.sock` remain possible + for the guest user, as in any Docker install. They do not cross the VM + boundary, but the test suite never uses them and the docs say not to. +- Vulnerability posture is a snapshot. The RFC appendix records what was + scanned and what was found on the date of the run. + +## Testing + +`crates/shuru-cli/tests/docker.rs`, `#[ignore]` like the mount tests, boots +real VMs from the Docker checkpoint and checks: + +1. dockerd starts, reports cgroup v2, seccomp, overlay2; the pinned image runs + and `id -u` inside it is 101. +2. HTTP through `-p`: a page served by the container is fetched from the host. +3. Egress is blocked without `--allow-net`. +4. With `--allow-net --allow-host example.com`, the container fetches + example.com but a non-listed domain, a raw IP, and a custom DNS server all + fail. +5. The container cannot reach a listener on the host loopback. +6. A container bind-mounting a read-only host mount cannot write to the host. +7. `--memory`, `--cpus`, `--pids-limit` are reflected in the container cgroup + and a memory hog is OOM-killed. +8. A named volume survives container stop/start and a dockerd restart, and + survives a clean VM stop/start via checkpoint. + +Evidence from the real run is in the appendix. + +## Rollout + +The base OS image for the next release carries the new kernel and init, so +the checkpoint script works with stock assets. Until then, `SHURU_KERNEL` and +`SHURU_INITRD` point at a locally built pair. No behaviour changes for users +who never create the checkpoint, apart from `/run` being tmpfs. + +## Appendix A: Evidence + +Recorded on 2026-10-26 on a MacBook with an Apple M-series CPU, macOS 14.4.1, +8 GB RAM. All VM output below comes from real boots of the worktree CLI with +`SHURU_DATA_DIR=~/.local/share/shuru-docker-dev`, which holds its own kernel, +initramfs and checkpoint. The installed `~/.local/share/shuru` assets were not +modified. + +### Kernel + +Built with `scripts/build-kernel-hf.sh` on a Hugging Face `cpu-upgrade` job +(job `6ade955e1e112550ce7f01dc`, `hf jobs ssh --dry-run` printed the ssh +target). Source tarball verified against kernel.org `sha256sums.asc`. + + Image-6.12.114 sha256 bd0550e93ab88a9977af6c5f4ba231aeeff143cd874980a99b247ca0e2a0e633 9320960 bytes + +Guest boot on the new kernel: + + 6.12.114 + tmpfs on /run type tmpfs (rw,relatime,size=65536k,mode=755) + tmpfs on /dev/shm type tmpfs (rw,relatime,size=262144k) + cgroup2 on /sys/fs/cgroup type cgroup2 (rw,relatime,nsdelegate,memory_recursiveprot) + subtree_control: cpuset cpu io memory pids + +moby `contrib/check-config.sh` run inside the guest against `/proc/config.gz`: +every "Generally Necessary" item enabled except `NETFILTER_XT_MATCH_IPVS` +(swarm routing mesh only). Optional items left out are swarm overlay, IPVS, +SELinux, AppArmor, btrfs, macvlan, ipvlan, ftp conntrack helpers. + +### Checkpoint + +`scripts/prepare-docker-checkpoint.sh` ran inside a VM allowed to reach only +deb.debian.org, security.debian.org, download.docker.com, `*.docker.io`, +`*.docker.com`, `*.cloudflarestorage.com`: + + Docker version 29.9.2, build a82e528 + containerd containerd v2.4.2 b7a25261e029d68978bbf290df0a62fc819b3c51 + runc version 1.5.2 + Digest: sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 + nginxinc/nginx-unprivileged sha256:a8cb0f33... a8cb0f33d51f 6 days ago 30.3MB + +Image config read from the registry before pulling: `User: 101`, +`ExposedPorts: 8080/tcp`, arm64 manifest +`sha256:d99276c6bdeded8a96168938a0f1dfa158c492410019d0d3766884d0919d1b45`. + +### Runtime checks from the integration suite + +Final run, each test booting one VM from the rebuilt checkpoint: + + test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 125.51s + +Raw output is in `docs/rfcs/0003-docker-on-shuru-evidence.log`. Excerpts: + + cgroupfs cgroup-v2 storage=overlayfs kernel=6.12.114 security=[name=seccomp,profile=builtin name=cgroupns name=no-new-privileges] + docker=29.9.2 containerd=v2.4.2 runc=1.5.2 + digest=nginxinc/nginx-unprivileged@sha256:a8cb0f33... user=101 + uid=101 + nginx-master-Uid: 101 101 101 101 + privileged=false + seccomp=[] + no-new-privs=NoNewPrivs: 1 + seccomp-mode=Seccomp: 2 + +HTTP through `-p`: a page written in the guest and served by the container +came back on the host port with `HTTP/1.1 200` and `Server: nginx`; the VM +shut down after the container logged the probe request. + +Egress without `--allow-net`: + + guest-eth0=Device "eth0" does not exist + EGRESS_BLOCKED + IP_BLOCKED + +Egress with `--allow-net --allow-host example.com`: + + Example Domain + ALLOWED_OK + DOMAIN_BLOCKED (www.iana.org, DNS refused by the proxy) + IP_BLOCKED (1.1.1.1, not DNS-pinned) + DNS_BLOCKED (--dns 8.8.8.8, UDP not relayed) + +Host loopback listener on a random port, with and without `--allow-net`: +`GATEWAY_BLOCKED`, `HOSTNAME_BLOCKED`, and the host listener accepted no +connection. + +Read-only host mount bind-mounted into a container: the container read the +host file, wrote `escaped.txt` into the guest overlay, and the file never +appeared on the host. `-v /:/vmroot` shows no `/Users`, the VM root only. + +Resource limits: + + memory.max=67108864 + cpu.max=50000 100000 + pids.max=20 + oom-exit=137 (32 MB limit, 200 MB allocation) + (fork beyond --pids-limit 5 fails, "forked-all" never printed) + +Named volume: data written through `docker exec` survived `docker stop` and +`docker start`, survived stopping and restarting dockerd, and survived a +clean VM stop and start through `shuru checkpoint create --from docker`. + +### Vulnerability posture + +Image, Trivy 0.76 with the 2026-10-25 database, `linux/arm64`: + + alpine 3.24.2 Total: 3 (UNKNOWN: 2, MEDIUM: 1, HIGH: 0, CRITICAL: 0) + musl 1.2.6-r2 -> fixed in 1.2.6-r3 (CVE-2026-107891, no severity yet) + zlib 1.3.2-r0 -> fixed in 1.3.2-r1 (CVE-2026-85091, medium, heap overflow) + +Both fixes landed in Alpine after the 2026-10-19 image build. There is no +newer `nginx-unprivileged` build yet. Residual: a medium zlib issue in a +process that runs as uid 101 under seccomp inside a VM. Re-run +`prepare-docker-checkpoint.sh` with a newer digest when the image rebuilds. + +Guest Debian layer, `debsecan --suite trixie --only-fixed` inside the VM: +36 fixable package entries (openssl, curl, expat, pcre2, brotli, xz) before +enabling the security archive, 0 after. 294 entries remain open with no +Debian fix available; that is the normal trixie backlog of low and +unimportant issues and is not actionable from this repo. + +Runtime components, GitHub advisory database queried for the exact +versions, with a control query against runc 1.1.11 returning 5 advisories: + + containerd/containerd/v2 2.4.2 0 advisories (latest release, 2026-10-13) + moby 29.9.2 0 advisories (latest release, 2026-10-20) + opencontainers/runc 1.5.2 0 advisories (latest release, 2026-09-25) + +Kernel 6.12.114 is the current 6.12 LTS release at build time. + +Not scanned: the proxy and CLI Rust dependencies (unchanged by this RFC) and +the kernel against per-CVE data (LTS point release is the mitigation). + +### Reproduction + + # kernel (HF job) and initramfs into an isolated data dir + export SHURU_DATA_DIR=~/.local/share/shuru-docker-dev + cargo build -p shuru-guest --target aarch64-unknown-linux-musl --release + ./scripts/build-kernel-hf.sh # or ./scripts/build-kernel.sh with Docker + ln -s ~/.local/share/shuru/rootfs.ext4 $SHURU_DATA_DIR/rootfs.ext4 + ./scripts/prepare-rootfs.sh # only builds the initramfs here + + # CLI: sign a copy, cargo test relinks target/debug/shuru + cargo build -p shuru-cli + cp target/debug/shuru /tmp/shuru-signed + codesign --entitlements shuru.entitlements --force -s - /tmp/shuru-signed + + export SHURU_KERNEL=$SHURU_DATA_DIR/Image SHURU_INITRD=$SHURU_DATA_DIR/initramfs.cpio.gz + export SHURU_ROOTFS=~/.local/share/shuru/rootfs.ext4 + SHURU_BIN=/tmp/shuru-signed ./scripts/prepare-docker-checkpoint.sh + SHURU_BIN=/tmp/shuru-signed SHURU_TEST_NET=1 \ + cargo test -p shuru-cli --test docker -- --ignored --test-threads=1 From f7e09a531a19c7d17e893503e4a4aa9460f9747a Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 06:37:31 +0530 Subject: [PATCH 11/57] guest: services and graceful shutdown (RFC 0004) An image declares long running processes in /etc/shuru/services/.json. Init starts them after networking, gates exec requests on their readiness check, and on SHUTDOWN_REQ sends SIGTERM, waits out each stop timeout, SIGKILLs what remains, syncs, and replies. The host Sandbox::stop() now performs that handshake before power off and kill() is the old hard stop, so checkpoints are cloned from a consistent disk on every stop path. The separate sync exec before checkpoint creation goes away. --- crates/shuru-cli/src/checkpoint.rs | 3 +- crates/shuru-cli/src/vm.rs | 25 +- crates/shuru-cli/tests/services.rs | 179 ++++++++ crates/shuru-guest/src/main.rs | 23 +- crates/shuru-guest/src/services.rs | 487 +++++++++++++++++++++ crates/shuru-proto/src/frame.rs | 4 + crates/shuru-proto/src/lib.rs | 13 + crates/shuru-vm/src/sandbox.rs | 55 ++- docs/rfcs/0004-guest-services-evidence.log | 265 +++++++++++ docs/rfcs/0004-guest-services.md | 257 +++++++++++ 10 files changed, 1299 insertions(+), 12 deletions(-) create mode 100644 crates/shuru-cli/tests/services.rs create mode 100644 crates/shuru-guest/src/services.rs create mode 100644 docs/rfcs/0004-guest-services-evidence.log create mode 100644 docs/rfcs/0004-guest-services.md diff --git a/crates/shuru-cli/src/checkpoint.rs b/crates/shuru-cli/src/checkpoint.rs index b44ef42..7e94d10 100644 --- a/crates/shuru-cli/src/checkpoint.rs +++ b/crates/shuru-cli/src/checkpoint.rs @@ -31,8 +31,7 @@ pub(crate) fn create( bail!("checkpoint '{}' already exists, delete it first", name); } - let mut prepared = vm::prepare_vm(vm_args, &cfg, from)?; - prepared.sync_before_stop = true; + let prepared = vm::prepare_vm(vm_args, &cfg, from)?; let result = vm::run_command(&prepared, &command)?; std::fs::create_dir_all(&checkpoints_dir)?; diff --git a/crates/shuru-cli/src/vm.rs b/crates/shuru-cli/src/vm.rs index a6d2431..6dc2126 100644 --- a/crates/shuru-cli/src/vm.rs +++ b/crates/shuru-cli/src/vm.rs @@ -64,10 +64,6 @@ pub(crate) struct PreparedVm { pub memory: u64, pub disk_size: u64, pub proxy_config: Option, - /// Flush guest page cache to disk before stopping. Set for checkpoint - /// creation, where the disk is cloned after the hard stop and unsynced - /// writes would silently vanish from the saved image. - pub sync_before_stop: bool, pub verbose: bool, pub forwards: Vec, pub mounts: Vec, @@ -275,7 +271,6 @@ pub(crate) fn prepare_vm( memory, disk_size, proxy_config, - sync_before_stop: false, verbose, forwards, mounts, @@ -428,12 +423,26 @@ pub(crate) fn run_command(prepared: &PreparedVm, command: &[String]) -> Result { + if prepared.verbose && !report.stopped.is_empty() { + eprintln!("shuru: stopped services: {}", report.stopped.join(", ")); + } + if !report.killed.is_empty() { + eprintln!( + "shuru: services ignored SIGTERM and were killed: {}", + report.killed.join(", ") + ); + } + } + Err(e) => eprintln!("shuru: guest shutdown failed, powering off: {}", e), } + trace_boot("guest shut down"); drop(proxy_handle); - let _ = sandbox.stop(); + let _ = sandbox.kill(); Ok(RunResult { exit_code, nbd_handle }) } diff --git a/crates/shuru-cli/tests/services.rs b/crates/shuru-cli/tests/services.rs new file mode 100644 index 0000000..9452609 --- /dev/null +++ b/crates/shuru-cli/tests/services.rs @@ -0,0 +1,179 @@ +//! Guest services (RFC 0004). Each test builds a throwaway checkpoint from +//! the base rootfs with a small shell service and boots real VMs from it, +//! so every test is #[ignore]d. Run with: +//! +//! SHURU_BIN=target/debug/shuru cargo test -p shuru-cli --test services -- --ignored +//! +//! SHURU_BIN must be a codesigned binary (see tests/docker.rs). SHURU_DATA_DIR, +//! SHURU_KERNEL and SHURU_INITRD are inherited by the CLI. + +use std::process::{Command, Output, Stdio}; + +use base64::Engine; + +fn shuru_bin() -> String { + std::env::var("SHURU_BIN") + .expect("SHURU_BIN not set: point it at a codesigned shuru binary (e.g. just build)") +} + +fn guest_cmd(script: &str) -> Vec { + let b64 = base64::engine::general_purpose::STANDARD.encode(script.as_bytes()); + vec![ + "sh".into(), + "-c".into(), + format!("echo {} | base64 -d | sh", b64), + ] +} + +fn text(out: &Output) -> String { + format!( + "--- stdout ---\n{}\n--- stderr ---\n{}", + String::from_utf8_lossy(&out.stdout), + String::from_utf8_lossy(&out.stderr) + ) +} + +fn stdout(out: &Output) -> String { + String::from_utf8_lossy(&out.stdout).to_string() +} + +fn stderr(out: &Output) -> String { + String::from_utf8_lossy(&out.stderr).to_string() +} + +fn shuru(args: &[&str], script: &str) -> Output { + let out = Command::new(shuru_bin()) + .args(args) + .arg("--") + .args(guest_cmd(script)) + .stdin(Stdio::null()) + .output() + .expect("failed to spawn shuru"); + eprintln!("$ shuru {}\n{}", args.join(" "), text(&out)); + out +} + +/// A checkpoint that is deleted when dropped, so a failed assertion does +/// not leave it behind. +struct Checkpoint(String); + +impl Checkpoint { + fn create(suffix: &str, from: Option<&str>, setup: &str) -> Self { + let name = format!("shuru-test-svc-{}-{}", suffix, std::process::id()); + let mut args = vec!["checkpoint", "create", name.as_str(), "--verbose"]; + if let Some(from) = from { + args.extend(["--from", from]); + } + let out = shuru(&args, setup); + assert!(out.status.success(), "checkpoint create failed\n{}", text(&out)); + Checkpoint(name) + } +} + +impl Drop for Checkpoint { + fn drop(&mut self) { + let _ = Command::new(shuru_bin()) + .args(["checkpoint", "delete", &self.0]) + .output(); + } +} + +/// Writes a service file. The JSON is passed through base64 so the shell +/// never sees its quotes. +fn declare(name: &str, json: &str) -> String { + let b64 = base64::engine::general_purpose::STANDARD.encode(json.as_bytes()); + format!( + "mkdir -p /etc/shuru/services && echo {} | base64 -d > /etc/shuru/services/{}.json\n", + b64, name + ) +} + +#[test] +#[ignore] +fn service_with_delayed_ready_check_gates_the_command() { + let setup = declare( + "slow", + r#"{"exec": ["sh", "-c", "sleep 2; touch /run/slow-ready; exec sleep infinity"], + "ready": ["test", "-f", "/run/slow-ready"], + "ready_timeout_secs": 20, "stop_timeout_secs": 5}"#, + ) + &declare( + "fast", + r#"{"exec": ["sh", "-c", "echo fast-started; exec sleep infinity"]}"#, + ); + let ckpt = Checkpoint::create("gate", None, &setup); + + let out = shuru( + &["run", "--from", &ckpt.0, "--verbose"], + r#" +if [ -f /run/slow-ready ]; then echo GATED_OK; else echo GATED_FAIL; fi +echo "fast-log=$(cat /run/shuru/log/fast.log)" +echo "slow-alive=$(pgrep -c -f "sleep infinity")" +"#, + ); + assert!(out.status.success(), "{}", text(&out)); + let s = stdout(&out); + assert!(s.contains("GATED_OK"), "{}", text(&out)); + assert!(s.contains("fast-log=fast-started"), "{}", text(&out)); + assert!(s.contains("slow-alive=2"), "{}", text(&out)); + assert!(stderr(&out).contains("stopped services: fast, slow"), "{}", text(&out)); +} + +#[test] +#[ignore] +fn service_that_fails_blocks_the_command_with_its_log() { + let setup = declare( + "bad", + r#"{"exec": ["sh", "-c", "echo booting bad service; sleep 1; echo giving up; exit 3"], + "ready": ["false"], "ready_timeout_secs": 10}"#, + ); + let ckpt = Checkpoint::create("fail", None, &setup); + + let out = shuru(&["run", "--from", &ckpt.0], "echo SHOULD_NOT_RUN"); + assert!(!out.status.success(), "{}", text(&out)); + assert!(!stdout(&out).contains("SHOULD_NOT_RUN"), "{}", text(&out)); + let e = stderr(&out); + assert!(e.contains("service bad exited with status 3"), "{}", text(&out)); + assert!(e.contains("giving up"), "{}", text(&out)); +} + +#[test] +#[ignore] +fn shutdown_delivers_sigterm_and_syncs_before_the_checkpoint_is_cloned() { + let setup = declare( + "trap", + r#"{"exec": ["sh", "-c", "trap \"echo got-term > /var/lib/trap-marker; exit 0\" TERM; while true; do sleep 1; done"], + "stop_timeout_secs": 10}"#, + ); + let base = Checkpoint::create("term", None, &setup); + let derived = Checkpoint::create("term-derived", Some(&base.0), "echo RAN_IN_BASE"); + + let out = shuru( + &["run", "--from", &derived.0], + "cat /var/lib/trap-marker 2>/dev/null || echo NO_MARKER", + ); + assert!(out.status.success(), "{}", text(&out)); + assert!(stdout(&out).contains("got-term"), "{}", text(&out)); +} + +#[test] +#[ignore] +fn service_ignoring_sigterm_is_killed_after_its_stop_timeout() { + let setup = declare( + "stubborn", + r#"{"exec": ["sh", "-c", "trap \"\" TERM; while true; do sleep 1; done"], + "stop_timeout_secs": 2}"#, + ); + let ckpt = Checkpoint::create("kill", None, &setup); + + let start = std::time::Instant::now(); + let out = shuru(&["run", "--from", &ckpt.0], "echo RAN"); + let elapsed = start.elapsed(); + assert!(out.status.success(), "{}", text(&out)); + assert!(stdout(&out).contains("RAN"), "{}", text(&out)); + assert!( + stderr(&out).contains("services ignored SIGTERM and were killed: stubborn"), + "{}", + text(&out) + ); + assert!(elapsed.as_secs() < 30, "stop took {:?}", elapsed); +} diff --git a/crates/shuru-guest/src/main.rs b/crates/shuru-guest/src/main.rs index 57d12b1..78454bb 100644 --- a/crates/shuru-guest/src/main.rs +++ b/crates/shuru-guest/src/main.rs @@ -1,3 +1,6 @@ +#[cfg(target_os = "linux")] +mod services; + #[cfg(target_os = "linux")] mod guest { use std::io::{Read, Write}; @@ -294,10 +297,12 @@ mod guest { fn reap_zombies() { loop { - let ret = unsafe { libc::waitpid(-1, std::ptr::null_mut(), libc::WNOHANG) }; + let mut status: libc::c_int = 0; + let ret = unsafe { libc::waitpid(-1, &mut status, libc::WNOHANG) }; if ret <= 0 { break; } + crate::services::reaped(ret, status); } } @@ -421,6 +426,13 @@ mod guest { continue; } + // Services declared by the image must be ready before a + // command runs against them (RFC 0004). + if let Err(msg) = crate::services::wait_ready() { + let _ = frame::write_frame(&mut writer, frame::ERROR, msg.as_bytes()); + continue; + } + if req.tty.unwrap_or(false) { // TTY mode: hand off the raw fd let raw_fd = std::os::unix::io::AsRawFd::as_raw_fd(&writer); @@ -568,6 +580,10 @@ mod guest { }; handle_download(&req, &mut writer); } + frame::SHUTDOWN_REQ => { + let resp = crate::services::shutdown(); + let _ = frame::send_json(&mut writer, frame::SHUTDOWN_RESP, &resp); + } _ => {} // unknown type, skip } } @@ -1675,6 +1691,11 @@ mod guest { setup_networking(); stage("networking ready"); + let started = crate::services::start_all(); + if started > 0 { + stage(&format!("{} service(s) starting", started)); + } + // Register signal handlers (PID 1 has no default signal dispositions) unsafe { libc::signal( diff --git a/crates/shuru-guest/src/services.rs b/crates/shuru-guest/src/services.rs new file mode 100644 index 0000000..450bcc3 --- /dev/null +++ b/crates/shuru-guest/src/services.rs @@ -0,0 +1,487 @@ +//! Guest services (RFC 0004): long running processes declared by the image +//! under /etc/shuru/services/.json. Init starts them at boot, gates +//! exec requests on their readiness, and stops them on SHUTDOWN_REQ. + +use std::collections::HashMap; +use std::os::unix::process::CommandExt; +use std::process::{Command, Stdio}; +use std::sync::{Condvar, Mutex}; +use std::time::{Duration, Instant}; + +use shuru_proto::ShutdownResponse; + +const SERVICES_DIR: &str = "/etc/shuru/services"; +const LOG_DIR: &str = "/run/shuru/log"; +const READY_POLL: Duration = Duration::from_millis(250); +const DEFAULT_READY_TIMEOUT: u64 = 30; +const DEFAULT_STOP_TIMEOUT: u64 = 15; +const LOG_TAIL_LINES: usize = 20; + +#[derive(Clone, Debug, PartialEq)] +enum State { + Starting, + Ready, + Failed(String), + Stopped, +} + +struct Spec { + name: String, + exec: Vec, + ready: Option>, + ready_timeout: Duration, + stop_timeout: Duration, + env: HashMap, + cwd: String, +} + +struct Service { + name: String, + pid: i32, + state: State, + stop_timeout: Duration, +} + +struct Registry { + services: Vec, + shutting_down: bool, +} + +static REGISTRY: Mutex = Mutex::new(Registry { + services: Vec::new(), + shutting_down: false, +}); +static CHANGED: Condvar = Condvar::new(); + +fn log_line(msg: &str) { + let s = format!("shuru-guest: {}\n", msg); + unsafe { libc::write(2, s.as_ptr() as *const libc::c_void, s.len()) }; +} + +fn registry() -> std::sync::MutexGuard<'static, Registry> { + REGISTRY.lock().unwrap_or_else(|e| e.into_inner()) +} + +fn valid_name(name: &str) -> bool { + let mut chars = name.chars(); + match chars.next() { + Some(c) if c.is_ascii_lowercase() || c.is_ascii_digit() => {} + _ => return false, + } + chars.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-') +} + +fn argv_field(value: &serde_json::Value, key: &str) -> Result>, String> { + match value.get(key) { + None | Some(serde_json::Value::Null) => Ok(None), + Some(serde_json::Value::Array(items)) => { + let mut argv = Vec::with_capacity(items.len()); + for item in items { + match item.as_str() { + Some(s) => argv.push(s.to_string()), + None => return Err(format!("{} must be an array of strings", key)), + } + } + if argv.is_empty() { + return Err(format!("{} must not be empty", key)); + } + Ok(Some(argv)) + } + Some(_) => Err(format!("{} must be an array of strings", key)), + } +} + +fn secs_field(value: &serde_json::Value, key: &str, default: u64) -> Result { + match value.get(key) { + None | Some(serde_json::Value::Null) => Ok(Duration::from_secs(default)), + Some(v) => match v.as_u64() { + Some(n) => Ok(Duration::from_secs(n)), + None => Err(format!("{} must be a non-negative integer", key)), + }, + } +} + +fn parse_spec(name: &str, text: &str) -> Result { + let value: serde_json::Value = serde_json::from_str(text).map_err(|e| e.to_string())?; + if !value.is_object() { + return Err("service file must be a JSON object".into()); + } + let exec = argv_field(&value, "exec")?.ok_or("exec is required")?; + let ready = argv_field(&value, "ready")?; + let ready_timeout = secs_field(&value, "ready_timeout_secs", DEFAULT_READY_TIMEOUT)?; + let stop_timeout = secs_field(&value, "stop_timeout_secs", DEFAULT_STOP_TIMEOUT)?; + let mut env = HashMap::new(); + if let Some(obj) = value.get("env") { + match obj.as_object() { + Some(map) => { + for (k, v) in map { + match v.as_str() { + Some(s) => { + env.insert(k.clone(), s.to_string()); + } + None => return Err("env values must be strings".into()), + } + } + } + None if obj.is_null() => {} + None => return Err("env must be an object".into()), + } + } + let cwd = match value.get("cwd") { + None | Some(serde_json::Value::Null) => "/".to_string(), + Some(v) => v + .as_str() + .map(str::to_string) + .ok_or("cwd must be a string")?, + }; + Ok(Spec { + name: name.to_string(), + exec, + ready, + ready_timeout, + stop_timeout, + env, + cwd, + }) +} + +fn load_specs() -> Vec { + let entries = match std::fs::read_dir(SERVICES_DIR) { + Ok(e) => e, + Err(_) => return Vec::new(), + }; + let mut specs = Vec::new(); + for entry in entries.flatten() { + let path = entry.path(); + if path.extension().and_then(|e| e.to_str()) != Some("json") { + continue; + } + let name = match path.file_stem().and_then(|s| s.to_str()) { + Some(n) if valid_name(n) => n.to_string(), + _ => { + log_line(&format!("ignoring service file {}: bad name", path.display())); + continue; + } + }; + let text = match std::fs::read_to_string(&path) { + Ok(t) => t, + Err(e) => { + log_line(&format!("ignoring service {}: {}", name, e)); + continue; + } + }; + match parse_spec(&name, &text) { + Ok(spec) => specs.push(spec), + Err(e) => log_line(&format!("ignoring service {}: {}", name, e)), + } + } + specs.sort_by(|a, b| a.name.cmp(&b.name)); + specs +} + +fn log_path(name: &str) -> String { + format!("{}/{}.log", LOG_DIR, name) +} + +fn spawn(spec: &Spec) -> std::io::Result { + std::fs::create_dir_all(LOG_DIR)?; + let log = std::fs::OpenOptions::new() + .create(true) + .append(true) + .open(log_path(&spec.name))?; + let log_err = log.try_clone()?; + let mut cmd = Command::new(&spec.exec[0]); + cmd.args(&spec.exec[1..]); + cmd.envs(&spec.env); + cmd.current_dir(&spec.cwd); + cmd.stdin(Stdio::null()); + cmd.stdout(Stdio::from(log)); + cmd.stderr(Stdio::from(log_err)); + // Own process group so a stop can reach anything the service forked. + unsafe { + cmd.pre_exec(|| { + libc::setpgid(0, 0); + Ok(()) + }); + } + let child = cmd.spawn()?; + Ok(child.id() as i32) +} + +/// Non-blocking exit check. `None` while running, `Some(status)` once the +/// process is gone. A status of -1 means the main loop reaped it first. +fn poll_exit(pid: i32) -> Option { + let mut status: libc::c_int = 0; + let r = unsafe { libc::waitpid(pid, &mut status, libc::WNOHANG) }; + if r == pid { + Some(status) + } else if r < 0 { + Some(-1) + } else { + None + } +} + +fn describe_exit(status: i32) -> String { + if status < 0 { + "exited".to_string() + } else if libc::WIFEXITED(status) { + format!("exited with status {}", libc::WEXITSTATUS(status)) + } else if libc::WIFSIGNALED(status) { + format!("killed by signal {}", libc::WTERMSIG(status)) + } else { + "exited".to_string() + } +} + +fn set_state(name: &str, state: State) { + let mut reg = registry(); + if let Some(svc) = reg.services.iter_mut().find(|s| s.name == name) { + if matches!(svc.state, State::Stopped) { + return; + } + svc.state = state; + } + drop(reg); + CHANGED.notify_all(); +} + +/// Called by the PID 1 reaper for every child it collects, so a service +/// that dies at any point is recorded even when no thread is polling it. +pub fn reaped(pid: i32, status: i32) { + let name = { + let reg = registry(); + if reg.shutting_down { + return; + } + reg.services + .iter() + .find(|s| s.pid == pid && s.state != State::Stopped) + .map(|s| s.name.clone()) + }; + if let Some(name) = name { + log_line(&format!("service {} {}", name, describe_exit(status))); + set_state(&name, State::Failed(describe_exit(status))); + } +} + +fn ready_check_passes(spec: &Spec, ready: &[String]) -> bool { + Command::new(&ready[0]) + .args(&ready[1..]) + .envs(&spec.env) + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .status() + .map(|s| s.success()) + .unwrap_or(false) +} + +fn watch_until_ready(spec: Spec, pid: i32) { + let deadline = Instant::now() + spec.ready_timeout; + loop { + if let Some(status) = poll_exit(pid) { + set_state(&spec.name, State::Failed(describe_exit(status))); + log_line(&format!("service {} {}", spec.name, describe_exit(status))); + return; + } + match &spec.ready { + None => { + set_state(&spec.name, State::Ready); + return; + } + Some(ready) => { + if ready_check_passes(&spec, ready) { + set_state(&spec.name, State::Ready); + log_line(&format!("service {} ready", spec.name)); + return; + } + } + } + if Instant::now() >= deadline { + let msg = format!( + "not ready after {}s", + spec.ready_timeout.as_secs() + ); + log_line(&format!("service {} {}", spec.name, msg)); + set_state(&spec.name, State::Failed(msg)); + return; + } + std::thread::sleep(READY_POLL); + } +} + +/// Spawn every declared service. Returns the number started. +pub fn start_all() -> usize { + let specs = load_specs(); + let mut started = 0; + for spec in specs { + let pid = match spawn(&spec) { + Ok(pid) => pid, + Err(e) => { + log_line(&format!("service {} failed to start: {}", spec.name, e)); + registry().services.push(Service { + name: spec.name.clone(), + pid: 0, + state: State::Failed(format!("failed to start: {}", e)), + stop_timeout: spec.stop_timeout, + }); + continue; + } + }; + registry().services.push(Service { + name: spec.name.clone(), + pid, + state: State::Starting, + stop_timeout: spec.stop_timeout, + }); + started += 1; + std::thread::spawn(move || watch_until_ready(spec, pid)); + } + started +} + +fn log_tail(name: &str) -> String { + let text = std::fs::read_to_string(log_path(name)).unwrap_or_default(); + let lines: Vec<&str> = text.lines().collect(); + let start = lines.len().saturating_sub(LOG_TAIL_LINES); + lines[start..].join("\n") +} + +/// Pick up exits the reaper has not seen yet, so a service that died +/// between two connections is reported on the next exec. +fn poll_all() { + let pids: Vec<(String, i32)> = registry() + .services + .iter() + .filter(|s| s.pid > 0 && matches!(s.state, State::Starting | State::Ready)) + .map(|s| (s.name.clone(), s.pid)) + .collect(); + for (name, pid) in pids { + if let Some(status) = poll_exit(pid) { + if status >= 0 { + log_line(&format!("service {} {}", name, describe_exit(status))); + set_state(&name, State::Failed(describe_exit(status))); + } + } + } +} + +/// Block until no service is still starting. Ok when every service is ready +/// (or none exist), Err with a message naming the first failed service. +pub fn wait_ready() -> Result<(), String> { + if registry().shutting_down { + return Err("guest is shutting down".into()); + } + poll_all(); + let mut reg = registry(); + loop { + if reg.shutting_down { + return Err("guest is shutting down".into()); + } + if reg.services.iter().any(|s| s.state == State::Starting) { + reg = CHANGED + .wait_timeout(reg, Duration::from_millis(200)) + .unwrap_or_else(|e| e.into_inner()) + .0; + continue; + } + let failed = reg + .services + .iter() + .find_map(|s| match &s.state { + State::Failed(reason) => Some((s.name.clone(), reason.clone())), + _ => None, + }); + drop(reg); + return match failed { + None => Ok(()), + Some((name, reason)) => { + let tail = log_tail(&name); + let mut msg = format!("service {} {}", name, reason); + if !tail.is_empty() { + msg.push_str(&format!("\n--- {} ---\n{}\n", log_path(&name), tail)); + } + Err(msg) + } + }; + } +} + +/// Stop every running service (SIGTERM, then SIGKILL to its process group +/// after its stop timeout), then sync the disk. +pub fn shutdown() -> ShutdownResponse { + let targets: Vec<(String, i32, Duration)> = { + let mut reg = registry(); + reg.shutting_down = true; + reg.services + .iter() + .filter(|s| s.pid > 0 && matches!(s.state, State::Starting | State::Ready)) + .map(|s| (s.name.clone(), s.pid, s.stop_timeout)) + .collect() + }; + CHANGED.notify_all(); + + let mut resp = ShutdownResponse::default(); + if !targets.is_empty() { + let start = Instant::now(); + for (_, pid, _) in &targets { + unsafe { libc::kill(*pid, libc::SIGTERM) }; + } + let mut pending: Vec<(String, i32, Duration)> = targets; + loop { + pending.retain(|(name, pid, _)| match poll_exit(*pid) { + Some(_) => { + resp.stopped.push(name.clone()); + false + } + None => true, + }); + if pending.is_empty() { + break; + } + let elapsed = start.elapsed(); + let mut expired = Vec::new(); + pending.retain(|(name, pid, timeout)| { + if elapsed >= *timeout { + unsafe { + libc::kill(-*pid, libc::SIGKILL); + libc::kill(*pid, libc::SIGKILL); + } + expired.push((name.clone(), *pid)); + false + } else { + true + } + }); + for (name, pid) in expired { + log_line(&format!("service {} ignored SIGTERM, killed", name)); + // Reap the killed process so it does not linger as a zombie. + for _ in 0..100 { + if poll_exit(pid).is_some() { + break; + } + std::thread::sleep(Duration::from_millis(10)); + } + resp.killed.push(name); + } + if pending.is_empty() { + break; + } + std::thread::sleep(Duration::from_millis(50)); + } + resp.stopped.sort(); + resp.killed.sort(); + for name in resp.stopped.iter().chain(resp.killed.iter()) { + set_state(name, State::Stopped); + } + log_line(&format!( + "services stopped in {:.1}s (stopped: {:?}, killed: {:?})", + start.elapsed().as_secs_f64(), + resp.stopped, + resp.killed + )); + } + unsafe { libc::sync() }; + resp +} diff --git a/crates/shuru-proto/src/frame.rs b/crates/shuru-proto/src/frame.rs index 0e9ec85..31ce77d 100644 --- a/crates/shuru-proto/src/frame.rs +++ b/crates/shuru-proto/src/frame.rs @@ -53,6 +53,10 @@ pub const DISCARD_RESP: u8 = 0x4F; pub const DOWNLOAD_REQ: u8 = 0x50; pub const DOWNLOAD_PROGRESS: u8 = 0x51; +// Shutdown: host asks the guest to stop its services and sync the disk +pub const SHUTDOWN_REQ: u8 = 0x60; +pub const SHUTDOWN_RESP: u8 = 0x61; + const MAX_FRAME: u32 = 1 << 20; // 1 MB /// Write a binary frame: `[u32 BE length][u8 type][payload]`. diff --git a/crates/shuru-proto/src/lib.rs b/crates/shuru-proto/src/lib.rs index 5f3cf8f..1d1bd51 100644 --- a/crates/shuru-proto/src/lib.rs +++ b/crates/shuru-proto/src/lib.rs @@ -25,6 +25,19 @@ pub struct ExecRequest { pub cwd: Option, } +// --- Shutdown protocol --- + +/// Reply to SHUTDOWN_REQ, sent once every guest service has exited and the +/// disk is synced. `killed` lists services that ignored SIGTERM and were +/// killed after their stop timeout. +#[derive(Debug, Default, Serialize, Deserialize)] +pub struct ShutdownResponse { + #[serde(default)] + pub stopped: Vec, + #[serde(default)] + pub killed: Vec, +} + // --- Port forwarding protocol --- /// A host:guest port mapping for port forwarding over vsock. diff --git a/crates/shuru-vm/src/sandbox.rs b/crates/shuru-vm/src/sandbox.rs index f018cf2..d794cfd 100644 --- a/crates/shuru-vm/src/sandbox.rs +++ b/crates/shuru-vm/src/sandbox.rs @@ -26,7 +26,8 @@ use shuru_linux::*; use shuru_proto::{ frame, ChmodRequest, CopyRequest, DiscardRequest, ExecRequest, ForwardRequest, ForwardResponse, FsOkResponse, MkdirRequest, MountRequest, MountResponse, PortMapping, ReadDirRequest, - ReadDirResponse, ReadFileRequest, RemoveRequest, RenameRequest, StatRequest, StatResponse, + ReadDirResponse, ReadFileRequest, RemoveRequest, RenameRequest, ShutdownResponse, StatRequest, + StatResponse, WatchRequest, WriteFileRequest, WriteFileResponse, VSOCK_PORT, VSOCK_PORT_FORWARD, }; @@ -245,7 +246,37 @@ impl Sandbox { .map_err(|e| anyhow::anyhow!("Failed to start VM: {}", e)) } + /// Ask the guest to stop its services and sync the disk (RFC 0004). + /// Returns what the guest stopped, or an error if it did not answer + /// within the shutdown timeout. + pub fn shutdown(&self) -> Result { + let stream = self.connect_vsock()?; + let _ = stream.set_read_timeout(Some(SHUTDOWN_TIMEOUT)); + let (tx, rx) = std::sync::mpsc::channel(); + std::thread::spawn(move || { + let _ = tx.send(shutdown_handshake(stream)); + }); + match rx.recv_timeout(SHUTDOWN_TIMEOUT + Duration::from_secs(5)) { + Ok(result) => result, + Err(_) => bail!( + "guest did not answer the shutdown request within {}s", + SHUTDOWN_TIMEOUT.as_secs() + ), + } + } + + /// Graceful stop: shutdown handshake, then power off. Falls back to a + /// plain power off when the guest does not answer. pub fn stop(&self) -> Result<()> { + if let Err(e) = self.shutdown() { + tracing::warn!("guest shutdown failed, powering off: {}", e); + } + self.kill() + } + + /// Power off without asking the guest. Services get no SIGTERM and the + /// disk is not synced. + pub fn kill(&self) -> Result<()> { self.vm .stop() .map_err(|e| anyhow::anyhow!("Failed to stop VM: {}", e)) @@ -924,6 +955,28 @@ impl Sandbox { } } +/// Upper bound on a graceful shutdown. Covers the slowest service stop +/// timeout an image can reasonably declare, plus the sync. +const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(90); + +fn shutdown_handshake(stream: TcpStream) -> Result { + let mut writer = stream.try_clone()?; + let mut reader = stream; + frame::write_frame(&mut writer, frame::SHUTDOWN_REQ, &[])?; + loop { + match frame::read_frame(&mut reader).context("waiting for guest shutdown")? { + Some((frame::SHUTDOWN_RESP, payload)) => { + return serde_json::from_slice(&payload).context("parsing shutdown response"); + } + Some((frame::ERROR, payload)) => { + bail!("guest refused shutdown: {}", String::from_utf8_lossy(&payload)) + } + Some(_) => {} + None => bail!("guest closed the connection before answering shutdown"), + } + } +} + // --- Port forwarding --- /// Handle returned by `start_port_forwarding`. Signals all listener threads diff --git a/docs/rfcs/0004-guest-services-evidence.log b/docs/rfcs/0004-guest-services-evidence.log new file mode 100644 index 0000000..fcdacdd --- /dev/null +++ b/docs/rfcs/0004-guest-services-evidence.log @@ -0,0 +1,265 @@ + +running 4 tests +test service_ignoring_sigterm_is_killed_after_its_stop_timeout ... $ shuru checkpoint create shuru-test-svc-kill-87504 --verbose +--- stdout --- + +--- stderr --- +shuru: creating working copy... +shuru: kernel=/Image +shuru: rootfs=/instances/87505/rootfs.ext4 (work copy) +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: VM created and validated successfully +shuru: VM started, waiting for guest... +random: crng init done +virtio_blk virtio1: 1/0/0 default/read/poll queues +virtio_blk virtio1: [vda] 8388608 512-byte logical blocks (4.29 GB/4.00 GiB) +rtc-pl031 20050000.pl031: registered as rtc0 +rtc-pl031 20050000.pl031: setting system clock to 2026-10-26T00:57:55 UTC (1792976275) +NET: Registered PF_INET6 protocol family +Segment Routing with IPv6 +In-situ OAM (IOAM) with IPv6 +sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver +NET: Registered PF_PACKET protocol family +Bridge firewalling registered +NET: Registered PF_VSOCK protocol family +clk: Disabling unused clocks +Freeing unused kernel memory: 896K +Run /init as init process +EXT4-fs (vda): mounted filesystem 728de991-e6e3-4e1a-873d-bc29aeff5c07 r/w with ordered data mode. Quota mode: disabled. +shuru-guest[ 147.2ms]: starting as PID 1 +shuru-guest[ 147.5ms]: filesystems mounted +shuru-guest: no network device (sandbox mode) +shuru-guest[ 147.7ms]: networking ready +shuru-guest[ 147.8ms]: vsock listening on port 1024 +shuru-guest[ 147.8ms]: port forward listener on port 1025 +shuru-guest: accepted vsock connection +shuru-guest: accepted vsock connection +shuru: saving checkpoint 'shuru-test-svc-kill-87504'... +shuru: checkpoint 'shuru-test-svc-kill-87504' saved + +$ shuru run --from shuru-test-svc-kill-87504 +--- stdout --- +RAN + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: services ignored SIGTERM and were killed: stubborn + +ok +test service_that_fails_blocks_the_command_with_its_log ... $ shuru checkpoint create shuru-test-svc-fail-87504 --verbose +--- stdout --- + +--- stderr --- +shuru: creating working copy... +shuru: kernel=/Image +shuru: rootfs=/instances/87512/rootfs.ext4 (work copy) +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: VM created and validated successfully +shuru: VM started, waiting for guest... +random: crng init done +virtio_blk virtio1: 1/0/0 default/read/poll queues +virtio_blk virtio1: [vda] 8388608 512-byte logical blocks (4.29 GB/4.00 GiB) +rtc-pl031 20050000.pl031: registered as rtc0 +rtc-pl031 20050000.pl031: setting system clock to 2026-10-26T00:57:58 UTC (1792976278) +NET: Registered PF_INET6 protocol family +Segment Routing with IPv6 +In-situ OAM (IOAM) with IPv6 +sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver +NET: Registered PF_PACKET protocol family +Bridge firewalling registered +NET: Registered PF_VSOCK protocol family +clk: Disabling unused clocks +Freeing unused kernel memory: 896K +Run /init as init process +EXT4-fs (vda): mounted filesystem 728de991-e6e3-4e1a-873d-bc29aeff5c07 r/w with ordered data mode. Quota mode: disabled. +shuru-guest[ 134.2ms]: starting as PID 1 +shuru-guest[ 134.6ms]: filesystems mounted +shuru-guest: no network device (sandbox mode) +shuru-guest[ 134.7ms]: networking ready +shuru-guest[ 134.8ms]: vsock listening on port 1024 +shuru-guest[ 134.8ms]: port forward listener on port 1025 +shuru-guest: accepted vsock connection +shuru-guest: accepted vsock connection +shuru: saving checkpoint 'shuru-test-svc-fail-87504'... +shuru: checkpoint 'shuru-test-svc-fail-87504' saved + +$ shuru run --from shuru-test-svc-fail-87504 +--- stdout --- + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +guest error: service bad exited with status 3 +--- /run/shuru/log/bad.log --- +booting bad service +giving up + +ok +test service_with_delayed_ready_check_gates_the_command ... $ shuru checkpoint create shuru-test-svc-gate-87504 --verbose +--- stdout --- + +--- stderr --- +shuru: creating working copy... +shuru: kernel=/Image +shuru: rootfs=/instances/87519/rootfs.ext4 (work copy) +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: VM created and validated successfully +shuru: VM started, waiting for guest... +random: crng init done +virtio_blk virtio1: 1/0/0 default/read/poll queues +virtio_blk virtio1: [vda] 8388608 512-byte logical blocks (4.29 GB/4.00 GiB) +rtc-pl031 20050000.pl031: registered as rtc0 +rtc-pl031 20050000.pl031: setting system clock to 2026-10-26T00:57:59 UTC (1792976279) +NET: Registered PF_INET6 protocol family +Segment Routing with IPv6 +In-situ OAM (IOAM) with IPv6 +sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver +NET: Registered PF_PACKET protocol family +Bridge firewalling registered +NET: Registered PF_VSOCK protocol family +clk: Disabling unused clocks +Freeing unused kernel memory: 896K +Run /init as init process +EXT4-fs (vda): mounted filesystem 728de991-e6e3-4e1a-873d-bc29aeff5c07 r/w with ordered data mode. Quota mode: disabled. +shuru-guest[ 134.4ms]: starting as PID 1 +shuru-guest[ 134.8ms]: filesystems mounted +shuru-guest: no network device (sandbox mode) +shuru-guest[ 134.9ms]: networking ready +shuru-guest[ 135.0ms]: vsock listening on port 1024 +shuru-guest[ 135.0ms]: port forward listener on port 1025 +shuru-guest: accepted vsock connection +shuru-guest: accepted vsock connection +shuru: saving checkpoint 'shuru-test-svc-gate-87504'... +shuru: checkpoint 'shuru-test-svc-gate-87504' saved + +$ shuru run --from shuru-test-svc-gate-87504 --verbose +--- stdout --- +GATED_OK +fast-log=fast-started +slow-alive=2 + +--- stderr --- +shuru: creating working copy... +shuru: kernel=/Image +shuru: rootfs=/instances/87521/rootfs.ext4 (work copy) +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: VM created and validated successfully +shuru: VM started, waiting for guest... +random: crng init done +virtio_blk virtio1: 1/0/0 default/read/poll queues +virtio_blk virtio1: [vda] 8388608 512-byte logical blocks (4.29 GB/4.00 GiB) +rtc-pl031 20050000.pl031: registered as rtc0 +rtc-pl031 20050000.pl031: setting system clock to 2026-10-26T00:58:00 UTC (1792976280) +NET: Registered PF_INET6 protocol family +Segment Routing with IPv6 +In-situ OAM (IOAM) with IPv6 +sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver +NET: Registered PF_PACKET protocol family +Bridge firewalling registered +NET: Registered PF_VSOCK protocol family +clk: Disabling unused clocks +Freeing unused kernel memory: 896K +Run /init as init process +EXT4-fs (vda): mounted filesystem 728de991-e6e3-4e1a-873d-bc29aeff5c07 r/w with ordered data mode. Quota mode: disabled. +shuru-guest[ 130.3ms]: starting as PID 1 +shuru-guest[ 130.7ms]: filesystems mounted +shuru-guest: no network device (sandbox mode) +shuru-guest[ 130.8ms]: networking ready +shuru-guest[ 133.4ms]: 2 service(s) starting +shuru-guest[ 133.4ms]: vsock listening on port 1024 +shuru-guest[ 133.4ms]: port forward listener on port 1025 +shuru-guest: accepted vsock connection +shuru-guest: service slow ready +shuru-guest: accepted vsock connection +shuru-guest: services stopped in 0.1s (stopped: ["fast", "slow"], killed: []) +shuru: stopped services: fast, slow + +ok +test shutdown_delivers_sigterm_and_syncs_before_the_checkpoint_is_cloned ... $ shuru checkpoint create shuru-test-svc-term-87504 --verbose +--- stdout --- + +--- stderr --- +shuru: creating working copy... +shuru: kernel=/Image +shuru: rootfs=/instances/87526/rootfs.ext4 (work copy) +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: VM created and validated successfully +shuru: VM started, waiting for guest... +random: crng init done +virtio_blk virtio1: 1/0/0 default/read/poll queues +virtio_blk virtio1: [vda] 8388608 512-byte logical blocks (4.29 GB/4.00 GiB) +rtc-pl031 20050000.pl031: registered as rtc0 +rtc-pl031 20050000.pl031: setting system clock to 2026-10-26T00:58:02 UTC (1792976282) +NET: Registered PF_INET6 protocol family +Segment Routing with IPv6 +In-situ OAM (IOAM) with IPv6 +sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver +NET: Registered PF_PACKET protocol family +Bridge firewalling registered +NET: Registered PF_VSOCK protocol family +clk: Disabling unused clocks +Freeing unused kernel memory: 896K +Run /init as init process +EXT4-fs (vda): mounted filesystem 728de991-e6e3-4e1a-873d-bc29aeff5c07 r/w with ordered data mode. Quota mode: disabled. +shuru-guest[ 136.4ms]: starting as PID 1 +shuru-guest[ 136.8ms]: filesystems mounted +shuru-guest: no network device (sandbox mode) +shuru-guest[ 136.8ms]: networking ready +shuru-guest[ 136.9ms]: vsock listening on port 1024 +shuru-guest[ 137.0ms]: port forward listener on port 1025 +shuru-guest: accepted vsock connection +shuru-guest: accepted vsock connection +shuru: saving checkpoint 'shuru-test-svc-term-87504'... +shuru: checkpoint 'shuru-test-svc-term-87504' saved + +$ shuru checkpoint create shuru-test-svc-term-derived-87504 --verbose --from shuru-test-svc-term-87504 +--- stdout --- +RAN_IN_BASE + +--- stderr --- +shuru: creating working copy... +shuru: kernel=/Image +shuru: rootfs=/instances/87528/rootfs.ext4 (work copy) +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: VM created and validated successfully +shuru: VM started, waiting for guest... +random: crng init done +virtio_blk virtio1: 1/0/0 default/read/poll queues +virtio_blk virtio1: [vda] 8388608 512-byte logical blocks (4.29 GB/4.00 GiB) +rtc-pl031 20050000.pl031: registered as rtc0 +rtc-pl031 20050000.pl031: setting system clock to 2026-10-26T00:58:02 UTC (1792976282) +NET: Registered PF_INET6 protocol family +Segment Routing with IPv6 +In-situ OAM (IOAM) with IPv6 +sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver +NET: Registered PF_PACKET protocol family +Bridge firewalling registered +NET: Registered PF_VSOCK protocol family +clk: Disabling unused clocks +Freeing unused kernel memory: 896K +Run /init as init process +EXT4-fs (vda): mounted filesystem 728de991-e6e3-4e1a-873d-bc29aeff5c07 r/w with ordered data mode. Quota mode: disabled. +shuru-guest[ 130.2ms]: starting as PID 1 +shuru-guest[ 130.5ms]: filesystems mounted +shuru-guest: no network device (sandbox mode) +shuru-guest[ 130.6ms]: networking ready +shuru-guest[ 133.3ms]: 1 service(s) starting +shuru-guest[ 133.4ms]: vsock listening on port 1024 +shuru-guest[ 133.4ms]: port forward listener on port 1025 +shuru-guest: accepted vsock connection +shuru-guest: accepted vsock connection +shuru-guest: services stopped in 1.0s (stopped: ["trap"], killed: []) +shuru: stopped services: trap +shuru: saving checkpoint 'shuru-test-svc-term-derived-87504'... +shuru: checkpoint 'shuru-test-svc-term-derived-87504' saved + +$ shuru run --from shuru-test-svc-term-derived-87504 +--- stdout --- +got-term + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +ok + +test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 9.49s + diff --git a/docs/rfcs/0004-guest-services.md b/docs/rfcs/0004-guest-services.md new file mode 100644 index 0000000..c59e0f5 --- /dev/null +++ b/docs/rfcs/0004-guest-services.md @@ -0,0 +1,257 @@ +# RFC 0004: Guest services + +- Status: Implemented +- Date: 2026-10-26 +- Scope: shuru-guest, shuru-proto, shuru-vm, shuru-cli, Docker checkpoint script +- Depends on: RFC 0003 + +## Summary + +Let an image declare long running processes that the guest starts at boot, +waits on before running the user command, and stops cleanly before the VM +goes away. A service is one JSON file under `/etc/shuru/services/` in the +rootfs or checkpoint. Init owns the lifecycle. The host asks the guest to +shut down over vsock before it stops the VM, and the guest answers only +after every service has exited and the disk is synced. + +With this in place `shuru run --from docker -- docker run ...` just works. +The `with-dockerd` wrapper from RFC 0003 goes away. + +## Motivation + +The guest has no init system. PID 1 is shuru-init, which mounts +filesystems, brings up networking and serves the vsock control protocol. +Nothing starts daemons and nothing stops them. RFC 0003 worked around this +with a shell wrapper that started dockerd around each command, which has +four problems: + +- Every daemon needs its own copy of the wrapper and users must remember to + type it. `shuru run --from docker -- docker ps` fails with a socket error. +- Shutdown runs only on the happy path. An interrupted `shuru run`, a stop + from the SDK, or a host side error leaves the daemon without SIGTERM and + the disk without a sync. For a checkpoint build that means a cloned disk + with half written state. +- The host already hard stops the VM. There is no cooperative shutdown at + all, so even the `sync` before a checkpoint clone is a separate exec that + can be skipped by any error between the command and the stop. +- Startup cost is paid per command instead of per boot. + +Other sandboxes solve this at the platform level. E2B templates take a +start command and a ready command, and the ready command is retried until +it exits 0 before the sandbox is handed over. Sprites declare services that +start on boot and expose a lifecycle state. Shuru should offer the same +contract: declare once in the image, the runtime handles start, readiness +and stop. + +## Non-goals + +- Restart on failure. A service that exits is reported, not restarted. +- Dependencies between services. All services start in parallel. +- Per service users or cgroups. Services run as root in the root cgroup, + the same as the user command today. +- Services that depend on host mounts. Mounts arrive over vsock after boot, + services start before the first vsock connection. +- Changing the on disk format of checkpoints. + +## Design + +### Service definition + +A service is a JSON file at `/etc/shuru/services/.json`. The name is +the file stem and must match `[a-z0-9][a-z0-9-]*`. + +```json +{ + "exec": ["dockerd"], + "ready": ["docker", "info"], + "ready_timeout_secs": 60, + "stop_timeout_secs": 30, + "env": {"DOCKER_RAMDISK": "1"}, + "cwd": "/" +} +``` + +| field | required | default | meaning | +|---|---|---|---| +| `exec` | yes | | argv of the process to run. Resolved on the init PATH. | +| `ready` | no | none | argv retried every 250 ms until it exits 0. Without it the service is ready as soon as it is spawned. | +| `ready_timeout_secs` | no | 30 | give up on `ready` after this long. | +| `stop_timeout_secs` | no | 15 | time between SIGTERM and SIGKILL at shutdown. | +| `env` | no | `{}` | extra environment for `exec` and `ready`. | +| `cwd` | no | `/` | working directory for `exec`. | + +Files that fail to parse are reported on the console and skipped. They do +not block the boot or the user command, because a broken file in an image +should be debuggable with `shuru run`. + +### Lifecycle in the guest + +After networking is up and before the vsock listeners are created, init +reads the services directory and spawns every service. Each gets its own +process group and its stdout and stderr appended to +`/run/shuru/log/.log`. The log lives on tmpfs so it never lands in a +checkpoint. + +Each service has one of four states: starting, ready, failed or stopped. A +thread per service runs the ready check until it passes or the timeout is +hit. The zombie reaper already in init records the exit of any service pid, +so a daemon that dies at any point moves to failed with its exit status. + +Before spawning a user command, in both the piped and the tty exec paths, +init waits until no service is still starting. If every service is ready +the command runs as before. If any service is failed, init answers the exec +with an ERROR frame that names the service, the reason, and the last lines +of its log, and does not run the command. File, mount, watch and port +forward requests are never gated, so the log of a failed service can always +be read from the host. + +### Shutdown handshake + +Two new frames on the control connection: + +- `SHUTDOWN_REQ` (0x60), empty payload. +- `SHUTDOWN_RESP` (0x61), JSON `ShutdownResponse { stopped: [name], killed: [name] }`. + +On `SHUTDOWN_REQ` the guest sends SIGTERM to every running service, waits +up to each one's `stop_timeout_secs` for it to exit, sends SIGKILL to the +process group of any that remain, calls `sync`, and then replies. Services +are stopped in parallel so the wall clock cost is the slowest service, not +the sum. Once a shutdown has started, new exec requests are refused. + +On the host, `Sandbox::stop()` becomes a graceful stop. It opens a control +connection, sends `SHUTDOWN_REQ`, waits for the reply with a read timeout, +and then performs the hard stop it did before. Anything that goes wrong on +the way, including an old guest that does not know the frame, falls through +to the hard stop so a stop can never hang. `Sandbox::kill()` is the old +behaviour for callers that want it. + +Because the handshake includes `sync`, the `sync_before_stop` flag in the +CLI and the separate `sync` exec go away. Checkpoint creation and plain runs +share one path, and the SDK gets the same shutdown through its existing +`stop()` and `Drop`. + +### Docker checkpoint + +`scripts/prepare-docker-checkpoint.sh` installs Docker, writes +`/etc/shuru/services/docker.json`, and saves that as an intermediate +checkpoint. It then boots from it, where the service model has already +started dockerd, runs `docker pull` for the pinned image, and saves the +final checkpoint. The intermediate one is deleted. The build itself is the +first consumer of the feature. + +The `daemon.json` from RFC 0003 is unchanged. The `with-dockerd` helper is +no longer installed. + +### Traffic and isolation + +Nothing in this RFC changes networking or mounts. Services run inside the +VM with the same proxy, allowlist and mount rules as the user command. + +## Security + +- Services come from the image. Anything that can write to + `/etc/shuru/services/` in a checkpoint could already run arbitrary code + in that checkpoint, so this adds no new trust boundary. +- Service logs are on tmpfs under `/run`, which is size capped at 64 MB. + A very chatty service fills its log and then gets write errors, it does + not fill the disk or the checkpoint. +- Shutdown is bounded. The guest waits at most `stop_timeout_secs` per + service and the host waits at most 90 seconds for the reply before it + hard stops. A hung service cannot hold a VM open. +- Readiness failure fails closed for exec. A command never runs against a + half started service. + +Residual risks: + +- SIGKILL after the stop timeout can still leave a service with unflushed + state. The sync that follows only covers what reached the page cache. +- The host hard stop on timeout is the same crash semantics as before. The + improvement is that it is now the exception rather than the rule. + +## Testing + +`crates/shuru-cli/tests/services.rs` builds throwaway checkpoints from tiny +shell services and checks, against a real VM: + +- a service with a delayed ready check gates the user command, a second + service without a ready check is up immediately, and both are stopped + at shutdown with their logs under `/run/shuru/log` +- a service that exits before its ready check passes fails the exec with + an error naming it and the tail of its log, and the command never runs +- SIGTERM reaches a service at shutdown and the disk is synced before the + checkpoint is cloned, proven by a marker written from the TERM trap and + read back from a derived checkpoint +- a service that ignores SIGTERM is killed after its stop timeout and the + CLI reports it + +`crates/shuru-cli/tests/docker.rs` drops every `with-dockerd` and runs +plain `docker` commands. The nine RFC 0003 tests pass unchanged otherwise. + +## Rollout + +The guest and host change together in one release. An old host against a +new guest never sends `SHUTDOWN_REQ` and behaves as today. An old guest +skips unknown frames without answering, so a new host against it waits out +the shutdown timeout and then hard stops. Mixed versions degrade to the old +behaviour at the cost of a slow stop, and the asset version check keeps the +two in step for stock installs. + +## Appendix A: Evidence + +Captured on 2026-10-26 against real VMs on an M-series Mac with 8 GB RAM, +kernel 6.12.114 (sha256 `bd0550e9...`), isolated data dir, codesigned debug +CLI. Full `--nocapture` output is in +`docs/rfcs/0004-guest-services-evidence.log`; the Docker suite rerun is in +`docs/rfcs/0003-docker-on-shuru-evidence.log`. + +Service suite, four tests, one run: + +``` +test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 9.49s +``` + +Lines that show each behaviour, from that log: + +``` +shuru-guest: service slow ready +GATED_OK +fast-log=fast-started +slow-alive=2 +shuru-guest: services stopped in 0.1s (stopped: ["fast", "slow"], killed: []) +shuru: stopped services: fast, slow + +guest error: service bad exited with status 3 +--- /run/shuru/log/bad.log --- +booting bad service +giving up + +shuru-guest: services stopped in 1.0s (stopped: ["trap"], killed: []) +shuru: stopped services: trap +got-term + +shuru: services ignored SIGTERM and were killed: stubborn +``` + +Docker checkpoint build with the two step script, with dockerd started by +the service model in step two: + +``` +==> Step 2/2: pulling the image into 'docker' with dockerd running as a service +shuru-guest: service docker ready +Digest: sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 +shuru: stopped services: docker +==> Checkpoint 'docker' ready +real 2m6.213s +``` + +RFC 0003 Docker suite, nine tests, against that checkpoint with no +`with-dockerd` anywhere: + +``` +test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 78.78s +``` + +The same nine tests took 125.51s with the wrapper, because every script +paid a daemon start and stop. The checkpoint persistence test additionally +asserts `shuru: stopped services: docker` on the create side, which is the +handshake running before the clone. From 3efb1c1f1d187e3e397b1c43af1478dc71fc8aac Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 06:37:37 +0530 Subject: [PATCH 12/57] docker: run dockerd as a guest service The checkpoint build now installs Docker and declares the service in a first step, then boots from that checkpoint, where dockerd is already up, to pull the pinned image. with-dockerd is gone; the tests and README call docker directly. Nine tests still pass, in 79s instead of 125s because the daemon starts once per boot. --- CHANGELOG.md | 19 +++- README.md | 25 +++-- crates/shuru-cli/tests/docker.rs | 47 ++++---- docs/rfcs/0003-docker-on-shuru-evidence.log | 83 ++++++++++---- docs/rfcs/0003-docker-on-shuru.md | 23 ++-- scripts/prepare-docker-checkpoint.sh | 114 +++++++++----------- 6 files changed, 185 insertions(+), 126 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4af50ac..1c84df1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,13 +2,24 @@ ## Unreleased +### Guest services + +An image can declare long running processes in +`/etc/shuru/services/.json`. The guest init starts them at boot, +waits for their readiness check before running the command, and stops them +with SIGTERM before the VM powers off. The host now asks the guest to shut +down over vsock, which also syncs the disk, so checkpoints are cloned from +a consistent image on every stop path. `Sandbox::stop()` is graceful and +`Sandbox::kill()` is the old hard stop. See docs/rfcs/0004-guest-services.md. + ### Docker Engine runs inside the VM `scripts/prepare-docker-checkpoint.sh` builds a checkpoint with pinned -docker-ce 29.9.2 and containerd 2.4.2 and one pre-pulled image, and -`with-dockerd CMD` runs a command with the daemon up. Containers get the -same boundary as any guest process: no egress without `--allow-net`, the -host allowlist applied by the proxy, host ports only through `-p`. +docker-ce 29.9.2 and containerd 2.4.2 and one pre-pulled image, with dockerd +declared as a guest service so `shuru run --from docker -- docker run ...` +just works. Containers get the same boundary as any guest process: no egress +without `--allow-net`, the host allowlist applied by the proxy, host ports +only through `-p`. To support it, the guest kernel gains cgroup v2 controllers, cgroup BPF, seccomp filters, veth, and the netfilter targets dockerd installs, and moves diff --git a/README.md b/README.md index 19a79b3..3264aa6 100644 --- a/README.md +++ b/README.md @@ -217,16 +217,27 @@ containers from that checkpoint with networking disabled: ./scripts/prepare-docker-checkpoint.sh # Serve the pre-pulled nginx-unprivileged image on host port 8080 -shuru run --from docker -p 8080:8080 -- with-dockerd sh -c \ - 'docker run -d -p 8080:8080 nginxinc/nginx-unprivileged:1.31.7-alpine-slim && sleep 300' +shuru run --from docker -p 8080:8080 -- \ + docker run --rm -p 8080:8080 nginxinc/nginx-unprivileged:1.31.7-alpine-slim curl http://127.0.0.1:8080/ ``` -`with-dockerd CMD` starts dockerd, runs `CMD`, then stops dockerd so the disk -is consistent for checkpointing. Pulling other images needs `--allow-net`, -and the usual `--allow-host` allowlist applies to container traffic too: -containers reach the internet only through the Shuru proxy, and nothing at -all without `--allow-net`. +dockerd is a guest service: it starts when the VM boots, the command waits +until `docker info` answers, and the daemon is stopped and the disk synced +before the VM powers off. Pulling other images needs `--allow-net`, and the +usual `--allow-host` allowlist applies to container traffic too: containers +reach the internet only through the Shuru proxy, and nothing at all without +`--allow-net`. + +Any image can declare services the same way. A JSON file under +`/etc/shuru/services/` names the command to run, an optional readiness +check, and the stop timeout: + +```json +{"exec": ["dockerd"], "ready": ["docker", "info"], "stop_timeout_secs": 30} +``` + +See docs/rfcs/0004-guest-services.md for the full contract. Docker isolation inside the VM stays at its defaults (seccomp, no new privileges). Do not use `--privileged` or mount the Docker socket into a diff --git a/crates/shuru-cli/tests/docker.rs b/crates/shuru-cli/tests/docker.rs index 89a26c0..04a050b 100644 --- a/crates/shuru-cli/tests/docker.rs +++ b/crates/shuru-cli/tests/docker.rs @@ -15,6 +15,10 @@ //! //! SHURU_DATA_DIR, SHURU_KERNEL and SHURU_INITRD are inherited by the CLI, //! so a run can use an isolated kernel and checkpoint directory. +//! +//! dockerd runs as a guest service (RFC 0004): it is up before the command +//! starts and is stopped cleanly before the VM powers off, so the scripts +//! below call `docker` directly. use std::io::{Read, Write}; use std::net::{TcpListener, TcpStream}; @@ -112,7 +116,6 @@ fn dockerd_runs_pinned_image_as_non_root_with_default_isolation() { &[], r#" set -e -with-dockerd sh -c ' docker info --format "{{.CgroupDriver}} cgroup-v{{.CgroupVersion}} storage={{.Driver}} kernel={{.KernelVersion}} security={{.SecurityOptions}}" docker version --format "docker={{.Server.Version}} containerd={{(index .Server.Components 1).Version}} runc={{(index .Server.Components 2).Version}}" docker image inspect --format "digest={{index .RepoDigests 0}} user={{.Config.User}}" IMAGE @@ -126,7 +129,6 @@ echo "seccomp=$(docker inspect --format "{{.HostConfig.SecurityOpt}}" web)" echo "no-new-privs=$(docker exec web grep NoNewPrivs /proc/1/status)" echo "seccomp-mode=$(docker exec web grep Seccomp: /proc/1/status)" docker rm -f web > /dev/null -' "#, ); assert!(out.status.success(), "{}", text(&out)); @@ -155,7 +157,6 @@ fn http_through_port_forward_reaches_container() { set -e mkdir -p /srv/www echo "{token}" > /srv/www/index.html -with-dockerd sh -c ' docker run -d --name web -p 8080:8080 -v /srv/www:/usr/share/nginx/html:ro IMAGE > /dev/null echo READY i=0 @@ -166,7 +167,6 @@ until docker logs web 2>&1 | grep -q "GET /done"; do done docker rm -f web > /dev/null echo STOPPED -' "# ); @@ -210,11 +210,9 @@ fn container_has_no_egress_without_allow_net() { let out = shuru_run( &[], r#" -with-dockerd sh -c ' echo "guest-eth0=$(ip -o link show eth0 2>&1 | head -c 40)" docker run --rm IMAGE sh -c "wget -T 5 -qO- http://example.com && echo EGRESS_OK || echo EGRESS_BLOCKED" docker run --rm IMAGE sh -c "nslookup example.com 2>&1 | tail -n 1; wget -T 5 -qO- http://93.184.215.14 && echo IP_OK || echo IP_BLOCKED" -' "#, ); let s = stdout(&out); @@ -234,12 +232,10 @@ fn container_egress_follows_host_allowlist() { let out = shuru_run( &["--allow-net", "--allow-host", "example.com"], r#" -with-dockerd sh -c ' docker run --rm IMAGE sh -c "wget -T 15 -qO- http://example.com | grep -o \"[^<]*\" && echo ALLOWED_OK || echo ALLOWED_FAIL" docker run --rm IMAGE sh -c "wget -T 5 -qO- http://www.iana.org/ > /dev/null 2>&1 && echo DOMAIN_LEAK || echo DOMAIN_BLOCKED" docker run --rm IMAGE sh -c "wget -T 5 -qO- http://1.1.1.1/ > /dev/null 2>&1 && echo IP_LEAK || echo IP_BLOCKED" docker run --rm --dns 8.8.8.8 IMAGE sh -c "wget -T 5 -qO- http://example.com > /dev/null 2>&1 && echo DNS_LEAK || echo DNS_BLOCKED" -' "#, ); let s = stdout(&out); @@ -263,10 +259,8 @@ fn container_cannot_reach_host_loopback_services() { let script = format!( r#" -with-dockerd sh -c ' docker run --rm IMAGE sh -c "wget -T 5 -qO- http://10.0.0.1:{port}/ > /dev/null 2>&1 && echo GATEWAY_REACHED || echo GATEWAY_BLOCKED" docker run --rm IMAGE sh -c "wget -T 5 -qO- http://host.shuru.internal:{port}/ > /dev/null 2>&1 && echo HOSTNAME_REACHED || echo HOSTNAME_BLOCKED" -' "# ); @@ -295,10 +289,8 @@ fn container_cannot_write_to_host_through_default_mount() { let out = shuru_run( &["--mount", &spec], r#" -with-dockerd sh -c ' docker run --rm --user 0 -v /workspace:/w IMAGE sh -c "cat /w/host.txt; echo escaped > /w/escaped.txt && echo WROTE_IN_GUEST" docker run --rm -v /:/vmroot IMAGE sh -c "ls /vmroot/Users > /dev/null 2>&1 && echo HOST_FS_VISIBLE || echo HOST_FS_ABSENT" -' "#, ); let s = stdout(&out); @@ -317,12 +309,10 @@ fn resource_limits_apply_inside_containers() { let out = shuru_run( &[], r#" -with-dockerd sh -c ' docker run --rm --memory 64m --cpus 0.5 --pids-limit 20 IMAGE sh -c "echo memory.max=\$(cat /sys/fs/cgroup/memory.max); echo cpu.max=\$(cat /sys/fs/cgroup/cpu.max); echo pids.max=\$(cat /sys/fs/cgroup/pids.max)" docker run --rm --memory 32m IMAGE sh -c "a=\$(head -c 200m /dev/zero | tr \"\\0\" a); echo survived" echo "oom-exit=$?" docker run --rm --pids-limit 5 IMAGE sh -c "for i in 1 2 3 4 5 6 7 8 9 10; do sleep 3 & done; wait; echo forked-all" 2>&1 | tail -n 1 -' "#, ); let s = stdout(&out); @@ -336,12 +326,11 @@ docker run --rm --pids-limit 5 IMAGE sh -c "for i in 1 2 3 4 5 6 7 8 9 10; do sl #[test] #[ignore] -fn named_volume_persists_across_container_and_daemon_restart() { +fn named_volume_persists_across_container_restart() { let token = format!("persisted-{}", std::process::id()); let script = format!( r#" set -e -with-dockerd sh -c ' docker volume create vdata > /dev/null docker create --name keeper -v vdata:/tmp IMAGE sleep 120 > /dev/null docker start keeper > /dev/null @@ -350,22 +339,21 @@ docker stop -t 1 keeper > /dev/null docker start keeper > /dev/null echo "after-container-restart=$(docker exec keeper cat /tmp/marker)" docker rm -f keeper > /dev/null -' -with-dockerd sh -c ' -echo "after-daemon-restart=$(docker run --rm -v vdata:/tmp IMAGE cat /tmp/marker)" -' +echo "after-new-container=$(docker run --rm -v vdata:/tmp IMAGE cat /tmp/marker)" "# ); let out = shuru_run(&[], &script); assert!(out.status.success(), "{}", text(&out)); let s = stdout(&out); assert!(s.contains(&format!("after-container-restart={}", token)), "{}", s); - assert!(s.contains(&format!("after-daemon-restart={}", token)), "{}", s); + assert!(s.contains(&format!("after-new-container={}", token)), "{}", s); } /// Shuru resets the disk on every run, so persistence across a VM stop and -/// start goes through a checkpoint. with-dockerd stops dockerd before the -/// checkpoint is taken, so the volume store is consistent on disk. +/// start goes through a checkpoint. The guest stops dockerd and syncs the +/// disk during the shutdown handshake, before the checkpoint is cloned, so +/// the volume store is consistent and the daemon restarts cleanly on the +/// next boot. #[test] #[ignore] fn named_volume_persists_across_vm_stop_start_via_checkpoint() { @@ -375,14 +363,12 @@ fn named_volume_persists_across_vm_stop_start_via_checkpoint() { let write = format!( r#" set -e -with-dockerd sh -c ' docker volume create vdata > /dev/null docker run --rm -v vdata:/tmp IMAGE sh -c "echo {token} > /tmp/marker" -' "# ); let create = Command::new(shuru_bin()) - .args(["checkpoint", "create", &name, "--from", &checkpoint(), "--"]) + .args(["checkpoint", "create", &name, "--verbose", "--from", &checkpoint(), "--"]) .args(guest_cmd(&write)) .stdin(Stdio::null()) .output() @@ -392,7 +378,7 @@ docker run --rm -v vdata:/tmp IMAGE sh -c "echo {token} > /tmp/marker" let read = Command::new(shuru_bin()) .args(["run", "--from", &name, "--"]) .args(guest_cmd( - r#"with-dockerd sh -c 'echo "after-vm-restart=$(docker run --rm -v vdata:/tmp IMAGE cat /tmp/marker)"'"#, + r#"echo "after-vm-restart=$(docker run --rm -v vdata:/tmp IMAGE cat /tmp/marker)""#, )) .stdin(Stdio::null()) .output() @@ -401,9 +387,14 @@ docker run --rm -v vdata:/tmp IMAGE sh -c "echo {token} > /tmp/marker" let _ = Command::new(shuru_bin()) .args(["checkpoint", "delete", &name]) .output(); - eprintln!("$ shuru checkpoint create {} --from {}\n{}", name, checkpoint(), text(&create)); + eprintln!("$ shuru checkpoint create {} --verbose --from {}\n{}", name, checkpoint(), text(&create)); eprintln!("$ shuru run --from {}\n{}", name, text(&read)); + assert!( + String::from_utf8_lossy(&create.stderr).contains("stopped services: docker"), + "{}", + text(&create) + ); assert!(read.status.success(), "{}", text(&read)); assert!( stdout(&read).contains(&format!("after-vm-restart={}", token)), diff --git a/docs/rfcs/0003-docker-on-shuru-evidence.log b/docs/rfcs/0003-docker-on-shuru-evidence.log index d23af31..6795244 100644 --- a/docs/rfcs/0003-docker-on-shuru-evidence.log +++ b/docs/rfcs/0003-docker-on-shuru-evidence.log @@ -17,7 +17,7 @@ HOSTNAME_BLOCKED shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... ok -test container_cannot_write_to_host_through_default_mount ... $ shuru run --from docker --mount /.tmpAWI21I:/workspace +test container_cannot_write_to_host_through_default_mount ... $ shuru run --from docker --mount /.tmpthbsMx:/workspace --- stdout --- from-host WROTE_IN_GUEST @@ -68,49 +68,95 @@ seccomp-mode=Seccomp: 2 shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... ok -test http_through_port_forward_reaches_container ... $ shuru run --from docker -p 61346:8080 +test http_through_port_forward_reaches_container ... $ shuru run --from docker -p 61603:8080 --- stdout --- READY STOPPED --- stderr --- shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... -shuru: forwarding 127.0.0.1:61346 -> guest:8080 +shuru: forwarding 127.0.0.1:61603 -> guest:8080 -$ GET http://127.0.0.1:61346/ +$ GET http://127.0.0.1:61603/ HTTP/1.1 200 OK Server: nginx/1.31.7 -Date: Mon, 26 Oct 2026 00:21:17 GMT +Date: Mon, 26 Oct 2026 01:02:26 GMT Content-Type: text/html Content-Length: 19 -Last-Modified: Mon, 26 Oct 2026 00:21:15 GMT +Last-Modified: Mon, 26 Oct 2026 01:02:26 GMT Connection: close -ETag: "6ade9cfb-13" +ETag: "6adea6a2-13" Accept-Ranges: bytes -shuru-docker-72816 +shuru-docker-98351 ok -test named_volume_persists_across_container_and_daemon_restart ... $ shuru run --from docker +test named_volume_persists_across_container_restart ... $ shuru run --from docker --- stdout --- -after-container-restart=persisted-72816 -after-daemon-restart=persisted-72816 +after-container-restart=persisted-98351 +after-new-container=persisted-98351 --- stderr --- shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... ok -test named_volume_persists_across_vm_stop_start_via_checkpoint ... $ shuru checkpoint create shuru-test-docker-data-72816 --from docker +test named_volume_persists_across_vm_stop_start_via_checkpoint ... $ shuru checkpoint create shuru-test-docker-data-98351 --verbose --from docker --- stdout --- --- stderr --- +shuru: creating working copy... +shuru: kernel=/Image +shuru: rootfs=/instances/98441/rootfs.ext4 (work copy) shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... -shuru: saving checkpoint 'shuru-test-docker-data-72816'... -shuru: checkpoint 'shuru-test-docker-data-72816' saved - -$ shuru run --from shuru-test-docker-data-72816 +shuru: VM created and validated successfully +shuru: VM started, waiting for guest... +random: crng init done +virtio_blk virtio1: 1/0/0 default/read/poll queues +virtio_blk virtio1: [vda] 8388608 512-byte logical blocks (4.29 GB/4.00 GiB) +rtc-pl031 20050000.pl031: registered as rtc0 +rtc-pl031 20050000.pl031: setting system clock to 2026-10-26T01:02:32 UTC (1792976552) +NET: Registered PF_INET6 protocol family +Segment Routing with IPv6 +In-situ OAM (IOAM) with IPv6 +sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver +NET: Registered PF_PACKET protocol family +Bridge firewalling registered +NET: Registered PF_VSOCK protocol family +clk: Disabling unused clocks +Freeing unused kernel memory: 896K +Run /init as init process +EXT4-fs (vda): mounted filesystem 728de991-e6e3-4e1a-873d-bc29aeff5c07 r/w with ordered data mode. Quota mode: disabled. +shuru-guest[ 213.6ms]: starting as PID 1 +shuru-guest[ 213.9ms]: filesystems mounted +shuru-guest: no network device (sandbox mode) +shuru-guest[ 214.0ms]: networking ready +shuru-guest[ 216.6ms]: 1 service(s) starting +shuru-guest[ 216.6ms]: vsock listening on port 1024 +shuru-guest[ 216.6ms]: port forward listener on port 1025 +shuru-guest: accepted vsock connection +shuru-guest: service docker ready +docker0: port 1(veth2b33299) entered blocking state +docker0: port 1(veth2b33299) entered disabled state +veth2b33299: entered allmulticast mode +veth2b33299: entered promiscuous mode +eth0: renamed from vethd3aa798 +docker0: port 1(veth2b33299) entered blocking state +docker0: port 1(veth2b33299) entered forwarding state +docker0: port 1(veth2b33299) entered disabled state +vethd3aa798: renamed from eth0 +docker0: port 1(veth2b33299) entered disabled state +veth2b33299 (unregistering): left allmulticast mode +veth2b33299 (unregistering): left promiscuous mode +docker0: port 1(veth2b33299) entered disabled state +shuru-guest: accepted vsock connection +shuru-guest: services stopped in 1.0s (stopped: ["docker"], killed: []) +shuru: stopped services: docker +shuru: saving checkpoint 'shuru-test-docker-data-98351'... +shuru: checkpoint 'shuru-test-docker-data-98351' saved + +$ shuru run --from shuru-test-docker-data-98351 --- stdout --- -after-vm-restart=vm-persisted-72816 +after-vm-restart=vm-persisted-98351 --- stderr --- shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... @@ -131,6 +177,5 @@ WARNING: Your kernel does not support swap limit capabilities or the cgroup is n ok -test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 123.84s +test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 78.78s -exit=0 diff --git a/docs/rfcs/0003-docker-on-shuru.md b/docs/rfcs/0003-docker-on-shuru.md index 204b679..e984ff3 100644 --- a/docs/rfcs/0003-docker-on-shuru.md +++ b/docs/rfcs/0003-docker-on-shuru.md @@ -96,13 +96,16 @@ checkpoints. 3. Write `/etc/docker/daemon.json` with `no-new-privileges: true`. Everything else stays at Docker defaults (iptables on, userland proxy on, seccomp default profile, overlay2, json-file logs). -4. Install `/usr/local/bin/with-dockerd`, which starts containerd and dockerd, - waits for the socket, runs the given command, then stops dockerd cleanly so - the disk is consistent for checkpointing. -5. `docker pull` the pinned image so the checkpoint runs it without network. +4. Declare dockerd as a guest service in `/etc/shuru/services/docker.json` + (RFC 0004), with `docker info` as the readiness check and a 30 second + stop timeout. The guest init starts it at boot and stops it before power + off. An earlier revision of this RFC used a `with-dockerd` wrapper + script for the same job; RFC 0004 replaced it. +5. Boot from that intermediate checkpoint and `docker pull` the pinned image + so the final checkpoint runs it without network. The checkpoint is the unit users reuse: `shuru run --from docker -p 8080:8080 --- with-dockerd docker run ...`. +-- docker run ...`. ### Data dir isolation @@ -223,11 +226,17 @@ Image config read from the registry before pulling: `User: 101`, ### Runtime checks from the integration suite -Final run, each test booting one VM from the rebuilt checkpoint: +Final run with the `with-dockerd` wrapper, each test booting one VM from +the rebuilt checkpoint: test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 125.51s -Raw output is in `docs/rfcs/0003-docker-on-shuru-evidence.log`. Excerpts: +Rerun after RFC 0004 moved dockerd to a guest service, same nine tests: + + test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 78.78s + +Raw output of the rerun is in `docs/rfcs/0003-docker-on-shuru-evidence.log`. +Excerpts, identical between the two runs: cgroupfs cgroup-v2 storage=overlayfs kernel=6.12.114 security=[name=seccomp,profile=builtin name=cgroupns name=no-new-privileges] docker=29.9.2 containerd=v2.4.2 runc=1.5.2 diff --git a/scripts/prepare-docker-checkpoint.sh b/scripts/prepare-docker-checkpoint.sh index 0757154..1838818 100755 --- a/scripts/prepare-docker-checkpoint.sh +++ b/scripts/prepare-docker-checkpoint.sh @@ -1,12 +1,17 @@ #!/bin/bash -# Create a Shuru checkpoint with Docker Engine installed and one pinned image -# pulled, so `shuru run --from docker -- with-dockerd docker run ...` works -# with networking disabled. +# Create a Shuru checkpoint with Docker Engine installed as a guest service +# (RFC 0004) and one pinned image pulled, so +# `shuru run --from docker -- docker run ...` works with networking disabled. # # Everything is pinned: Docker apt packages by exact version, the apt signing # key by SHA-256, the image by manifest digest. The VM that performs the # install only reaches the hosts listed below. # +# The build has two steps. The first installs Docker and declares the +# dockerd service, saved as an intermediate checkpoint. The second boots from +# it, which starts dockerd through the service model, pulls the image, and +# saves the final checkpoint. The intermediate checkpoint is then deleted. +# # Needs a kernel and guest init with container support (RFC 0003). Until a # release ships them, point SHURU_KERNEL and SHURU_INITRD at a local build. set -euo pipefail @@ -25,53 +30,9 @@ DOCKER_GPG_SHA256="${DOCKER_GPG_SHA256:-1500c1f56fa9e26b9b8f42452a553675796ade08 # runs as uid 101 and listens on 8080. DOCKER_IMAGE="${DOCKER_IMAGE:-nginxinc/nginx-unprivileged:1.31.7-alpine-slim@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7}" -WITH_DOCKERD_B64="$(base64 << 'HELPER' | tr -d '\n' -#!/bin/sh -# Start dockerd, run a command, then stop dockerd so the disk is consistent. -# usage: with-dockerd CMD [ARGS...] -set -eu -if [ "$#" -eq 0 ]; then - echo "usage: with-dockerd CMD [ARGS...]" >&2 - exit 64 -fi -LOG=/var/log/dockerd.log -if docker info > /dev/null 2>&1; then - exec "$@" -fi -dockerd > "$LOG" 2>&1 & -DOCKERD_PID=$! -i=0 -until docker info > /dev/null 2>&1; do - i=$((i + 1)) - if ! kill -0 "$DOCKERD_PID" 2> /dev/null; then - echo "with-dockerd: dockerd exited during startup" >&2 - tail -n 30 "$LOG" >&2 - exit 1 - fi - if [ "$i" -ge 300 ]; then - echo "with-dockerd: dockerd not ready after 60s" >&2 - tail -n 30 "$LOG" >&2 - kill "$DOCKERD_PID" 2> /dev/null || true - exit 1 - fi - sleep 0.2 -done -set +e -"$@" -STATUS=$? -set -e -kill -TERM "$DOCKERD_PID" 2> /dev/null || true -j=0 -while kill -0 "$DOCKERD_PID" 2> /dev/null && [ "$j" -lt 150 ]; do - sleep 0.2 - j=$((j + 1)) -done -sync -exit "$STATUS" -HELPER -)" +BASE_NAME="${CHECKPOINT_NAME}-base" -GUEST_SCRIPT="$(cat << EOF +INSTALL_SCRIPT="$(cat << EOF set -eu export DEBIAN_FRONTEND=noninteractive echo "==> Upgrading Debian base (main, security and updates archives)" @@ -106,19 +67,33 @@ apt-get clean rm -rf /var/lib/apt/lists/* mkdir -p /etc/docker printf '{\n "no-new-privileges": true\n}\n' > /etc/docker/daemon.json -echo "${WITH_DOCKERD_B64}" | base64 -d > /usr/local/bin/with-dockerd -chmod 755 /usr/local/bin/with-dockerd -echo "==> Pulling ${DOCKER_IMAGE}" -with-dockerd sh -c 'docker pull "${DOCKER_IMAGE}" && docker image ls --digests' +echo "==> Declaring the dockerd service" +mkdir -p /etc/shuru/services +cat > /etc/shuru/services/docker.json << SVCEOF +{ + "exec": ["dockerd"], + "ready": ["docker", "info"], + "ready_timeout_secs": 60, + "stop_timeout_secs": 30 +} +SVCEOF +cat /etc/shuru/services/docker.json echo "==> Installed versions" docker --version containerd --version runc --version | head -n 1 EOF )" -GUEST_SCRIPT_B64="$(printf '%s\n' "$GUEST_SCRIPT" | base64 | tr -d '\n')" -ARGS=(checkpoint create "$CHECKPOINT_NAME" +PULL_SCRIPT="$(cat << EOF +set -eu +echo "==> Pulling ${DOCKER_IMAGE}" +docker pull "${DOCKER_IMAGE}" +docker image ls --digests +EOF +)" + +ALLOW_ARGS=( --allow-net --disk-size "$DISK_SIZE_MB" --memory "$MEMORY_MB" @@ -128,12 +103,29 @@ ARGS=(checkpoint create "$CHECKPOINT_NAME" --allow-host "*.docker.io" --allow-host "*.docker.com" --allow-host "*.cloudflarestorage.com") -if [ -n "$FROM_CHECKPOINT" ]; then - ARGS+=(--from "$FROM_CHECKPOINT") -fi if [ -n "${VERBOSE:-}" ]; then - ARGS+=(--verbose) + ALLOW_ARGS+=(--verbose) fi -echo "==> Creating checkpoint '${CHECKPOINT_NAME}' with Docker ${DOCKER_VERSION}" -exec "$SHURU_BIN" "${ARGS[@]}" -- sh -c "echo ${GUEST_SCRIPT_B64} | base64 -d | sh" +run_checkpoint() { + local name="$1" from="$2" script="$3" + local args=(checkpoint create "$name" "${ALLOW_ARGS[@]}") + if [ -n "$from" ]; then + args+=(--from "$from") + fi + local b64 + b64="$(printf '%s\n' "$script" | base64 | tr -d '\n')" + "$SHURU_BIN" "${args[@]}" -- sh -c "echo ${b64} | base64 -d | sh" +} + +echo "==> Step 1/2: installing Docker ${DOCKER_VERSION} into '${BASE_NAME}'" +run_checkpoint "$BASE_NAME" "$FROM_CHECKPOINT" "$INSTALL_SCRIPT" + +echo "==> Step 2/2: pulling the image into '${CHECKPOINT_NAME}' with dockerd running as a service" +if run_checkpoint "$CHECKPOINT_NAME" "$BASE_NAME" "$PULL_SCRIPT"; then + "$SHURU_BIN" checkpoint delete "$BASE_NAME" + echo "==> Checkpoint '${CHECKPOINT_NAME}' ready" +else + echo "==> Pull failed; intermediate checkpoint '${BASE_NAME}' left in place for debugging" >&2 + exit 1 +fi From e5f295fc401fa60dbd281fc8e0c5cb65564b1ce2 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 06:38:12 +0530 Subject: [PATCH 13/57] chore: clear clippy warnings in guest, proto and cli C string literals instead of hand terminated byte strings, pointer casts through cast() so they stay correct where c_char is signed, a while let for the vsock read loop, io::Error::other, and a literal header line in checkpoint list. No behaviour change. --- crates/shuru-cli/src/checkpoint.rs | 2 +- crates/shuru-guest/src/main.rs | 24 ++++++------------------ crates/shuru-proto/src/frame.rs | 2 +- 3 files changed, 8 insertions(+), 20 deletions(-) diff --git a/crates/shuru-cli/src/checkpoint.rs b/crates/shuru-cli/src/checkpoint.rs index 7e94d10..b81d6fe 100644 --- a/crates/shuru-cli/src/checkpoint.rs +++ b/crates/shuru-cli/src/checkpoint.rs @@ -100,7 +100,7 @@ pub(crate) fn list() -> Result<()> { checkpoints.sort_by_key(|(_, _, t, _)| *t); - println!("{:<20} {:>10} {}", "NAME", "SIZE", "CREATED"); + println!("NAME SIZE CREATED"); for (name, size, mtime, is_cas) in &checkpoints { let size_str = if *is_cas { if *size >= 1024 * 1024 { diff --git a/crates/shuru-guest/src/main.rs b/crates/shuru-guest/src/main.rs index 78454bb..2832d7d 100644 --- a/crates/shuru-guest/src/main.rs +++ b/crates/shuru-guest/src/main.rs @@ -41,7 +41,7 @@ mod guest { if libc::fcntl(2, libc::F_GETFD) >= 0 { return; } - let fd = libc::open(b"/dev/null\0".as_ptr() as *const libc::c_char, libc::O_RDWR); + let fd = libc::open(c"/dev/null".as_ptr(), libc::O_RDWR); if fd >= 0 { for t in 0..3 { libc::dup2(fd, t); @@ -226,7 +226,7 @@ mod guest { let copy_len = name.len().min(libc::IFNAMSIZ); std::ptr::copy_nonoverlapping( name.as_ptr(), - ifr.ifr_name.as_mut_ptr() as *mut u8, + ifr.ifr_name.as_mut_ptr().cast::(), copy_len, ); @@ -260,11 +260,7 @@ mod guest { // Check if eth0 exists (network device present) let has_eth0 = { let mut ifr: libc::ifreq = std::mem::zeroed(); - std::ptr::copy_nonoverlapping( - b"eth0\0".as_ptr(), - ifr.ifr_name.as_mut_ptr() as *mut u8, - 5, - ); + std::ptr::copy_nonoverlapping(c"eth0".as_ptr(), ifr.ifr_name.as_mut_ptr(), 5); libc::ioctl(sock, libc::SIOCGIFFLAGS as _, &mut ifr) == 0 }; @@ -277,11 +273,7 @@ mod guest { // Check if eth0 already has an IP (configured by initramfs) let has_ip = { let mut ifr: libc::ifreq = std::mem::zeroed(); - std::ptr::copy_nonoverlapping( - b"eth0\0".as_ptr(), - ifr.ifr_name.as_mut_ptr() as *mut u8, - 5, - ); + std::ptr::copy_nonoverlapping(c"eth0".as_ptr(), ifr.ifr_name.as_mut_ptr(), 5); libc::ioctl(sock, libc::SIOCGIFADDR as _, &mut ifr) == 0 }; @@ -392,12 +384,8 @@ mod guest { let mut reader = stream.try_clone().expect("failed to clone stream"); let mut writer = stream; - loop { - let (msg_type, payload) = match frame::read_frame(&mut reader) { - Ok(Some(f)) => f, - _ => break, // EOF or error - }; - + // Ends on EOF or a read error. + while let Ok(Some((msg_type, payload))) = frame::read_frame(&mut reader) { match msg_type { frame::MOUNT_REQ => { let mount_req: MountRequest = match serde_json::from_slice(&payload) { diff --git a/crates/shuru-proto/src/frame.rs b/crates/shuru-proto/src/frame.rs index 31ce77d..2e1444b 100644 --- a/crates/shuru-proto/src/frame.rs +++ b/crates/shuru-proto/src/frame.rs @@ -102,7 +102,7 @@ pub fn read_frame(r: &mut impl Read) -> io::Result)>> { /// Serialize `msg` as JSON and send it as a typed frame. pub fn send_json(w: &mut impl Write, msg_type: u8, msg: &impl serde::Serialize) -> io::Result<()> { - let payload = serde_json::to_vec(msg).map_err(|e| io::Error::new(io::ErrorKind::Other, e))?; + let payload = serde_json::to_vec(msg).map_err(io::Error::other)?; write_frame(w, msg_type, &payload) } From 73c8bad8f268dbe5a203663a50826b8879650efd Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 06:43:08 +0530 Subject: [PATCH 14/57] www: Docker inside tab in the CLI section Shows a container served through port forwarding from the docker checkpoint and the service file that starts dockerd at boot. --- www/src/components/landing/CliSection.astro | 24 +++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/www/src/components/landing/CliSection.astro b/www/src/components/landing/CliSection.astro index 3cc9ea7..4d11975 100644 --- a/www/src/components/landing/CliSection.astro +++ b/www/src/components/landing/CliSection.astro @@ -33,6 +33,11 @@ const tabs = [ title: "Port forwarding", description: "Expose guest ports to the host. Works without network access.", }, + { + id: "docker", + title: "Docker inside", + description: "Run containers in the sandbox. dockerd starts as a guest service and follows the same network rules.", + }, ]; --- @@ -109,6 +114,25 @@ const tabs = [

# No --allow-net needed. Tunneled over vsock.

+ +
+

# One-time: scripts/prepare-docker-checkpoint.sh builds a 'docker' checkpoint

+

$ shuru run --from docker -p 8080:8080 -- docker run --rm -p 8080:8080 nginxinc/nginx-unprivileged:1.31.7-alpine-slim

+

shuru: forwarding 127.0.0.1:8080 -> guest:8080

+
+

$ curl -sI http://127.0.0.1:8080/ | head -1

+

HTTP/1.1 200 OK

+
+

$ shuru run --from docker -- cat /etc/shuru/services/docker.json

+

{"{"}

+

"exec": ["dockerd"],

+

"ready": ["docker", "info"],

+

"ready_timeout_secs": 60,

+

"stop_timeout_secs": 30

+

{"}"}

+
+

# Services start at boot, the command waits until they are ready, and they get SIGTERM before power off.

+
From 91972492bc65029c55693cc856e132ec76836bd9 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 06:48:09 +0530 Subject: [PATCH 15/57] vm: skip the shutdown handshake when the VM is not running A guest that already died cannot answer, and the vsock connect would retry for ten seconds before falling through to the hard stop. --- crates/shuru-vm/src/sandbox.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/crates/shuru-vm/src/sandbox.rs b/crates/shuru-vm/src/sandbox.rs index d794cfd..c769699 100644 --- a/crates/shuru-vm/src/sandbox.rs +++ b/crates/shuru-vm/src/sandbox.rs @@ -268,8 +268,12 @@ impl Sandbox { /// Graceful stop: shutdown handshake, then power off. Falls back to a /// plain power off when the guest does not answer. pub fn stop(&self) -> Result<()> { - if let Err(e) = self.shutdown() { - tracing::warn!("guest shutdown failed, powering off: {}", e); + // Only a running guest can answer; a VM that already died would + // just make the vsock connect retry until it gives up. + if matches!(self.vm.state(), VmState::Running) { + if let Err(e) = self.shutdown() { + tracing::warn!("guest shutdown failed, powering off: {}", e); + } } self.kill() } From d813fdfaa1a52cfe18e69ebfc45bd3a87dbb879c Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 07:26:59 +0530 Subject: [PATCH 16/57] chore: clear the remaining clippy warnings in the cli --- crates/shuru-cli/src/stdio.rs | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/crates/shuru-cli/src/stdio.rs b/crates/shuru-cli/src/stdio.rs index bbf1efd..f212d68 100644 --- a/crates/shuru-cli/src/stdio.rs +++ b/crates/shuru-cli/src/stdio.rs @@ -488,7 +488,7 @@ pub(crate) fn run_stdio(prepared: &PreparedVm) -> Result { let tx = event_tx.clone(); let pid_clone = pid.clone(); let mut spawn_env = secret_env.clone(); - spawn_env.extend(params.env.into_iter()); + spawn_env.extend(params.env); bg_threads.push(std::thread::spawn(move || { let argv: Vec<&str> = params.argv.iter().map(|s| s.as_str()).collect(); @@ -647,17 +647,12 @@ pub(crate) fn run_stdio(prepared: &PreparedVm) -> Result { } }; let mut reader = stream; - loop { - match frame::read_frame(&mut reader) { - Ok(Some((frame::WATCH_EVENT, data))) => { - if let Some(evt) = WatchEvent::decode(&data) { - let _ = tx.send(Event::FileChange { - path: evt.path, - event: evt.kind.to_string(), - }); - } - } - _ => break, + while let Ok(Some((frame::WATCH_EVENT, data))) = frame::read_frame(&mut reader) { + if let Some(evt) = WatchEvent::decode(&data) { + let _ = tx.send(Event::FileChange { + path: evt.path, + event: evt.kind.to_string(), + }); } } })); From c44bc35b9d76f25085aec46ca8a8d3477a7639e3 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 07:30:24 +0530 Subject: [PATCH 17/57] cli: recipes (RFC 0005) A recipe is a directory with recipe.json and shell steps, fetched from GitHub at an exact commit or read from a local path. shuru recipe list shows the official catalog in superhq-ai/recipes, shuru recipe show prints one, shuru checkpoint create NAME --recipe REF builds it, and shuru run --recipe REF builds on first use and reuses the checkpoint until the recipe changes. Each step runs in a fresh boot from the previous step, services declared by the recipe are in place from step one, and the checkpoint records its source and revision in a sidecar shown by checkpoint list. Third-party recipes ask for confirmation or --yes. The CLI moves to 0.8.0 because the docker recipe declares that as its minimum. --- crates/shuru-cli/Cargo.toml | 2 +- crates/shuru-cli/src/checkpoint.rs | 36 +- crates/shuru-cli/src/cli.rs | 42 ++ crates/shuru-cli/src/main.rs | 24 +- crates/shuru-cli/src/recipe.rs | 656 +++++++++++++++++++++++ crates/shuru-cli/tests/recipes.rs | 274 ++++++++++ docs/rfcs/0005-recipes-evidence.log | 799 ++++++++++++++++++++++++++++ docs/rfcs/0005-recipes.md | 288 ++++++++++ 8 files changed, 2115 insertions(+), 6 deletions(-) create mode 100644 crates/shuru-cli/src/recipe.rs create mode 100644 crates/shuru-cli/tests/recipes.rs create mode 100644 docs/rfcs/0005-recipes-evidence.log create mode 100644 docs/rfcs/0005-recipes.md diff --git a/crates/shuru-cli/Cargo.toml b/crates/shuru-cli/Cargo.toml index ab903f2..a57ee2e 100644 --- a/crates/shuru-cli/Cargo.toml +++ b/crates/shuru-cli/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "shuru-cli" -version = "0.7.0" +version = "0.8.0" edition = "2021" [[bin]] diff --git a/crates/shuru-cli/src/checkpoint.rs b/crates/shuru-cli/src/checkpoint.rs index b81d6fe..f19e5e7 100644 --- a/crates/shuru-cli/src/checkpoint.rs +++ b/crates/shuru-cli/src/checkpoint.rs @@ -5,7 +5,8 @@ use anyhow::{bail, Result}; use shuru_vm::default_data_dir; use crate::cli::VmArgs; -use crate::config::load_config; +use crate::config::{load_config, ShuruConfig}; +use crate::recipe; use crate::vm; pub(crate) fn create( @@ -15,7 +16,18 @@ pub(crate) fn create( command: Vec, ) -> Result { let cfg = load_config(vm_args.config.as_deref())?; + create_with_config(name, vm_args, &cfg, from, command) +} +/// Create a checkpoint with an explicit config. Recipe builds pass an empty +/// one so the project shuru.json never reaches a build. +pub(crate) fn create_with_config( + name: String, + vm_args: &VmArgs, + cfg: &ShuruConfig, + from: Option<&str>, + command: Vec, +) -> Result { let command = if !command.is_empty() { command } else { @@ -31,7 +43,7 @@ pub(crate) fn create( bail!("checkpoint '{}' already exists, delete it first", name); } - let prepared = vm::prepare_vm(vm_args, &cfg, from)?; + let prepared = vm::prepare_vm(vm_args, cfg, from)?; let result = vm::run_command(&prepared, &command)?; std::fs::create_dir_all(&checkpoints_dir)?; @@ -100,8 +112,17 @@ pub(crate) fn list() -> Result<()> { checkpoints.sort_by_key(|(_, _, t, _)| *t); - println!("NAME SIZE CREATED"); + println!("NAME SIZE CREATED RECIPE"); for (name, size, mtime, is_cas) in &checkpoints { + let origin = recipe::read_meta(name) + .map(|m| { + format!( + "{}@{}", + m.recipe.source, + &m.recipe.revision[..m.recipe.revision.len().min(7)] + ) + }) + .unwrap_or_default(); let size_str = if *is_cas { if *size >= 1024 * 1024 { format!("{} MB (cas)", size / (1024 * 1024)) @@ -126,12 +147,18 @@ pub(crate) fn list() -> Result<()> { } else { format!("{}d ago", elapsed / 86400) }; - println!("{:<20} {:>10} {}", name, size_str, age); + println!("{:<20} {:>10} {:<12} {}", name, size_str, age, origin); } Ok(()) } +/// Whether a checkpoint exists in either format. +pub(crate) fn exists(name: &str) -> bool { + let checkpoints_dir = format!("{}/checkpoints", default_data_dir()); + checkpoint_exists(&checkpoints_dir, name) +} + pub(crate) fn delete(name: &str) -> Result<()> { shuru_vm::validate_checkpoint_name(name).map_err(|e| anyhow::anyhow!(e))?; @@ -149,6 +176,7 @@ pub(crate) fn delete(name: &str) -> Result<()> { } else { bail!("Checkpoint '{}' not found", name); } + recipe::remove_meta(name); eprintln!("shuru: checkpoint '{}' deleted", name); Ok(()) diff --git a/crates/shuru-cli/src/cli.rs b/crates/shuru-cli/src/cli.rs index 7f6ee19..054d026 100644 --- a/crates/shuru-cli/src/cli.rs +++ b/crates/shuru-cli/src/cli.rs @@ -87,6 +87,15 @@ pub(crate) enum Commands { #[arg(long)] from: Option, + /// Build a checkpoint from a recipe on first use and start from it + /// (NAME, OWNER/REPO[/PATH][@REF], or a local directory) + #[arg(long, conflicts_with = "from", value_name = "REF")] + recipe: Option, + + /// Build a third-party recipe without the confirmation prompt + #[arg(long)] + yes: bool, + /// Attach to raw serial console instead of running a command #[arg(long)] console: bool, @@ -118,8 +127,32 @@ pub(crate) enum Commands { /// Remove leftover instance data from crashed VMs Prune, + + /// Browse and inspect recipes (RFC 0005) + Recipe { + #[command(subcommand)] + action: RecipeCommands, + }, +} + +#[derive(clap::Subcommand)] +pub(crate) enum RecipeCommands { + /// List the official recipes from github.com/superhq-ai/recipes + List { + /// Ignore the cached index + #[arg(long)] + refresh: bool, + }, + + /// Print a recipe, its services and every build step + Show { + /// NAME, OWNER/REPO[/PATH][@REF], or a local directory + recipe: String, + }, } +// Parsed once; the flattened VmArgs in Create dwarfs the other variants. +#[allow(clippy::large_enum_variant)] #[derive(clap::Subcommand)] pub(crate) enum CheckpointCommands { /// Run a command and save the resulting disk state as a checkpoint @@ -134,6 +167,15 @@ pub(crate) enum CheckpointCommands { #[arg(long)] from: Option, + /// Build from a recipe instead of running a command + /// (NAME, OWNER/REPO[/PATH][@REF], or a local directory) + #[arg(long, conflicts_with = "from", value_name = "REF")] + recipe: Option, + + /// Build a third-party recipe without the confirmation prompt + #[arg(long)] + yes: bool, + /// Command and arguments to run inside the VM #[arg(trailing_var_arg = true, allow_hyphen_values = true)] command: Vec, diff --git a/crates/shuru-cli/src/main.rs b/crates/shuru-cli/src/main.rs index 6f75c36..dba0084 100644 --- a/crates/shuru-cli/src/main.rs +++ b/crates/shuru-cli/src/main.rs @@ -2,6 +2,7 @@ mod assets; mod checkpoint; mod cli; mod config; +mod recipe; mod stdio; mod vm; @@ -12,7 +13,7 @@ use clap::Parser; use shuru_vm::{default_data_dir, VmState}; -use cli::{CheckpointCommands, Cli, Commands}; +use cli::{CheckpointCommands, Cli, Commands, RecipeCommands}; use config::load_config; fn main() -> Result<()> { @@ -29,12 +30,20 @@ fn main() -> Result<()> { Commands::Run { vm, from, + recipe, + yes, console, stdio, command, } => { let cfg = load_config(vm.config.as_deref())?; + // A recipe is built (once) before the run, with its own policy. + let from = match recipe { + Some(ref reference) => Some(recipe::ensure_checkpoint(reference, &vm, yes)?), + None => from, + }; + // Command resolution: CLI args > config > default /bin/sh let command = if !command.is_empty() { command @@ -113,8 +122,17 @@ fn main() -> Result<()> { name, vm, from, + recipe, + yes, command, } => { + if let Some(ref reference) = recipe { + if !command.is_empty() { + anyhow::bail!("--recipe builds from the recipe steps; drop the command"); + } + recipe::create_checkpoint(&name, reference, &vm, yes)?; + return Ok(()); + } let exit_code = checkpoint::create(name, &vm, from.as_deref(), command)?; process::exit(exit_code); } @@ -127,6 +145,10 @@ fn main() -> Result<()> { anyhow::bail!("checkpoint pull is not yet implemented") } }, + Commands::Recipe { action } => match action { + RecipeCommands::List { refresh } => recipe::list(refresh)?, + RecipeCommands::Show { recipe: reference } => recipe::show(&reference)?, + }, } Ok(()) diff --git a/crates/shuru-cli/src/recipe.rs b/crates/shuru-cli/src/recipe.rs new file mode 100644 index 0000000..436b72a --- /dev/null +++ b/crates/shuru-cli/src/recipe.rs @@ -0,0 +1,656 @@ +//! Recipes (RFC 0005): a directory with recipe.json and one or more step +//! scripts, fetched from GitHub at an exact commit or read from a local +//! path, and built into a checkpoint through the normal checkpoint flow. + +use std::collections::BTreeMap; +use std::io::{IsTerminal, Write}; +use std::path::{Path, PathBuf}; +use std::time::{Duration, SystemTime}; + +use anyhow::{bail, Context, Result}; +use base64::Engine; +use serde::{Deserialize, Serialize}; + +use shuru_vm::default_data_dir; + +use crate::assets; +use crate::checkpoint; +use crate::cli::VmArgs; +use crate::config::ShuruConfig; + +pub(crate) const OFFICIAL_OWNER: &str = "superhq-ai"; +pub(crate) const OFFICIAL_REPO: &str = "recipes"; +const INDEX_TTL: Duration = Duration::from_secs(24 * 3600); +const USER_AGENT: &str = concat!("shuru/", env!("CARGO_PKG_VERSION")); + +#[derive(Debug, Clone, Deserialize)] +pub(crate) struct RecipeSpec { + pub name: String, + #[serde(default)] + pub description: String, + #[serde(default)] + pub min_shuru_version: Option, + #[serde(default)] + pub from: Option, + #[serde(default)] + pub cpus: Option, + #[serde(default)] + pub memory: Option, + #[serde(default)] + pub disk_size: Option, + #[serde(default)] + pub network: Option, + #[serde(default)] + pub services: BTreeMap, + #[serde(default = "default_steps")] + pub steps: Vec, +} + +#[derive(Debug, Clone, Deserialize)] +pub(crate) struct RecipeNetwork { + #[serde(default)] + pub allow: Vec, +} + +fn default_steps() -> Vec { + vec!["build.sh".to_string()] +} + +/// Where a recipe reference points. +#[derive(Debug, Clone)] +enum Source { + Local(PathBuf), + GitHub { + owner: String, + repo: String, + path: String, + reference: String, + }, +} + +/// A recipe with its step scripts loaded and its revision fixed. +pub(crate) struct Recipe { + pub spec: RecipeSpec, + /// (file name, contents) in run order. + pub steps: Vec<(String, String)>, + /// Human readable origin, e.g. `superhq-ai/recipes/docker` or a path. + pub source: String, + /// Commit SHA for GitHub, content hash for local directories. + pub revision: String, + /// Official catalog or local path: no confirmation needed. + pub trusted: bool, +} + +impl Recipe { + pub fn short_revision(&self) -> &str { + &self.revision[..self.revision.len().min(7)] + } +} + +/// Sidecar written next to a checkpoint built from a recipe. +#[derive(Debug, Serialize, Deserialize)] +pub(crate) struct CheckpointMeta { + pub recipe: RecipeMeta, +} + +#[derive(Debug, Serialize, Deserialize)] +pub(crate) struct RecipeMeta { + pub name: String, + pub source: String, + pub revision: String, +} + +#[derive(Debug, Deserialize)] +struct IndexEntry { + name: String, + #[serde(default)] + description: String, +} + +// --- Reference parsing --- + +fn parse_reference(reference: &str) -> Result { + let looks_local = reference.starts_with("./") + || reference.starts_with("../") + || reference.starts_with('/') + || reference.starts_with('~') + || reference == "."; + if looks_local || Path::new(reference).join("recipe.json").is_file() { + let path = if let Some(rest) = reference.strip_prefix("~/") { + let home = std::env::var("HOME").context("HOME is not set")?; + PathBuf::from(home).join(rest) + } else { + PathBuf::from(reference) + }; + return Ok(Source::Local(path)); + } + + let (locator, git_ref) = match reference.rsplit_once('@') { + Some((l, r)) if !r.is_empty() && !r.contains('/') => (l, r.to_string()), + _ => (reference, "HEAD".to_string()), + }; + let parts: Vec<&str> = locator.split('/').collect(); + if parts.iter().any(|p| p.is_empty() || *p == "..") { + bail!("invalid recipe reference: {}", reference); + } + let (owner, repo, path) = match parts.len() { + 1 => ( + OFFICIAL_OWNER.to_string(), + OFFICIAL_REPO.to_string(), + parts[0].to_string(), + ), + 2 => (parts[0].to_string(), parts[1].to_string(), String::new()), + _ => ( + parts[0].to_string(), + parts[1].to_string(), + parts[2..].join("/"), + ), + }; + Ok(Source::GitHub { + owner, + repo, + path, + reference: git_ref, + }) +} + +// --- Fetching --- + +fn http_get(url: &str, accept: &str) -> Result { + let mut req = ureq::get(url) + .header("User-Agent", USER_AGENT) + .header("Accept", accept); + if url.starts_with("https://api.github.com/") { + if let Ok(token) = std::env::var("GITHUB_TOKEN").or_else(|_| std::env::var("GH_TOKEN")) { + if !token.is_empty() { + req = req.header("Authorization", &format!("Bearer {}", token)); + } + } + } + let mut resp = req + .call() + .with_context(|| format!("GET {} failed", url))?; + resp.body_mut() + .read_to_string() + .with_context(|| format!("reading {}", url)) +} + +fn resolve_sha(owner: &str, repo: &str, reference: &str) -> Result { + let url = format!( + "https://api.github.com/repos/{}/{}/commits/{}", + owner, repo, reference + ); + let sha = http_get(&url, "application/vnd.github.sha") + .with_context(|| format!("resolving {}/{}@{}", owner, repo, reference))?; + let sha = sha.trim().to_string(); + if sha.len() != 40 || !sha.chars().all(|c| c.is_ascii_hexdigit()) { + bail!("unexpected commit id from GitHub for {}/{}@{}: {}", owner, repo, reference, sha); + } + Ok(sha) +} + +fn raw_url(owner: &str, repo: &str, sha: &str, path: &str, file: &str) -> String { + if path.is_empty() { + format!("https://raw.githubusercontent.com/{}/{}/{}/{}", owner, repo, sha, file) + } else { + format!( + "https://raw.githubusercontent.com/{}/{}/{}/{}/{}", + owner, repo, sha, path, file + ) + } +} + +fn parse_spec(text: &str, origin: &str) -> Result { + let spec: RecipeSpec = serde_json::from_str(text) + .with_context(|| format!("invalid recipe.json in {}", origin))?; + validate_spec(&spec, origin)?; + Ok(spec) +} + +fn valid_name(name: &str, allow_dots: bool) -> bool { + let mut chars = name.chars(); + match chars.next() { + Some(c) if c.is_ascii_lowercase() || c.is_ascii_digit() => {} + _ => return false, + } + chars.all(|c| { + c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-' || c == '_' || (allow_dots && c == '.') + }) +} + +fn validate_spec(spec: &RecipeSpec, origin: &str) -> Result<()> { + if !valid_name(&spec.name, true) { + bail!( + "{}: recipe name {:?} must match [a-z0-9][a-z0-9._-]*", + origin, + spec.name + ); + } + if spec.steps.is_empty() { + bail!("{}: steps must list at least one script", origin); + } + for step in &spec.steps { + if step.contains('/') || step.contains("..") || step.is_empty() { + bail!("{}: step {:?} must be a file name in the recipe directory", origin, step); + } + } + for (name, value) in &spec.services { + if !valid_name(name, false) { + bail!("{}: service name {:?} must match [a-z0-9][a-z0-9-]*", origin, name); + } + if !value.is_object() { + bail!("{}: service {} must be a JSON object", origin, name); + } + } + if let Some(ref from) = spec.from { + shuru_vm::validate_checkpoint_name(from).map_err(|e| anyhow::anyhow!("{}: {}", origin, e))?; + } + if let Some(ref min) = spec.min_shuru_version { + let need = parse_version(min) + .with_context(|| format!("{}: invalid min_shuru_version {:?}", origin, min))?; + let have = parse_version(assets::CURRENT_VERSION)?; + if have < need { + bail!( + "{}: recipe needs shuru {} or newer, this is {}. Run `shuru upgrade`.", + origin, + min, + assets::CURRENT_VERSION + ); + } + } + Ok(()) +} + +fn parse_version(v: &str) -> Result<(u64, u64, u64)> { + let core = v.trim().trim_start_matches('v'); + let core = core.split(['-', '+']).next().unwrap_or(core); + let mut parts = core.split('.').map(|p| p.parse::()); + let major = parts.next().transpose()?.context("missing major version")?; + let minor = parts.next().transpose()?.unwrap_or(0); + let patch = parts.next().transpose()?.unwrap_or(0); + Ok((major, minor, patch)) +} + +fn load_local(dir: &Path) -> Result { + let dir = dir + .canonicalize() + .with_context(|| format!("recipe directory {} not found", dir.display()))?; + let origin = dir.display().to_string(); + let spec_text = std::fs::read_to_string(dir.join("recipe.json")) + .with_context(|| format!("reading {}/recipe.json", origin))?; + let spec = parse_spec(&spec_text, &origin)?; + let mut hasher = blake3::Hasher::new(); + hasher.update(spec_text.as_bytes()); + let mut steps = Vec::new(); + for step in &spec.steps { + let text = std::fs::read_to_string(dir.join(step)) + .with_context(|| format!("reading step {} in {}", step, origin))?; + hasher.update(step.as_bytes()); + hasher.update(text.as_bytes()); + steps.push((step.clone(), text)); + } + Ok(Recipe { + spec, + steps, + source: origin, + revision: hasher.finalize().to_hex().to_string(), + trusted: true, + }) +} + +fn load_github(owner: &str, repo: &str, path: &str, reference: &str) -> Result { + let sha = resolve_sha(owner, repo, reference)?; + let origin = if path.is_empty() { + format!("{}/{}", owner, repo) + } else { + format!("{}/{}/{}", owner, repo, path) + }; + let spec_text = http_get(&raw_url(owner, repo, &sha, path, "recipe.json"), "text/plain") + .with_context(|| format!("fetching recipe.json for {}@{}", origin, &sha[..7]))?; + let spec = parse_spec(&spec_text, &origin)?; + let mut steps = Vec::new(); + for step in &spec.steps { + let text = http_get(&raw_url(owner, repo, &sha, path, step), "text/plain") + .with_context(|| format!("fetching step {} for {}@{}", step, origin, &sha[..7]))?; + steps.push((step.clone(), text)); + } + Ok(Recipe { + spec, + steps, + source: origin, + revision: sha, + trusted: owner == OFFICIAL_OWNER && repo == OFFICIAL_REPO, + }) +} + +/// Resolve a reference to a recipe with its scripts and exact revision. +pub(crate) fn resolve(reference: &str) -> Result { + match parse_reference(reference)? { + Source::Local(dir) => load_local(&dir), + Source::GitHub { + owner, + repo, + path, + reference, + } => load_github(&owner, &repo, &path, &reference), + } +} + +// --- Display and trust --- + +fn print_summary(recipe: &Recipe, out: &mut impl Write) -> std::io::Result<()> { + writeln!(out, "name: {}", recipe.spec.name)?; + if !recipe.spec.description.is_empty() { + writeln!(out, "description: {}", recipe.spec.description)?; + } + writeln!(out, "source: {}@{}", recipe.source, recipe.short_revision())?; + if let Some(ref from) = recipe.spec.from { + writeln!(out, "from: checkpoint {}", from)?; + } + match &recipe.spec.network { + None => writeln!(out, "network: offline during build")?, + Some(n) if n.allow.is_empty() => writeln!(out, "network: unrestricted during build")?, + Some(n) => writeln!(out, "network: {}", n.allow.join(", "))?, + } + if !recipe.spec.services.is_empty() { + let names: Vec<&str> = recipe.spec.services.keys().map(String::as_str).collect(); + writeln!(out, "services: {}", names.join(", "))?; + } + let steps: Vec = recipe + .steps + .iter() + .map(|(n, t)| format!("{} ({} bytes)", n, t.len())) + .collect(); + writeln!(out, "steps: {}", steps.join(", "))?; + Ok(()) +} + +/// Official catalog and local directories build without asking. Anything +/// else prints its provenance and needs a yes, interactive or by flag. +fn confirm(recipe: &Recipe, yes: bool) -> Result<()> { + if recipe.trusted { + return Ok(()); + } + let mut err = std::io::stderr(); + writeln!(err, "shuru: third-party recipe")?; + print_summary(recipe, &mut err)?; + if yes { + return Ok(()); + } + if !std::io::stdin().is_terminal() { + bail!( + "refusing to build third-party recipe {} without confirmation; pass --yes", + recipe.source + ); + } + write!(err, "Build it? [y/N] ")?; + err.flush()?; + let mut answer = String::new(); + std::io::stdin().read_line(&mut answer)?; + if !matches!(answer.trim(), "y" | "Y" | "yes") { + bail!("aborted"); + } + Ok(()) +} + +// --- Commands --- + +pub(crate) fn show(reference: &str) -> Result<()> { + let recipe = resolve(reference)?; + let mut out = std::io::stdout(); + print_summary(&recipe, &mut out)?; + if !recipe.spec.services.is_empty() { + writeln!(out)?; + for (name, value) in &recipe.spec.services { + writeln!(out, "--- /etc/shuru/services/{}.json ---", name)?; + writeln!(out, "{}", serde_json::to_string_pretty(value)?)?; + } + } + for (name, text) in &recipe.steps { + writeln!(out)?; + writeln!(out, "--- {} ---", name)?; + write!(out, "{}", text)?; + if !text.ends_with('\n') { + writeln!(out)?; + } + } + Ok(()) +} + +fn index_cache_path() -> String { + format!("{}/recipes-index.json", default_data_dir()) +} + +fn fetch_index(refresh: bool) -> Result> { + let cache = index_cache_path(); + if !refresh { + if let Ok(meta) = std::fs::metadata(&cache) { + let fresh = meta + .modified() + .ok() + .and_then(|m| SystemTime::now().duration_since(m).ok()) + .map(|age| age < INDEX_TTL) + .unwrap_or(false); + if fresh { + if let Ok(text) = std::fs::read_to_string(&cache) { + if let Ok(entries) = serde_json::from_str::>(&text) { + return Ok(entries); + } + } + } + } + } + let url = format!( + "https://raw.githubusercontent.com/{}/{}/HEAD/index.json", + OFFICIAL_OWNER, OFFICIAL_REPO + ); + let text = http_get(&url, "application/json").context("fetching the recipe index")?; + let entries: Vec = + serde_json::from_str(&text).context("parsing the recipe index")?; + if let Some(parent) = Path::new(&cache).parent() { + let _ = std::fs::create_dir_all(parent); + } + let _ = std::fs::write(&cache, &text); + Ok(entries) +} + +pub(crate) fn list(refresh: bool) -> Result<()> { + let entries = fetch_index(refresh)?; + if entries.is_empty() { + eprintln!("No recipes published yet."); + return Ok(()); + } + let width = entries.iter().map(|e| e.name.len()).max().unwrap_or(4).max(4); + println!("{: String { + base64::engine::general_purpose::STANDARD.encode(s.as_bytes()) +} + +/// The guest command for one step: write service files on the first step, +/// then run the script from tmpfs so it never lands in the checkpoint. +fn step_command(recipe: &Recipe, index: usize, script: &str) -> Result> { + let mut payload = String::from("set -e\n"); + if index == 0 && !recipe.spec.services.is_empty() { + payload.push_str("mkdir -p /etc/shuru/services\n"); + for (name, value) in &recipe.spec.services { + let json = serde_json::to_string_pretty(value)?; + payload.push_str(&format!( + "echo {} | base64 -d > /etc/shuru/services/{}.json\n", + b64(&json), + name + )); + } + } + payload.push_str(&format!( + "echo {} | base64 -d > /tmp/shuru-recipe-step.sh\n", + b64(script) + )); + payload.push_str("exec sh /tmp/shuru-recipe-step.sh\n"); + Ok(vec![ + "sh".to_string(), + "-c".to_string(), + format!("echo {} | base64 -d | sh", b64(&payload)), + ]) +} + +/// VM settings for a build: the recipe decides size and network, the user +/// may enlarge the VM, and nothing from the project config or the user +/// mounts, ports and secrets reaches the build. +fn build_args(vm: &VmArgs, spec: &RecipeSpec) -> VmArgs { + VmArgs { + cpus: vm.cpus.or(spec.cpus), + memory: vm.memory.or(spec.memory), + disk_size: vm.disk_size.or(spec.disk_size), + kernel: vm.kernel.clone(), + rootfs: vm.rootfs.clone(), + initrd: vm.initrd.clone(), + allow_net: spec.network.is_some(), + dns_resolver: vm.dns_resolver, + allow_host_writes: false, + port: Vec::new(), + mount: Vec::new(), + secret: Vec::new(), + allow_host: spec + .network + .as_ref() + .map(|n| n.allow.clone()) + .unwrap_or_default(), + expose_host: Vec::new(), + config: None, + verbose: vm.verbose, + } +} + +fn meta_path(name: &str) -> String { + format!("{}/checkpoints/{}.json", default_data_dir(), name) +} + +pub(crate) fn read_meta(name: &str) -> Option { + let text = std::fs::read_to_string(meta_path(name)).ok()?; + serde_json::from_str(&text).ok() +} + +pub(crate) fn remove_meta(name: &str) { + let _ = std::fs::remove_file(meta_path(name)); +} + +/// Build `name` from the recipe, one checkpoint per step. +pub(crate) fn build(name: &str, recipe: &Recipe, vm: &VmArgs) -> Result<()> { + shuru_vm::validate_checkpoint_name(name).map_err(|e| anyhow::anyhow!(e))?; + let total = recipe.steps.len(); + eprintln!( + "shuru: building recipe {} from {}@{} ({} step{})", + recipe.spec.name, + recipe.source, + recipe.short_revision(), + total, + if total == 1 { "" } else { "s" } + ); + let args = build_args(vm, &recipe.spec); + let cfg = ShuruConfig::default(); + let mut from = recipe.spec.from.clone(); + let mut intermediates: Vec = Vec::new(); + + for (i, (step_name, script)) in recipe.steps.iter().enumerate() { + let last = i + 1 == total; + let target = if last { + name.to_string() + } else { + format!("{}-step{}", name, i + 1) + }; + eprintln!("shuru: step {}/{}: {}", i + 1, total, step_name); + let command = step_command(recipe, i, script)?; + let code = checkpoint::create_with_config(target.clone(), &args, &cfg, from.as_deref(), command)?; + if code != 0 { + let _ = checkpoint::delete(&target); + if let Some(kept) = intermediates.last() { + eprintln!( + "shuru: intermediate checkpoint {} kept for debugging; delete it with `shuru checkpoint delete {}`", + kept, kept + ); + } + bail!("recipe step {} exited with status {}", step_name, code); + } + if !last { + intermediates.push(target.clone()); + } + from = Some(target); + } + + for t in &intermediates { + checkpoint::delete(t)?; + } + + let meta = CheckpointMeta { + recipe: RecipeMeta { + name: recipe.spec.name.clone(), + source: recipe.source.clone(), + revision: recipe.revision.clone(), + }, + }; + std::fs::write(meta_path(name), serde_json::to_string_pretty(&meta)?) + .context("writing checkpoint metadata")?; + Ok(()) +} + +/// `shuru checkpoint create NAME --recipe REF`. +pub(crate) fn create_checkpoint(name: &str, reference: &str, vm: &VmArgs, yes: bool) -> Result<()> { + let recipe = resolve(reference)?; + confirm(&recipe, yes)?; + if checkpoint::exists(name) { + bail!("checkpoint {} already exists, delete it first", name); + } + build(name, &recipe, vm) +} + +/// `shuru run --recipe REF`: make sure a checkpoint named after the recipe +/// exists at the resolved revision, and return its name. +pub(crate) fn ensure_checkpoint(reference: &str, vm: &VmArgs, yes: bool) -> Result { + let recipe = resolve(reference)?; + confirm(&recipe, yes)?; + let name = recipe.spec.name.clone(); + if checkpoint::exists(&name) { + match read_meta(&name) { + Some(meta) if meta.recipe.revision == recipe.revision => { + eprintln!( + "shuru: using checkpoint {} ({}@{})", + name, + meta.recipe.source, + recipe.short_revision() + ); + return Ok(name); + } + Some(meta) => { + eprintln!( + "shuru: recipe changed ({}@{} -> {}@{}), rebuilding checkpoint {}", + meta.recipe.source, + &meta.recipe.revision[..meta.recipe.revision.len().min(7)], + recipe.source, + recipe.short_revision(), + name + ); + checkpoint::delete(&name)?; + } + None => bail!( + "checkpoint {} exists but was not built from a recipe; delete it or run with --from {}", + name, + name + ), + } + } + build(&name, &recipe, vm)?; + Ok(name) +} diff --git a/crates/shuru-cli/tests/recipes.rs b/crates/shuru-cli/tests/recipes.rs new file mode 100644 index 0000000..6db66b3 --- /dev/null +++ b/crates/shuru-cli/tests/recipes.rs @@ -0,0 +1,274 @@ +//! Recipes (RFC 0005). Local recipe directories are written on the fly and +//! built into throwaway checkpoints in real VMs, so every test but the +//! first is #[ignore]d. Run with: +//! +//! SHURU_BIN=target/debug/shuru cargo test -p shuru-cli --test recipes -- --ignored +//! +//! SHURU_BIN must be a codesigned binary (see tests/docker.rs). SHURU_DATA_DIR, +//! SHURU_KERNEL and SHURU_INITRD are inherited by the CLI. +//! +//! SHURU_DOCKER_RECIPE path to the docker recipe directory from a checkout +//! of superhq-ai/recipes; with SHURU_TEST_NET=1 it is +//! built for real and runs a container + +use std::path::{Path, PathBuf}; +use std::process::{Command, Output, Stdio}; + +fn shuru_bin() -> String { + std::env::var("SHURU_BIN") + .expect("SHURU_BIN not set: point it at a codesigned shuru binary (e.g. just build)") +} + +fn text(out: &Output) -> String { + format!( + "--- stdout ---\n{}\n--- stderr ---\n{}", + String::from_utf8_lossy(&out.stdout), + String::from_utf8_lossy(&out.stderr) + ) +} + +fn stdout(out: &Output) -> String { + String::from_utf8_lossy(&out.stdout).to_string() +} + +fn stderr(out: &Output) -> String { + String::from_utf8_lossy(&out.stderr).to_string() +} + +fn shuru(args: &[&str]) -> Output { + let out = Command::new(shuru_bin()) + .args(args) + .stdin(Stdio::null()) + .output() + .expect("failed to spawn shuru"); + eprintln!("$ shuru {}\n{}", args.join(" "), text(&out)); + out +} + +fn unique(prefix: &str) -> String { + format!("{}-{}", prefix, std::process::id()) +} + +/// A local recipe directory. Steps are plain files so a test can edit one +/// and observe the rebuild. +struct LocalRecipe { + dir: tempfile::TempDir, +} + +impl LocalRecipe { + fn new(name: &str, spec_json: &str, steps: &[(&str, &str)]) -> Self { + let dir = tempfile::tempdir().unwrap(); + let spec = spec_json.replace("NAME", name); + std::fs::write(dir.path().join("recipe.json"), spec).unwrap(); + for (file, body) in steps { + std::fs::write(dir.path().join(file), body).unwrap(); + } + LocalRecipe { dir } + } + + fn path(&self) -> &Path { + self.dir.path() + } + + fn path_str(&self) -> String { + self.dir.path().to_str().unwrap().to_string() + } +} + +struct Cleanup(Vec); + +impl Drop for Cleanup { + fn drop(&mut self) { + for name in &self.0 { + let _ = Command::new(shuru_bin()) + .args(["checkpoint", "delete", name]) + .output(); + } + } +} + +const TWO_STEP_SPEC: &str = r#"{ + "name": "NAME", + "description": "two steps and a service", + "disk_size": 2048, + "services": { + "hello": { + "exec": ["sh", "-c", "touch /run/hello-ran; exec sleep infinity"], + "ready": ["test", "-f", "/run/hello-ran"] + } + }, + "steps": ["first.sh", "second.sh"] +}"#; + +const FIRST_STEP: &str = "mkdir -p /opt/recipe\necho step1 >> /opt/recipe/log\ntest -f /etc/shuru/services/hello.json && echo service-file-present >> /opt/recipe/log\n"; +const SECOND_STEP: &str = "echo step2 >> /opt/recipe/log\ntest -f /run/hello-ran && echo step2-saw-service >> /opt/recipe/log\n"; + +#[test] +fn show_prints_metadata_and_steps_without_booting() { + let recipe = LocalRecipe::new( + "show-test", + TWO_STEP_SPEC, + &[("first.sh", FIRST_STEP), ("second.sh", SECOND_STEP)], + ); + let out = shuru(&["recipe", "show", &recipe.path_str()]); + assert!(out.status.success(), "{}", text(&out)); + let s = stdout(&out); + assert!(s.contains("name: show-test"), "{}", s); + assert!(s.contains("description: two steps and a service"), "{}", s); + assert!(s.contains("network: offline during build"), "{}", s); + assert!(s.contains("services: hello"), "{}", s); + assert!(s.contains("--- /etc/shuru/services/hello.json ---"), "{}", s); + assert!(s.contains("--- first.sh ---"), "{}", s); + assert!(s.contains("echo step2 >> /opt/recipe/log"), "{}", s); +} + +#[test] +fn show_rejects_bad_recipes() { + let bad_name = LocalRecipe::new("Bad Name", TWO_STEP_SPEC, &[("first.sh", ""), ("second.sh", "")]); + let out = shuru(&["recipe", "show", &bad_name.path_str()]); + assert!(!out.status.success()); + assert!(stderr(&out).contains("must match [a-z0-9]"), "{}", text(&out)); + + let missing_step = LocalRecipe::new("ok", TWO_STEP_SPEC, &[("first.sh", "")]); + let out = shuru(&["recipe", "show", &missing_step.path_str()]); + assert!(!out.status.success()); + assert!(stderr(&out).contains("reading step second.sh"), "{}", text(&out)); + + let future = LocalRecipe::new( + "future", + r#"{"name": "NAME", "min_shuru_version": "99.0.0"}"#, + &[("build.sh", "true\n")], + ); + let out = shuru(&["recipe", "show", &future.path_str()]); + assert!(!out.status.success()); + assert!(stderr(&out).contains("needs shuru 99.0.0 or newer"), "{}", text(&out)); +} + +#[test] +#[ignore] +fn run_builds_once_reuses_and_rebuilds_when_the_recipe_changes() { + let name = unique("shuru-test-recipe"); + let _cleanup = Cleanup(vec![name.clone()]); + let recipe = LocalRecipe::new( + &name, + TWO_STEP_SPEC, + &[("first.sh", FIRST_STEP), ("second.sh", SECOND_STEP)], + ); + let check = "cat /opt/recipe/log; test -f /run/hello-ran && echo RUN_SAW_SERVICE"; + + let out = shuru(&["run", "--recipe", &recipe.path_str(), "--", "sh", "-c", check]); + assert!(out.status.success(), "{}", text(&out)); + let s = stdout(&out); + let e = stderr(&out); + assert!(e.contains(&format!("building recipe {} from", name)), "{}", e); + assert!(e.contains("step 1/2: first.sh"), "{}", e); + assert!(e.contains("step 2/2: second.sh"), "{}", e); + assert!(s.contains("step1\nservice-file-present\nstep2\nstep2-saw-service\n"), "{}", s); + assert!(s.contains("RUN_SAW_SERVICE"), "{}", s); + + let out = shuru(&["run", "--recipe", &recipe.path_str(), "--", "sh", "-c", check]); + assert!(out.status.success(), "{}", text(&out)); + let e = stderr(&out); + assert!(e.contains(&format!("using checkpoint {}", name)), "{}", e); + assert!(!e.contains("building recipe"), "{}", e); + + let list = shuru(&["checkpoint", "list"]); + let l = stdout(&list); + let row = l.lines().find(|line| line.starts_with(&name)).unwrap_or(""); + assert!(row.contains(&recipe.path_str()), "{}", l); + + std::fs::write( + recipe.path().join("second.sh"), + format!("{}echo step2-v2 >> /opt/recipe/log\n", SECOND_STEP), + ) + .unwrap(); + let out = shuru(&["run", "--recipe", &recipe.path_str(), "--", "sh", "-c", check]); + assert!(out.status.success(), "{}", text(&out)); + let e = stderr(&out); + assert!(e.contains("recipe changed"), "{}", e); + assert!(e.contains("building recipe"), "{}", e); + assert!(stdout(&out).contains("step2-v2"), "{}", text(&out)); + + let leftovers = stdout(&shuru(&["checkpoint", "list"])); + assert!(!leftovers.contains(&format!("{}-step1", name)), "{}", leftovers); +} + +#[test] +#[ignore] +fn create_builds_under_a_chosen_name_and_refuses_a_command() { + let name = unique("shuru-test-recipe-named"); + let _cleanup = Cleanup(vec![name.clone()]); + let recipe = LocalRecipe::new( + "irrelevant", + r#"{"name": "NAME", "steps": ["build.sh"]}"#, + &[("build.sh", "echo built-by-recipe > /opt/marker\n")], + ); + + let out = shuru(&["checkpoint", "create", &name, "--recipe", &recipe.path_str(), "--", "echo", "no"]); + assert!(!out.status.success(), "{}", text(&out)); + assert!(stderr(&out).contains("drop the command"), "{}", text(&out)); + + let out = shuru(&["checkpoint", "create", &name, "--recipe", &recipe.path_str()]); + assert!(out.status.success(), "{}", text(&out)); + + let out = shuru(&["run", "--from", &name, "--", "cat", "/opt/marker"]); + assert!(out.status.success(), "{}", text(&out)); + assert!(stdout(&out).contains("built-by-recipe"), "{}", text(&out)); + + let out = shuru(&["checkpoint", "create", &name, "--recipe", &recipe.path_str()]); + assert!(!out.status.success(), "{}", text(&out)); + assert!(stderr(&out).contains("already exists"), "{}", text(&out)); +} + +#[test] +#[ignore] +fn failing_step_keeps_no_final_checkpoint() { + let name = unique("shuru-test-recipe-fail"); + let _cleanup = Cleanup(vec![name.clone(), format!("{}-step1", name)]); + let recipe = LocalRecipe::new( + &name, + r#"{"name": "NAME", "steps": ["ok.sh", "bad.sh"]}"#, + &[("ok.sh", "echo fine\n"), ("bad.sh", "echo boom >&2\nexit 7\n")], + ); + let out = shuru(&["run", "--recipe", &recipe.path_str(), "--", "true"]); + assert!(!out.status.success(), "{}", text(&out)); + let e = stderr(&out); + assert!(e.contains("step bad.sh exited with status 7"), "{}", e); + assert!(e.contains(&format!("intermediate checkpoint {}-step1 kept", name)), "{}", e); + let list = stdout(&shuru(&["checkpoint", "list"])); + assert!(!list.lines().any(|l| l.starts_with(&format!("{} ", name))), "{}", list); +} + +#[test] +#[ignore] +fn docker_recipe_builds_and_runs_a_container() { + let Ok(dir) = std::env::var("SHURU_DOCKER_RECIPE") else { + eprintln!("skipped: set SHURU_DOCKER_RECIPE to the docker recipe directory"); + return; + }; + if !std::env::var("SHURU_TEST_NET").map(|v| v == "1").unwrap_or(false) { + eprintln!("skipped: set SHURU_TEST_NET=1"); + return; + } + let dir = PathBuf::from(dir); + let name = unique("shuru-test-recipe-docker"); + let _cleanup = Cleanup(vec![name.clone()]); + + let out = shuru(&["checkpoint", "create", &name, "--recipe", dir.to_str().unwrap()]); + assert!(out.status.success(), "{}", text(&out)); + assert!(stderr(&out).contains("step 2/2: pull.sh"), "{}", text(&out)); + + let out = shuru(&[ + "run", + "--from", + &name, + "--", + "sh", + "-c", + "docker info --format '{{.ServerVersion}}' && docker run --rm nginxinc/nginx-unprivileged:1.31.7-alpine-slim id -u", + ]); + assert!(out.status.success(), "{}", text(&out)); + let s = stdout(&out); + assert!(s.contains("29.9.2"), "{}", s); + assert!(s.contains("\n101\n"), "{}", s); +} diff --git a/docs/rfcs/0005-recipes-evidence.log b/docs/rfcs/0005-recipes-evidence.log new file mode 100644 index 0000000..b5f00be --- /dev/null +++ b/docs/rfcs/0005-recipes-evidence.log @@ -0,0 +1,799 @@ +=== recipes suite (local recipes and the gated docker recipe) + +running 6 tests +test create_builds_under_a_chosen_name_and_refuses_a_command ... $ shuru checkpoint create shuru-test-recipe-named-4199 --recipe /.tmpjsyqiE -- echo no +--- stdout --- + +--- stderr --- +Error: --recipe builds from the recipe steps; drop the command + +$ shuru checkpoint create shuru-test-recipe-named-4199 --recipe /.tmpjsyqiE +--- stdout --- + +--- stderr --- +shuru: building recipe irrelevant from /.tmpjsyqiE@5cf1c28 (1 step) +shuru: step 1/1: build.sh +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: saving checkpoint 'shuru-test-recipe-named-4199'... +shuru: checkpoint 'shuru-test-recipe-named-4199' saved + +$ shuru run --from shuru-test-recipe-named-4199 -- cat /opt/marker +--- stdout --- +built-by-recipe + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +$ shuru checkpoint create shuru-test-recipe-named-4199 --recipe /.tmpjsyqiE +--- stdout --- + +--- stderr --- +Error: checkpoint shuru-test-recipe-named-4199 already exists, delete it first + +ok +test docker_recipe_builds_and_runs_a_container ... $ shuru checkpoint create shuru-test-recipe-docker-4199 --recipe /docker +--- stdout --- +==> Upgrading Debian base (main, security and updates archives) +Preconfiguring packages ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9863 files and directories currently installed.) +Preparing to unpack .../libc6_2.41-12+deb13u4_arm64.deb ... +Unpacking libc6:arm64 (2.41-12+deb13u4) over (2.41-12+deb13u3) ... +Setting up libc6:arm64 (2.41-12+deb13u4) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9863 files and directories currently installed.) +Preparing to unpack .../base-files_13.8+deb13u7_arm64.deb ... +Unpacking base-files (13.8+deb13u7) over (13.8+deb13u6) ... +Setting up base-files (13.8+deb13u7) ... +Installing new version of config file /etc/debian_version ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../bash_5.2.37-2+b10_arm64.deb ... +update-alternatives: warning: alternative /usr/share/man/man7/bash-builtins.7.gz (part of link group builtins.7.gz) doesn't exist; removing from list of alternatives +update-alternatives: warning: /etc/alternatives/builtins.7.gz is dangling; it will be updated with best choice +Unpacking bash (5.2.37-2+b10) over (5.2.37-2+b9) ... +Setting up bash (5.2.37-2+b10) ... +update-alternatives: error: alternative path /usr/share/man/man7/bash-builtins.7.gz doesn't exist +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../bsdutils_1%3a2.41.5-0+deb13u1_arm64.deb ... +Unpacking bsdutils (1:2.41.5-0+deb13u1) over (1:2.41-5) ... +Setting up bsdutils (1:2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../gzip_1.13-1+deb13u1_arm64.deb ... +Unpacking gzip (1.13-1+deb13u1) over (1.13-1) ... +Setting up gzip (1.13-1+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../libperl5.40_5.40.1-6+deb13u1_arm64.deb ... +Unpacking libperl5.40:arm64 (5.40.1-6+deb13u1) over (5.40.1-6) ... +Preparing to unpack .../perl_5.40.1-6+deb13u1_arm64.deb ... +Unpacking perl (5.40.1-6+deb13u1) over (5.40.1-6) ... +Preparing to unpack .../perl-base_5.40.1-6+deb13u1_arm64.deb ... +Unpacking perl-base (5.40.1-6+deb13u1) over (5.40.1-6) ... +Setting up perl-base (5.40.1-6+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../perl-modules-5.40_5.40.1-6+deb13u1_all.deb ... +Unpacking perl-modules-5.40 (5.40.1-6+deb13u1) over (5.40.1-6) ... +Preparing to unpack .../liblastlog2-2_2.41.5-0+deb13u1_arm64.deb ... +Unpacking liblastlog2-2:arm64 (2.41.5-0+deb13u1) over (2.41-5) ... +Setting up liblastlog2-2:arm64 (2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../libuuid1_2.41.5-0+deb13u1_arm64.deb ... +Unpacking libuuid1:arm64 (2.41.5-0+deb13u1) over (2.41-5) ... +Setting up libuuid1:arm64 (2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../libblkid1_2.41.5-0+deb13u1_arm64.deb ... +Unpacking libblkid1:arm64 (2.41.5-0+deb13u1) over (2.41-5) ... +Setting up libblkid1:arm64 (2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../libmount1_2.41.5-0+deb13u1_arm64.deb ... +Unpacking libmount1:arm64 (2.41.5-0+deb13u1) over (2.41-5) ... +Setting up libmount1:arm64 (2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../libsmartcols1_2.41.5-0+deb13u1_arm64.deb ... +Unpacking libsmartcols1:arm64 (2.41.5-0+deb13u1) over (2.41-5) ... +Setting up libsmartcols1:arm64 (2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../util-linux_2.41.5-0+deb13u1_arm64.deb ... +Unpacking util-linux (2.41.5-0+deb13u1) over (2.41-5) ... +Setting up util-linux (2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9877 files and directories currently installed.) +Preparing to unpack .../mount_2.41.5-0+deb13u1_arm64.deb ... +Unpacking mount (2.41.5-0+deb13u1) over (2.41-5) ... +Preparing to unpack .../libsqlite3-0_3.46.1-7+deb13u2_arm64.deb ... +Unpacking libsqlite3-0:arm64 (3.46.1-7+deb13u2) over (3.46.1-7+deb13u1) ... +Setting up libsqlite3-0:arm64 (3.46.1-7+deb13u2) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9877 files and directories currently installed.) +Preparing to unpack .../libc-bin_2.41-12+deb13u4_arm64.deb ... +Unpacking libc-bin (2.41-12+deb13u4) over (2.41-12+deb13u3) ... +Setting up libc-bin (2.41-12+deb13u4) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9877 files and directories currently installed.) +Preparing to unpack .../libaudit-common_1%3a4.0.2-2+deb13u1_all.deb ... +Unpacking libaudit-common (1:4.0.2-2+deb13u1) over (1:4.0.2-2) ... +Setting up libaudit-common (1:4.0.2-2+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9877 files and directories currently installed.) +Preparing to unpack .../libaudit1_1%3a4.0.2-2+deb13u1_arm64.deb ... +Unpacking libaudit1:arm64 (1:4.0.2-2+deb13u1) over (1:4.0.2-2+b2) ... +Setting up libaudit1:arm64 (1:4.0.2-2+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9876 files and directories currently installed.) +Preparing to unpack .../login_1%3a4.16.0-2+really2.41.5-0+deb13u1_arm64.deb ... +Unpacking login (1:4.16.0-2+really2.41.5-0+deb13u1) over (1:4.16.0-2+really2.41-5) ... +Preparing to unpack .../libexpat1_2.9.0-1~deb13u1_arm64.deb ... +Unpacking libexpat1:arm64 (2.9.0-1~deb13u1) over (2.7.1-2) ... +Preparing to unpack .../libcap2_1%3a2.75-10+deb13u1+b3_arm64.deb ... +Unpacking libcap2:arm64 (1:2.75-10+deb13u1+b3) over (1:2.75-10+deb13u1+b1) ... +Setting up libcap2:arm64 (1:2.75-10+deb13u1+b3) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9878 files and directories currently installed.) +Preparing to unpack .../liblzma5_5.8.1-1+deb13u2_arm64.deb ... +Unpacking liblzma5:arm64 (5.8.1-1+deb13u2) over (5.8.1-1+deb13u1) ... +Setting up liblzma5:arm64 (5.8.1-1+deb13u2) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9878 files and directories currently installed.) +Preparing to unpack .../libpcre2-8-0_10.46-1~deb13u3_arm64.deb ... +Unpacking libpcre2-8-0:arm64 (10.46-1~deb13u3) over (10.46-1~deb13u1) ... +Setting up libpcre2-8-0:arm64 (10.46-1~deb13u3) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9878 files and directories currently installed.) +Preparing to unpack .../openssl-provider-legacy_3.5.7-1~deb13u3_arm64.deb ... +Unpacking openssl-provider-legacy (3.5.7-1~deb13u3) over (3.5.6-1~deb13u2) ... +Setting up openssl-provider-legacy (3.5.7-1~deb13u3) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9878 files and directories currently installed.) +Preparing to unpack .../libssl3t64_3.5.7-1~deb13u3_arm64.deb ... +Unpacking libssl3t64:arm64 (3.5.7-1~deb13u3) over (3.5.6-1~deb13u2) ... +Setting up libssl3t64:arm64 (3.5.7-1~deb13u3) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9878 files and directories currently installed.) +Preparing to unpack .../00-tzdata_2026e-0+deb13u1_all.deb ... +Unpacking tzdata (2026e-0+deb13u1) over (2026b-0+deb13u1) ... +Preparing to unpack .../01-openssl_3.5.7-1~deb13u3_arm64.deb ... +Unpacking openssl (3.5.7-1~deb13u3) over (3.5.6-1~deb13u2) ... +Preparing to unpack .../02-ca-certificates_20250419+deb13u1_all.deb ... +Unpacking ca-certificates (20250419+deb13u1) over (20250419) ... +Preparing to unpack .../03-xz-utils_5.8.1-1+deb13u2_arm64.deb ... +Unpacking xz-utils (5.8.1-1+deb13u2) over (5.8.1-1+deb13u1) ... +Preparing to unpack .../04-libbrotli1_1.1.0-2+deb13u1_arm64.deb ... +Unpacking libbrotli1:arm64 (1.1.0-2+deb13u1) over (1.1.0-2+b7) ... +Preparing to unpack .../05-libssh2-1t64_1.11.1-1+deb13u2_arm64.deb ... +Unpacking libssh2-1t64:arm64 (1.11.1-1+deb13u2) over (1.11.1-1+deb13u1) ... +Preparing to unpack .../06-curl_8.14.1-2+deb13u7_arm64.deb ... +Unpacking curl (8.14.1-2+deb13u7) over (8.14.1-2+deb13u4) ... +Preparing to unpack .../07-libcurl4t64_8.14.1-2+deb13u7_arm64.deb ... +Unpacking libcurl4t64:arm64 (8.14.1-2+deb13u7) over (8.14.1-2+deb13u4) ... +Preparing to unpack .../08-jq_1.7.1-6+deb13u4_arm64.deb ... +Unpacking jq (1.7.1-6+deb13u4) over (1.7.1-6+deb13u2) ... +Preparing to unpack .../09-libjq1_1.7.1-6+deb13u4_arm64.deb ... +Unpacking libjq1:arm64 (1.7.1-6+deb13u4) over (1.7.1-6+deb13u2) ... +Preparing to unpack .../10-libcap2-bin_1%3a2.75-10+deb13u1+b3_arm64.deb ... +Unpacking libcap2-bin (1:2.75-10+deb13u1+b3) over (1:2.75-10+deb13u1+b1) ... +Preparing to unpack .../11-libcom-err2_1.47.2-3+b12_arm64.deb ... +Unpacking libcom-err2:arm64 (1.47.2-3+b12) over (1.47.2-3+b11) ... +Preparing to unpack .../12-libcurl3t64-gnutls_8.14.1-2+deb13u7_arm64.deb ... +Unpacking libcurl3t64-gnutls:arm64 (8.14.1-2+deb13u7) over (8.14.1-2+deb13u4) ... +Setting up libexpat1:arm64 (2.9.0-1~deb13u1) ... +Setting up libjq1:arm64 (1.7.1-6+deb13u4) ... +Setting up libbrotli1:arm64 (1.1.0-2+deb13u1) ... +Setting up libcom-err2:arm64 (1.47.2-3+b12) ... +Setting up tzdata (2026e-0+deb13u1) ... + +Current default time zone: 'Etc/UTC' +Local time is now: Mon Oct 26 01:54:54 UTC 2026. +Universal Time is now: Mon Oct 26 01:54:54 UTC 2026. +Run 'dpkg-reconfigure tzdata' if you wish to change it. + +Setting up libcap2-bin (1:2.75-10+deb13u1+b3) ... +Setting up xz-utils (5.8.1-1+deb13u2) ... +Setting up mount (2.41.5-0+deb13u1) ... +Setting up perl-modules-5.40 (5.40.1-6+deb13u1) ... +Setting up jq (1.7.1-6+deb13u4) ... +Setting up libssh2-1t64:arm64 (1.11.1-1+deb13u2) ... +Setting up openssl (3.5.7-1~deb13u3) ... +Setting up login (1:4.16.0-2+really2.41.5-0+deb13u1) ... +Setting up libcurl4t64:arm64 (8.14.1-2+deb13u7) ... +Setting up libcurl3t64-gnutls:arm64 (8.14.1-2+deb13u7) ... +Setting up libperl5.40:arm64 (5.40.1-6+deb13u1) ... +Setting up ca-certificates (20250419+deb13u1) ... +Updating certificates in /etc/ssl/certs... +rehash: warning: skipping ca-certificates.crt, it does not contain exactly one certificate or CRL +0 added, 2 removed; done. +Setting up perl (5.40.1-6+deb13u1) ... +Setting up curl (8.14.1-2+deb13u7) ... +Processing triggers for debianutils (5.23.2) ... +Processing triggers for libc-bin (2.41-12+deb13u4) ... +Processing triggers for ca-certificates (20250419+deb13u1) ... +Updating certificates in /etc/ssl/certs... +0 added, 0 removed; done. +Running hooks in /etc/ca-certificates/update.d... +done. +==> Adding Docker apt repository (key pinned by SHA-256) +/etc/apt/keyrings/docker.asc: OK +==> Installing docker-ce 5:29.9.2-1~debian.13~trixie, containerd.io 2.4.2-3~debian.13~trixie +Selecting previously unselected package containerd.io. +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9875 files and directories currently installed.) +Preparing to unpack .../00-containerd.io_2.4.2-3~debian.13~trixie_arm64.deb ... +Unpacking containerd.io (2.4.2-3~debian.13~trixie) ... +Selecting previously unselected package docker-ce-cli. +Preparing to unpack .../01-docker-ce-cli_5%3a29.9.2-1~debian.13~trixie_arm64.deb ... +Unpacking docker-ce-cli (5:29.9.2-1~debian.13~trixie) ... +Selecting previously unselected package libip4tc2:arm64. +Preparing to unpack .../02-libip4tc2_1.8.11-2_arm64.deb ... +Unpacking libip4tc2:arm64 (1.8.11-2) ... +Selecting previously unselected package libip6tc2:arm64. +Preparing to unpack .../03-libip6tc2_1.8.11-2_arm64.deb ... +Unpacking libip6tc2:arm64 (1.8.11-2) ... +Selecting previously unselected package netbase. +Preparing to unpack .../04-netbase_6.5_all.deb ... +Unpacking netbase (6.5) ... +Selecting previously unselected package libnfnetlink0:arm64. +Preparing to unpack .../05-libnfnetlink0_1.0.2-3_arm64.deb ... +Unpacking libnfnetlink0:arm64 (1.0.2-3) ... +Selecting previously unselected package libnetfilter-conntrack3:arm64. +Preparing to unpack .../06-libnetfilter-conntrack3_1.1.0-1_arm64.deb ... +Unpacking libnetfilter-conntrack3:arm64 (1.1.0-1) ... +Selecting previously unselected package libnftnl11:arm64. +Preparing to unpack .../07-libnftnl11_1.2.9-1_arm64.deb ... +Unpacking libnftnl11:arm64 (1.2.9-1) ... +Selecting previously unselected package iptables. +Preparing to unpack .../08-iptables_1.8.11-2_arm64.deb ... +Unpacking iptables (1.8.11-2) ... +Selecting previously unselected package libjansson4:arm64. +Preparing to unpack .../09-libjansson4_2.14-2+b3_arm64.deb ... +Unpacking libjansson4:arm64 (2.14-2+b3) ... +Selecting previously unselected package libnftables1:arm64. +Preparing to unpack .../10-libnftables1_1.1.3-1_arm64.deb ... +Unpacking libnftables1:arm64 (1.1.3-1) ... +Selecting previously unselected package nftables. +Preparing to unpack .../11-nftables_1.1.3-1_arm64.deb ... +Unpacking nftables (1.1.3-1) ... +Selecting previously unselected package docker-ce. +Preparing to unpack .../12-docker-ce_5%3a29.9.2-1~debian.13~trixie_arm64.deb ... +Unpacking docker-ce (5:29.9.2-1~debian.13~trixie) ... +Setting up libip4tc2:arm64 (1.8.11-2) ... +Setting up libip6tc2:arm64 (1.8.11-2) ... +Setting up libnftnl11:arm64 (1.2.9-1) ... +Setting up libjansson4:arm64 (2.14-2+b3) ... +Setting up containerd.io (2.4.2-3~debian.13~trixie) ... +Setting up docker-ce-cli (5:29.9.2-1~debian.13~trixie) ... +Setting up libnfnetlink0:arm64 (1.0.2-3) ... +Setting up netbase (6.5) ... +Setting up libnftables1:arm64 (1.1.3-1) ... +Setting up nftables (1.1.3-1) ... +Setting up libnetfilter-conntrack3:arm64 (1.1.0-1) ... +Setting up iptables (1.8.11-2) ... +update-alternatives: using /usr/sbin/iptables-legacy to provide /usr/sbin/iptables (iptables) in auto mode +update-alternatives: using /usr/sbin/ip6tables-legacy to provide /usr/sbin/ip6tables (ip6tables) in auto mode +update-alternatives: using /usr/sbin/iptables-nft to provide /usr/sbin/iptables (iptables) in auto mode +update-alternatives: using /usr/sbin/ip6tables-nft to provide /usr/sbin/ip6tables (ip6tables) in auto mode +update-alternatives: using /usr/sbin/arptables-nft to provide /usr/sbin/arptables (arptables) in auto mode +update-alternatives: using /usr/sbin/ebtables-nft to provide /usr/sbin/ebtables (ebtables) in auto mode +Setting up docker-ce (5:29.9.2-1~debian.13~trixie) ... +invoke-rc.d: could not determine current runlevel +invoke-rc.d: WARNING: No init system and policy-rc.d missing! Defaulting to block. +Processing triggers for libc-bin (2.41-12+deb13u4) ... +==> Installed versions +Docker version 29.9.2, build a82e528 +containerd containerd v2.4.2 b7a25261e029d68978bbf290df0a62fc819b3c51 +runc version 1.5.2 +==> Pulling nginxinc/nginx-unprivileged:1.31.7-alpine-slim@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 +docker.io/nginxinc/nginx-unprivileged@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7: Pulling from nginxinc/nginx-unprivileged +4b40f23576bc: Pulling fs layer +a9986cd6f37d: Pulling fs layer +d74d0cecaf1a: Pulling fs layer +115972ae778a: Pulling fs layer +98f56d1336e8: Pulling fs layer +581a829fa84a: Pulling fs layer +4bc482c4f270: Pulling fs layer +2fe8f2a34241: Pulling fs layer +44136fa355b3: Download complete +115972ae778a: Download complete +2fe8f2a34241: Download complete +98f56d1336e8: Download complete +4b40f23576bc: Download complete +581a829fa84a: Download complete +4bc482c4f270: Download complete +e437ba1f09a3: Download complete +d74d0cecaf1a: Download complete +a9986cd6f37d: Download complete +a9986cd6f37d: Pull complete +115972ae778a: Pull complete +2fe8f2a34241: Pull complete +98f56d1336e8: Pull complete +4b40f23576bc: Pull complete +581a829fa84a: Pull complete +4bc482c4f270: Pull complete +d74d0cecaf1a: Pull complete +Digest: sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 +Status: Downloaded newer image for nginxinc/nginx-unprivileged@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 +docker.io/nginxinc/nginx-unprivileged:1.31.7-alpine-slim@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 +REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE +nginxinc/nginx-unprivileged 1.31.7-alpine-slim sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 a8cb0f33d51f 7 days ago 30.3MB + +--- stderr --- +shuru: building recipe docker from /docker@1b30f3d (2 steps) +shuru: step 1/2: install.sh +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: saving checkpoint 'shuru-test-recipe-docker-4199-step1'... +shuru: checkpoint 'shuru-test-recipe-docker-4199-step1' saved +shuru: step 2/2: pull.sh +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: saving checkpoint 'shuru-test-recipe-docker-4199'... +shuru: checkpoint 'shuru-test-recipe-docker-4199' saved +shuru: checkpoint 'shuru-test-recipe-docker-4199-step1' deleted + +$ shuru run --from shuru-test-recipe-docker-4199 -- sh -c docker info --format '{{.ServerVersion}}' && docker run --rm nginxinc/nginx-unprivileged:1.31.7-alpine-slim id -u +--- stdout --- +29.9.2 +101 + +--- stderr --- +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +ok +test failing_step_keeps_no_final_checkpoint ... $ shuru run --recipe /.tmpOh1uVw -- true +--- stdout --- +fine + +--- stderr --- +shuru: building recipe shuru-test-recipe-fail-4199 from /.tmpOh1uVw@6590f2b (2 steps) +shuru: step 1/2: ok.sh +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +shuru: saving checkpoint 'shuru-test-recipe-fail-4199-step1'... +shuru: checkpoint 'shuru-test-recipe-fail-4199-step1' saved +shuru: step 2/2: bad.sh +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +boom +shuru: saving checkpoint 'shuru-test-recipe-fail-4199'... +shuru: checkpoint 'shuru-test-recipe-fail-4199' saved +shuru: checkpoint 'shuru-test-recipe-fail-4199' deleted +shuru: intermediate checkpoint shuru-test-recipe-fail-4199-step1 kept for debugging; delete it with `shuru checkpoint delete shuru-test-recipe-fail-4199-step1` +Error: recipe step bad.sh exited with status 7 + +$ shuru checkpoint list +--- stdout --- +NAME SIZE CREATED RECIPE +docker 1.3 GB 4m ago /docker@dcbbf2c +shuru-test-recipe-fail-4199-step1 1008 MB just now + +--- stderr --- + +ok +test run_builds_once_reuses_and_rebuilds_when_the_recipe_changes ... $ shuru run --recipe /.tmpEZbp9s -- sh -c cat /opt/recipe/log; test -f /run/hello-ran && echo RUN_SAW_SERVICE +--- stdout --- +step1 +service-file-present +step2 +step2-saw-service +RUN_SAW_SERVICE + +--- stderr --- +shuru: building recipe shuru-test-recipe-4199 from /.tmpEZbp9s@48ff0ed (2 steps) +shuru: step 1/2: first.sh +shuru: booting VM (2cpus, 2048MB RAM, 2048MB disk)... +shuru: saving checkpoint 'shuru-test-recipe-4199-step1'... +shuru: checkpoint 'shuru-test-recipe-4199-step1' saved +shuru: step 2/2: second.sh +shuru: booting VM (2cpus, 2048MB RAM, 2048MB disk)... +shuru: saving checkpoint 'shuru-test-recipe-4199'... +shuru: checkpoint 'shuru-test-recipe-4199' saved +shuru: checkpoint 'shuru-test-recipe-4199-step1' deleted +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +$ shuru run --recipe /.tmpEZbp9s -- sh -c cat /opt/recipe/log; test -f /run/hello-ran && echo RUN_SAW_SERVICE +--- stdout --- +step1 +service-file-present +step2 +step2-saw-service +RUN_SAW_SERVICE + +--- stderr --- +shuru: using checkpoint shuru-test-recipe-4199 (/.tmpEZbp9s@48ff0ed) +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +$ shuru checkpoint list +--- stdout --- +NAME SIZE CREATED RECIPE +docker 1.3 GB 4m ago /docker@dcbbf2c +shuru-test-recipe-4199 1008 MB just now /.tmpEZbp9s@48ff0ed + +--- stderr --- + +$ shuru run --recipe /.tmpEZbp9s -- sh -c cat /opt/recipe/log; test -f /run/hello-ran && echo RUN_SAW_SERVICE +--- stdout --- +step1 +service-file-present +step2 +step2-saw-service +step2-v2 +RUN_SAW_SERVICE + +--- stderr --- +shuru: recipe changed (/.tmpEZbp9s@48ff0ed -> /.tmpEZbp9s@ae89e3d), rebuilding checkpoint shuru-test-recipe-4199 +shuru: checkpoint 'shuru-test-recipe-4199' deleted +shuru: building recipe shuru-test-recipe-4199 from /.tmpEZbp9s@ae89e3d (2 steps) +shuru: step 1/2: first.sh +shuru: booting VM (2cpus, 2048MB RAM, 2048MB disk)... +shuru: saving checkpoint 'shuru-test-recipe-4199-step1'... +shuru: checkpoint 'shuru-test-recipe-4199-step1' saved +shuru: step 2/2: second.sh +shuru: booting VM (2cpus, 2048MB RAM, 2048MB disk)... +shuru: saving checkpoint 'shuru-test-recipe-4199'... +shuru: checkpoint 'shuru-test-recipe-4199' saved +shuru: checkpoint 'shuru-test-recipe-4199-step1' deleted +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... + +$ shuru checkpoint list +--- stdout --- +NAME SIZE CREATED RECIPE +docker 1.3 GB 4m ago /docker@dcbbf2c +shuru-test-recipe-4199 1008 MB just now /.tmpEZbp9s@ae89e3d + +--- stderr --- + +ok +test show_prints_metadata_and_steps_without_booting ... $ shuru recipe show /.tmp0W2qfk +--- stdout --- +name: show-test +description: two steps and a service +source: /.tmp0W2qfk@d559800 +network: offline during build +services: hello +steps: first.sh (138 bytes), second.sh (98 bytes) + +--- /etc/shuru/services/hello.json --- +{ + "exec": [ + "sh", + "-c", + "touch /run/hello-ran; exec sleep infinity" + ], + "ready": [ + "test", + "-f", + "/run/hello-ran" + ] +} + +--- first.sh --- +mkdir -p /opt/recipe +echo step1 >> /opt/recipe/log +test -f /etc/shuru/services/hello.json && echo service-file-present >> /opt/recipe/log + +--- second.sh --- +echo step2 >> /opt/recipe/log +test -f /run/hello-ran && echo step2-saw-service >> /opt/recipe/log + +--- stderr --- + +ok +test show_rejects_bad_recipes ... $ shuru recipe show /.tmpkH5s9O +--- stdout --- + +--- stderr --- +Error: /.tmpkH5s9O: recipe name "Bad Name" must match [a-z0-9][a-z0-9._-]* + +$ shuru recipe show /.tmpqu4jAZ +--- stdout --- + +--- stderr --- +Error: reading step second.sh in /.tmpqu4jAZ + +Caused by: + No such file or directory (os error 2) + +$ shuru recipe show /.tmpk4H0o8 +--- stdout --- + +--- stderr --- +Error: /.tmpk4H0o8: recipe needs shuru 99.0.0 or newer, this is 0.8.0. Run `shuru upgrade`. + +ok + +test result: ok. 6 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 130.08s + +recipes-exit=0 +=== shuru recipe list (github.com/superhq-ai/recipes) +NAME DESCRIPTION +docker Docker Engine 29.9 with dockerd as a guest service and nginx-unprivileged pre-pulled + +Source: github.com/superhq-ai/recipes. Build one with `shuru run --recipe NAME` or `shuru checkpoint create NAME --recipe NAME`. +list-exit=0 +=== shuru run --recipe docker (first use rebuilds: existing checkpoint came from a local path) +shuru: recipe changed (/docker@dcbbf2c -> superhq-ai/recipes/docker@2a5c726), rebuilding checkpoint docker +shuru: checkpoint 'docker' deleted +shuru: building recipe docker from superhq-ai/recipes/docker@2a5c726 (2 steps) +shuru: step 1/2: install.sh +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +==> Upgrading Debian base (main, security and updates archives) +Preconfiguring packages ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9863 files and directories currently installed.) +Preparing to unpack .../libc6_2.41-12+deb13u4_arm64.deb ... +Unpacking libc6:arm64 (2.41-12+deb13u4) over (2.41-12+deb13u3) ... +Setting up libc6:arm64 (2.41-12+deb13u4) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9863 files and directories currently installed.) +Preparing to unpack .../base-files_13.8+deb13u7_arm64.deb ... +Unpacking base-files (13.8+deb13u7) over (13.8+deb13u6) ... +Setting up base-files (13.8+deb13u7) ... +Installing new version of config file /etc/debian_version ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../bash_5.2.37-2+b10_arm64.deb ... +update-alternatives: warning: alternative /usr/share/man/man7/bash-builtins.7.gz (part of link group builtins.7.gz) doesn't exist; removing from list of alternatives +update-alternatives: warning: /etc/alternatives/builtins.7.gz is dangling; it will be updated with best choice +Unpacking bash (5.2.37-2+b10) over (5.2.37-2+b9) ... +Setting up bash (5.2.37-2+b10) ... +update-alternatives: error: alternative path /usr/share/man/man7/bash-builtins.7.gz doesn't exist +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../bsdutils_1%3a2.41.5-0+deb13u1_arm64.deb ... +Unpacking bsdutils (1:2.41.5-0+deb13u1) over (1:2.41-5) ... +Setting up bsdutils (1:2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../gzip_1.13-1+deb13u1_arm64.deb ... +Unpacking gzip (1.13-1+deb13u1) over (1.13-1) ... +Setting up gzip (1.13-1+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../libperl5.40_5.40.1-6+deb13u1_arm64.deb ... +Unpacking libperl5.40:arm64 (5.40.1-6+deb13u1) over (5.40.1-6) ... +Preparing to unpack .../perl_5.40.1-6+deb13u1_arm64.deb ... +Unpacking perl (5.40.1-6+deb13u1) over (5.40.1-6) ... +Preparing to unpack .../perl-base_5.40.1-6+deb13u1_arm64.deb ... +Unpacking perl-base (5.40.1-6+deb13u1) over (5.40.1-6) ... +Setting up perl-base (5.40.1-6+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../perl-modules-5.40_5.40.1-6+deb13u1_all.deb ... +Unpacking perl-modules-5.40 (5.40.1-6+deb13u1) over (5.40.1-6) ... +Preparing to unpack .../liblastlog2-2_2.41.5-0+deb13u1_arm64.deb ... +Unpacking liblastlog2-2:arm64 (2.41.5-0+deb13u1) over (2.41-5) ... +Setting up liblastlog2-2:arm64 (2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../libuuid1_2.41.5-0+deb13u1_arm64.deb ... +Unpacking libuuid1:arm64 (2.41.5-0+deb13u1) over (2.41-5) ... +Setting up libuuid1:arm64 (2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../libblkid1_2.41.5-0+deb13u1_arm64.deb ... +Unpacking libblkid1:arm64 (2.41.5-0+deb13u1) over (2.41-5) ... +Setting up libblkid1:arm64 (2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../libmount1_2.41.5-0+deb13u1_arm64.deb ... +Unpacking libmount1:arm64 (2.41.5-0+deb13u1) over (2.41-5) ... +Setting up libmount1:arm64 (2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../libsmartcols1_2.41.5-0+deb13u1_arm64.deb ... +Unpacking libsmartcols1:arm64 (2.41.5-0+deb13u1) over (2.41-5) ... +Setting up libsmartcols1:arm64 (2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9872 files and directories currently installed.) +Preparing to unpack .../util-linux_2.41.5-0+deb13u1_arm64.deb ... +Unpacking util-linux (2.41.5-0+deb13u1) over (2.41-5) ... +Setting up util-linux (2.41.5-0+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9877 files and directories currently installed.) +Preparing to unpack .../mount_2.41.5-0+deb13u1_arm64.deb ... +Unpacking mount (2.41.5-0+deb13u1) over (2.41-5) ... +Preparing to unpack .../libsqlite3-0_3.46.1-7+deb13u2_arm64.deb ... +Unpacking libsqlite3-0:arm64 (3.46.1-7+deb13u2) over (3.46.1-7+deb13u1) ... +Setting up libsqlite3-0:arm64 (3.46.1-7+deb13u2) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9877 files and directories currently installed.) +Preparing to unpack .../libc-bin_2.41-12+deb13u4_arm64.deb ... +Unpacking libc-bin (2.41-12+deb13u4) over (2.41-12+deb13u3) ... +Setting up libc-bin (2.41-12+deb13u4) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9877 files and directories currently installed.) +Preparing to unpack .../libaudit-common_1%3a4.0.2-2+deb13u1_all.deb ... +Unpacking libaudit-common (1:4.0.2-2+deb13u1) over (1:4.0.2-2) ... +Setting up libaudit-common (1:4.0.2-2+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9877 files and directories currently installed.) +Preparing to unpack .../libaudit1_1%3a4.0.2-2+deb13u1_arm64.deb ... +Unpacking libaudit1:arm64 (1:4.0.2-2+deb13u1) over (1:4.0.2-2+b2) ... +Setting up libaudit1:arm64 (1:4.0.2-2+deb13u1) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9876 files and directories currently installed.) +Preparing to unpack .../login_1%3a4.16.0-2+really2.41.5-0+deb13u1_arm64.deb ... +Unpacking login (1:4.16.0-2+really2.41.5-0+deb13u1) over (1:4.16.0-2+really2.41-5) ... +Preparing to unpack .../libexpat1_2.9.0-1~deb13u1_arm64.deb ... +Unpacking libexpat1:arm64 (2.9.0-1~deb13u1) over (2.7.1-2) ... +Preparing to unpack .../libcap2_1%3a2.75-10+deb13u1+b3_arm64.deb ... +Unpacking libcap2:arm64 (1:2.75-10+deb13u1+b3) over (1:2.75-10+deb13u1+b1) ... +Setting up libcap2:arm64 (1:2.75-10+deb13u1+b3) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9878 files and directories currently installed.) +Preparing to unpack .../liblzma5_5.8.1-1+deb13u2_arm64.deb ... +Unpacking liblzma5:arm64 (5.8.1-1+deb13u2) over (5.8.1-1+deb13u1) ... +Setting up liblzma5:arm64 (5.8.1-1+deb13u2) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9878 files and directories currently installed.) +Preparing to unpack .../libpcre2-8-0_10.46-1~deb13u3_arm64.deb ... +Unpacking libpcre2-8-0:arm64 (10.46-1~deb13u3) over (10.46-1~deb13u1) ... +Setting up libpcre2-8-0:arm64 (10.46-1~deb13u3) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9878 files and directories currently installed.) +Preparing to unpack .../openssl-provider-legacy_3.5.7-1~deb13u3_arm64.deb ... +Unpacking openssl-provider-legacy (3.5.7-1~deb13u3) over (3.5.6-1~deb13u2) ... +Setting up openssl-provider-legacy (3.5.7-1~deb13u3) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9878 files and directories currently installed.) +Preparing to unpack .../libssl3t64_3.5.7-1~deb13u3_arm64.deb ... +Unpacking libssl3t64:arm64 (3.5.7-1~deb13u3) over (3.5.6-1~deb13u2) ... +Setting up libssl3t64:arm64 (3.5.7-1~deb13u3) ... +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9878 files and directories currently installed.) +Preparing to unpack .../00-tzdata_2026e-0+deb13u1_all.deb ... +Unpacking tzdata (2026e-0+deb13u1) over (2026b-0+deb13u1) ... +Preparing to unpack .../01-openssl_3.5.7-1~deb13u3_arm64.deb ... +Unpacking openssl (3.5.7-1~deb13u3) over (3.5.6-1~deb13u2) ... +Preparing to unpack .../02-ca-certificates_20250419+deb13u1_all.deb ... +Unpacking ca-certificates (20250419+deb13u1) over (20250419) ... +Preparing to unpack .../03-xz-utils_5.8.1-1+deb13u2_arm64.deb ... +Unpacking xz-utils (5.8.1-1+deb13u2) over (5.8.1-1+deb13u1) ... +Preparing to unpack .../04-libbrotli1_1.1.0-2+deb13u1_arm64.deb ... +Unpacking libbrotli1:arm64 (1.1.0-2+deb13u1) over (1.1.0-2+b7) ... +Preparing to unpack .../05-libssh2-1t64_1.11.1-1+deb13u2_arm64.deb ... +Unpacking libssh2-1t64:arm64 (1.11.1-1+deb13u2) over (1.11.1-1+deb13u1) ... +Preparing to unpack .../06-curl_8.14.1-2+deb13u7_arm64.deb ... +Unpacking curl (8.14.1-2+deb13u7) over (8.14.1-2+deb13u4) ... +Preparing to unpack .../07-libcurl4t64_8.14.1-2+deb13u7_arm64.deb ... +Unpacking libcurl4t64:arm64 (8.14.1-2+deb13u7) over (8.14.1-2+deb13u4) ... +Preparing to unpack .../08-jq_1.7.1-6+deb13u4_arm64.deb ... +Unpacking jq (1.7.1-6+deb13u4) over (1.7.1-6+deb13u2) ... +Preparing to unpack .../09-libjq1_1.7.1-6+deb13u4_arm64.deb ... +Unpacking libjq1:arm64 (1.7.1-6+deb13u4) over (1.7.1-6+deb13u2) ... +Preparing to unpack .../10-libcap2-bin_1%3a2.75-10+deb13u1+b3_arm64.deb ... +Unpacking libcap2-bin (1:2.75-10+deb13u1+b3) over (1:2.75-10+deb13u1+b1) ... +Preparing to unpack .../11-libcom-err2_1.47.2-3+b12_arm64.deb ... +Unpacking libcom-err2:arm64 (1.47.2-3+b12) over (1.47.2-3+b11) ... +Preparing to unpack .../12-libcurl3t64-gnutls_8.14.1-2+deb13u7_arm64.deb ... +Unpacking libcurl3t64-gnutls:arm64 (8.14.1-2+deb13u7) over (8.14.1-2+deb13u4) ... +Setting up libexpat1:arm64 (2.9.0-1~deb13u1) ... +Setting up libjq1:arm64 (1.7.1-6+deb13u4) ... +Setting up libbrotli1:arm64 (1.1.0-2+deb13u1) ... +Setting up libcom-err2:arm64 (1.47.2-3+b12) ... +Setting up tzdata (2026e-0+deb13u1) ... + +Current default time zone: 'Etc/UTC' +Local time is now: Mon Oct 26 01:57:04 UTC 2026. +Universal Time is now: Mon Oct 26 01:57:04 UTC 2026. +Run 'dpkg-reconfigure tzdata' if you wish to change it. + +Setting up libcap2-bin (1:2.75-10+deb13u1+b3) ... +Setting up xz-utils (5.8.1-1+deb13u2) ... +Setting up mount (2.41.5-0+deb13u1) ... +Setting up perl-modules-5.40 (5.40.1-6+deb13u1) ... +Setting up jq (1.7.1-6+deb13u4) ... +Setting up libssh2-1t64:arm64 (1.11.1-1+deb13u2) ... +Setting up openssl (3.5.7-1~deb13u3) ... +Setting up login (1:4.16.0-2+really2.41.5-0+deb13u1) ... +Setting up libcurl4t64:arm64 (8.14.1-2+deb13u7) ... +Setting up libcurl3t64-gnutls:arm64 (8.14.1-2+deb13u7) ... +Setting up libperl5.40:arm64 (5.40.1-6+deb13u1) ... +Setting up ca-certificates (20250419+deb13u1) ... +Updating certificates in /etc/ssl/certs... +rehash: warning: skipping ca-certificates.crt, it does not contain exactly one certificate or CRL +0 added, 2 removed; done. +Setting up perl (5.40.1-6+deb13u1) ... +Setting up curl (8.14.1-2+deb13u7) ... +Processing triggers for debianutils (5.23.2) ... +Processing triggers for libc-bin (2.41-12+deb13u4) ... +Processing triggers for ca-certificates (20250419+deb13u1) ... +Updating certificates in /etc/ssl/certs... +0 added, 0 removed; done. +Running hooks in /etc/ca-certificates/update.d... +done. +==> Adding Docker apt repository (key pinned by SHA-256) +/etc/apt/keyrings/docker.asc: OK +==> Installing docker-ce 5:29.9.2-1~debian.13~trixie, containerd.io 2.4.2-3~debian.13~trixie +Selecting previously unselected package containerd.io. +(Reading database ... (Reading database ... 5% (Reading database ... 10% (Reading database ... 15% (Reading database ... 20% (Reading database ... 25% (Reading database ... 30% (Reading database ... 35% (Reading database ... 40% (Reading database ... 45% (Reading database ... 50% (Reading database ... 55% (Reading database ... 60% (Reading database ... 65% (Reading database ... 70% (Reading database ... 75% (Reading database ... 80% (Reading database ... 85% (Reading database ... 90% (Reading database ... 95% (Reading database ... 100% (Reading database ... 9875 files and directories currently installed.) +Preparing to unpack .../00-containerd.io_2.4.2-3~debian.13~trixie_arm64.deb ... +Unpacking containerd.io (2.4.2-3~debian.13~trixie) ... +Selecting previously unselected package docker-ce-cli. +Preparing to unpack .../01-docker-ce-cli_5%3a29.9.2-1~debian.13~trixie_arm64.deb ... +Unpacking docker-ce-cli (5:29.9.2-1~debian.13~trixie) ... +Selecting previously unselected package libip4tc2:arm64. +Preparing to unpack .../02-libip4tc2_1.8.11-2_arm64.deb ... +Unpacking libip4tc2:arm64 (1.8.11-2) ... +Selecting previously unselected package libip6tc2:arm64. +Preparing to unpack .../03-libip6tc2_1.8.11-2_arm64.deb ... +Unpacking libip6tc2:arm64 (1.8.11-2) ... +Selecting previously unselected package netbase. +Preparing to unpack .../04-netbase_6.5_all.deb ... +Unpacking netbase (6.5) ... +Selecting previously unselected package libnfnetlink0:arm64. +Preparing to unpack .../05-libnfnetlink0_1.0.2-3_arm64.deb ... +Unpacking libnfnetlink0:arm64 (1.0.2-3) ... +Selecting previously unselected package libnetfilter-conntrack3:arm64. +Preparing to unpack .../06-libnetfilter-conntrack3_1.1.0-1_arm64.deb ... +Unpacking libnetfilter-conntrack3:arm64 (1.1.0-1) ... +Selecting previously unselected package libnftnl11:arm64. +Preparing to unpack .../07-libnftnl11_1.2.9-1_arm64.deb ... +Unpacking libnftnl11:arm64 (1.2.9-1) ... +Selecting previously unselected package iptables. +Preparing to unpack .../08-iptables_1.8.11-2_arm64.deb ... +Unpacking iptables (1.8.11-2) ... +Selecting previously unselected package libjansson4:arm64. +Preparing to unpack .../09-libjansson4_2.14-2+b3_arm64.deb ... +Unpacking libjansson4:arm64 (2.14-2+b3) ... +Selecting previously unselected package libnftables1:arm64. +Preparing to unpack .../10-libnftables1_1.1.3-1_arm64.deb ... +Unpacking libnftables1:arm64 (1.1.3-1) ... +Selecting previously unselected package nftables. +Preparing to unpack .../11-nftables_1.1.3-1_arm64.deb ... +Unpacking nftables (1.1.3-1) ... +Selecting previously unselected package docker-ce. +Preparing to unpack .../12-docker-ce_5%3a29.9.2-1~debian.13~trixie_arm64.deb ... +Unpacking docker-ce (5:29.9.2-1~debian.13~trixie) ... +Setting up libip4tc2:arm64 (1.8.11-2) ... +Setting up libip6tc2:arm64 (1.8.11-2) ... +Setting up libnftnl11:arm64 (1.2.9-1) ... +Setting up libjansson4:arm64 (2.14-2+b3) ... +Setting up containerd.io (2.4.2-3~debian.13~trixie) ... +Setting up docker-ce-cli (5:29.9.2-1~debian.13~trixie) ... +Setting up libnfnetlink0:arm64 (1.0.2-3) ... +Setting up netbase (6.5) ... +Setting up libnftables1:arm64 (1.1.3-1) ... +Setting up nftables (1.1.3-1) ... +Setting up libnetfilter-conntrack3:arm64 (1.1.0-1) ... +Setting up iptables (1.8.11-2) ... +update-alternatives: using /usr/sbin/iptables-legacy to provide /usr/sbin/iptables (iptables) in auto mode +update-alternatives: using /usr/sbin/ip6tables-legacy to provide /usr/sbin/ip6tables (ip6tables) in auto mode +update-alternatives: using /usr/sbin/iptables-nft to provide /usr/sbin/iptables (iptables) in auto mode +update-alternatives: using /usr/sbin/ip6tables-nft to provide /usr/sbin/ip6tables (ip6tables) in auto mode +update-alternatives: using /usr/sbin/arptables-nft to provide /usr/sbin/arptables (arptables) in auto mode +update-alternatives: using /usr/sbin/ebtables-nft to provide /usr/sbin/ebtables (ebtables) in auto mode +Setting up docker-ce (5:29.9.2-1~debian.13~trixie) ... +invoke-rc.d: could not determine current runlevel +invoke-rc.d: WARNING: No init system and policy-rc.d missing! Defaulting to block. +Processing triggers for libc-bin (2.41-12+deb13u4) ... +==> Installed versions +Docker version 29.9.2, build a82e528 +containerd containerd v2.4.2 b7a25261e029d68978bbf290df0a62fc819b3c51 +runc version 1.5.2 +shuru: saving checkpoint 'docker-step1'... +shuru: checkpoint 'docker-step1' saved +shuru: step 2/2: pull.sh +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +==> Pulling nginxinc/nginx-unprivileged:1.31.7-alpine-slim@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 +docker.io/nginxinc/nginx-unprivileged@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7: Pulling from nginxinc/nginx-unprivileged +4b40f23576bc: Pulling fs layer +115972ae778a: Pulling fs layer +98f56d1336e8: Pulling fs layer +d74d0cecaf1a: Pulling fs layer +581a829fa84a: Pulling fs layer +a9986cd6f37d: Pulling fs layer +2fe8f2a34241: Pulling fs layer +4bc482c4f270: Pulling fs layer +44136fa355b3: Download complete +115972ae778a: Download complete +98f56d1336e8: Download complete +4bc482c4f270: Download complete +581a829fa84a: Download complete +2fe8f2a34241: Download complete +4b40f23576bc: Download complete +e437ba1f09a3: Download complete +a9986cd6f37d: Download complete +a9986cd6f37d: Pull complete +d74d0cecaf1a: Download complete +115972ae778a: Pull complete +98f56d1336e8: Pull complete +4bc482c4f270: Pull complete +581a829fa84a: Pull complete +2fe8f2a34241: Pull complete +4b40f23576bc: Pull complete +d74d0cecaf1a: Pull complete +Digest: sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 +Status: Downloaded newer image for nginxinc/nginx-unprivileged@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 +docker.io/nginxinc/nginx-unprivileged:1.31.7-alpine-slim@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 +REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE +nginxinc/nginx-unprivileged 1.31.7-alpine-slim sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 a8cb0f33d51f 7 days ago 30.3MB +shuru: saving checkpoint 'docker'... +shuru: checkpoint 'docker' saved +shuru: checkpoint 'docker-step1' deleted +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +29.9.2 +101 + +real 2m3.632s +user 0m20.139s +sys 0m3.259s +run-recipe-exit=0 +=== shuru run --recipe docker (second use reuses the checkpoint) +shuru: using checkpoint docker (superhq-ai/recipes/docker@2a5c726) +shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... +REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE +nginxinc/nginx-unprivileged 1.31.7-alpine-slim sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 a8cb0f33d51f 7 days ago 30.3MB + +real 0m3.910s +user 0m0.068s +sys 0m0.017s +run-recipe-reuse-exit=0 +=== checkpoint list and sidecar +NAME SIZE CREATED RECIPE +docker 1.3 GB just now superhq-ai/recipes/docker@2a5c726 +{ + "recipe": { + "name": "docker", + "source": "superhq-ai/recipes/docker", + "revision": "2a5c726ee5fa4812b5315fa4b8b81650118b5305" + } +} diff --git a/docs/rfcs/0005-recipes.md b/docs/rfcs/0005-recipes.md new file mode 100644 index 0000000..bd8e411 --- /dev/null +++ b/docs/rfcs/0005-recipes.md @@ -0,0 +1,288 @@ +# RFC 0005: Recipes + +- Status: Implemented +- Date: 2026-10-26 +- Scope: shuru-cli, the superhq-ai/recipes repository +- Depends on: RFC 0004 + +## Summary + +A recipe is a small directory, `recipe.json` plus one or more shell steps, +that describes how to turn the base image or an existing checkpoint into a +new checkpoint. Recipes live in git. The official catalog is +`superhq-ai/recipes` on GitHub, any repository can hold more, and a local +directory works for development. The CLI resolves a recipe to an exact +commit, builds it through the ordinary checkpoint flow, and records where +the checkpoint came from. + +``` +shuru recipe list +shuru recipe show docker +shuru checkpoint create docker --recipe docker +shuru run --recipe docker -p 8080:8080 -- docker run --rm -p 8080:8080 nginx +``` + +The last form builds the checkpoint on first use and reuses it afterwards. + +## Motivation + +RFC 0003 shipped Docker support as a shell script in the repository. The +installed CLI knows nothing about it, so a Homebrew user has to clone the +repo to get a Docker checkpoint. The same is true of every "install X into +a sandbox" recipe people write: it is a one-off script in some other +project, with no versioning, no provenance on the checkpoint it produced, +and no way to share it short of copy and paste. + +The pieces already exist. `shuru checkpoint create` is the build step, RFC +0004 services are the runtime contract, and git is the distribution +channel every user already has. A recipe is the glue, kept deliberately +small. + +## Non-goals + +- Parameters or templating inside recipes. A recipe is fixed; variants are + separate recipes. +- Dependencies between recipes beyond `from` naming a checkpoint. +- Signing beyond the git commit SHA. Authenticity rests on GitHub and the + repository owner. +- A registry service. The catalog is a JSON file in a git repository. +- Prebuilt checkpoint downloads. Possible later, orthogonal to this. + +## Design + +### Recipe layout + +``` +docker/ + recipe.json + install.sh + pull.sh +``` + +`recipe.json`: + +```json +{ + "name": "docker", + "description": "Docker Engine with dockerd as a guest service", + "min_shuru_version": "0.8.0", + "from": null, + "disk_size": 4096, + "memory": 2048, + "network": {"allow": ["deb.debian.org", "download.docker.com"]}, + "services": { + "docker": {"exec": ["dockerd"], "ready": ["docker", "info"]} + }, + "steps": ["install.sh", "pull.sh"] +} +``` + +| field | required | meaning | +|---|---|---| +| `name` | yes | checkpoint name used by `shuru run --recipe`. `[a-z0-9][a-z0-9._-]*`. | +| `description` | no | one line for `recipe list` and `recipe show`. | +| `min_shuru_version` | no | refuse to build on an older CLI. | +| `from` | no | existing checkpoint to start from instead of the base image. | +| `cpus`, `memory`, `disk_size` | no | VM size for the build. CLI flags override. | +| `network.allow` | no | hosts the build may reach. Absent means the build runs offline. An empty list means unrestricted. | +| `services` | no | RFC 0004 service files, written before the first step runs. | +| `steps` | no | scripts run in order, default `["build.sh"]`. | + +Each step runs in its own boot. The first boots from `from` or the base +image, every later step boots from the checkpoint the previous step saved. +Services are written during the first step, so from the second step on +they are running. This is why the Docker recipe has two steps: the first +installs the engine and declares the service, the second pulls an image +with dockerd already up. Intermediate checkpoints are deleted when the +build succeeds and kept, with a message, when it fails. + +A step script is sent to the guest as a base64 payload the same way the +RFC 0003 script was, so it can use any quoting it likes. It runs with +`sh`, from `/`, as root, and its exit status fails the build. + +### References + +| form | resolves to | +|---|---| +| `docker` | `superhq-ai/recipes`, directory `docker`, default branch | +| `owner/repo` | that repository root | +| `owner/repo/path/to/dir` | a directory in that repository | +| any of the above `@ref` | a branch, tag or commit | +| `./dir`, `/abs/dir`, `../dir` | a local directory | + +A GitHub reference is resolved to a commit SHA through the GitHub API +before anything is fetched, and the files are then read at that SHA from +`raw.githubusercontent.com`. The SHA is printed, is what the checkpoint +records, and is what `--recipe docker@` pins. `GITHUB_TOKEN` or +`GH_TOKEN`, when set, is sent to api.github.com only, for private +repositories and rate limits. + +A local recipe gets a content hash in place of a SHA, so editing a step +counts as a new revision. + +### Trust + +A recipe runs inside the VM, under the network allowlist it declares, so +it can shape the checkpoint but cannot touch the host. It still decides +what every later sandbox built from it contains. The CLI therefore prints +the source, the commit and the allowlist before every build, and for +anything that is not the official catalog or a local path it asks for +confirmation on a terminal, or requires `--yes` without one. + +### Checkpoint provenance + +A checkpoint built from a recipe gets a sidecar +`checkpoints/.json`: + +```json +{"recipe": {"name": "docker", "source": "superhq-ai/recipes/docker", "revision": ""}} +``` + +`shuru checkpoint list` shows it. `shuru checkpoint delete` removes it +with the image. + +### `shuru run --recipe` + +1. Resolve the reference and confirm trust. +2. Look for a checkpoint named after the recipe. + - Present with a matching revision: reuse it. + - Present with a different revision: say so, delete it, rebuild. + - Present without a sidecar: refuse, since it is not ours to replace. + - Absent: build. +3. Run the command from that checkpoint with the flags the user gave. + +The build and the run are separate phases with separate network policy. +The build uses the recipe allowlist. The run uses whatever `--allow-net` +and `--allow-host` the user passed, which by default is nothing. + +### Catalog + +`shuru recipe list` reads `index.json` from the default branch of +`superhq-ai/recipes`, a flat array of `{name, description}` that the +repository validates in CI against its directories. The file is cached in +the data directory for a day; `--refresh` bypasses the cache. +`shuru recipe show ` prints the metadata and every step script, so +the contents can be read before they are built. + +### The recipes repository + +`superhq-ai/recipes` holds `index.json`, one directory per recipe, a +validation script, and a workflow that runs it. The Docker recipe moves +there from `scripts/prepare-docker-checkpoint.sh`, which is removed from +this repository. Pinned versions, the apt key hash and the image digest +stay in the recipe. + +## Security + +- Builds run with the recipe allowlist, never the project `shuru.json`, so + a project config cannot leak secrets into a recipe build and a recipe + cannot widen a project policy. +- The checkpoint records the exact commit. Two users building the same + reference at the same SHA run the same script. +- Third-party recipes require an explicit yes. Official and local do not, + because the official catalog is reviewed in its own repository and a + local directory is code the user already owns. +- A recipe cannot name a service with a path, and service names and + recipe names are validated before anything is written. + +Residual risks: + +- GitHub is trusted for both the SHA lookup and the file contents. A + compromised GitHub account that owns a recipe can change what builds, + which is the same exposure as any git dependency. +- Reuse is keyed on the recipe revision, not on the base image. A new + Shuru release with a new rootfs does not rebuild existing recipe + checkpoints. `min_shuru_version` catches the case where the recipe + needs the newer kernel. + +## Testing + +`crates/shuru-cli/tests/recipes.rs` uses local recipes built on the fly: + +- `recipe show` prints metadata and steps without booting anything +- a two step recipe with a service: step one output, step two output, + and proof the service was running during step two and during the run +- `run --recipe` builds once, reuses on the next run, and rebuilds after + the step script changes, with the sidecar reflecting each revision +- `checkpoint create NAME --recipe` under a chosen name +- with network, the real Docker recipe from a checkout of + `superhq-ai/recipes` builds and runs a container as uid 101 + +## Rollout + +The Docker checkpoint for the RFC 0003 test suite is now built with +`shuru checkpoint create docker --recipe docker` against the official +catalog, or from a checkout while a recipe is being changed. The README and +the website show that form first and `shuru run --recipe docker` as the +one-liner. + +## Appendix A: Evidence + +Captured on 2026-10-26 against real VMs on an M-series Mac, kernel 6.12.114, +isolated data dir, codesigned debug CLI 0.8.0, with the official catalog at +superhq-ai/recipes commit 2a5c726. Full `--nocapture` output is in +`docs/rfcs/0005-recipes-evidence.log`. + +Recipes suite, six tests in one run (two parse-only, three on throwaway +local recipes, one that builds the docker recipe for real): + +``` +test result: ok. 6 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 130.08s +``` + +Lines that show each behaviour, from that log: + +``` +shuru: building recipe shuru-test-recipe-4199 from /.tmpEZbp9s@48ff0ed (2 steps) +shuru: step 1/2: first.sh +shuru: step 2/2: second.sh +step1 +service-file-present +step2 +step2-saw-service +RUN_SAW_SERVICE +shuru: using checkpoint shuru-test-recipe-4199 (/.tmpEZbp9s@48ff0ed) +shuru: recipe changed (/.tmpEZbp9s@48ff0ed -> /.tmpEZbp9s@ae89e3d), rebuilding checkpoint shuru-test-recipe-4199 + +Error: --recipe builds from the recipe steps; drop the command +Error: checkpoint shuru-test-recipe-named-4199 already exists, delete it first + +shuru: intermediate checkpoint shuru-test-recipe-fail-4199-step1 kept for debugging; delete it with `shuru checkpoint delete shuru-test-recipe-fail-4199-step1` +Error: recipe step bad.sh exited with status 7 + +shuru: step 2/2: pull.sh +Digest: sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 +29.9.2 +101 +``` + +The official path, resolved from GitHub. The data dir held a `docker` +checkpoint built from a local checkout, so the first `shuru run --recipe +docker` saw a different source and rebuilt; the second reused it: + +``` +$ shuru recipe list --refresh +NAME DESCRIPTION +docker Docker Engine 29.9 with dockerd as a guest service and nginx-unprivileged pre-pulled + +$ shuru run --recipe docker -- sh -c "docker info --format '{{.ServerVersion}}'; docker run --rm nginxinc/nginx-unprivileged:1.31.7-alpine-slim id -u" +shuru: recipe changed (/docker@dcbbf2c -> superhq-ai/recipes/docker@2a5c726), rebuilding checkpoint docker +shuru: step 1/2: install.sh +shuru: step 2/2: pull.sh +shuru: checkpoint 'docker' saved +29.9.2 +101 +real 2m3.632s + +$ shuru run --recipe docker -- docker image ls --digests +shuru: using checkpoint docker (superhq-ai/recipes/docker@2a5c726) +real 0m3.910s + +$ shuru checkpoint list +NAME SIZE CREATED RECIPE +docker 1.3 GB just now superhq-ai/recipes/docker@2a5c726 +``` + +The RFC 0003 Docker suite was rerun against a checkpoint built by the +recipe and passed nine of nine in 78.79s; its log is +`docs/rfcs/0003-docker-on-shuru-evidence.log`. From 0f75bf96a14372abd4c52b99d2121d148d212523 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 07:31:01 +0530 Subject: [PATCH 18/57] docker: build the checkpoint from the docker recipe The two step script moves to the docker recipe in superhq-ai/recipes, where a pull by digest is tagged afterwards so docker run by tag works offline. README, changelog, RFC 0003 and 0004 and the website show shuru checkpoint create docker --recipe docker and the shuru run --recipe docker one-liner. The RFC 0003 suite evidence is regenerated against a recipe-built checkpoint. --- CHANGELOG.md | 24 +++- README.md | 34 ++++- crates/shuru-cli/tests/docker.rs | 5 +- docs/rfcs/0003-docker-on-shuru-evidence.log | 78 ++++++------ docs/rfcs/0003-docker-on-shuru.md | 15 +-- docs/rfcs/0004-guest-services.md | 29 ++--- scripts/prepare-docker-checkpoint.sh | 131 -------------------- www/src/components/landing/CliSection.astro | 10 +- 8 files changed, 119 insertions(+), 207 deletions(-) delete mode 100755 scripts/prepare-docker-checkpoint.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c84df1..c050354 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,14 +12,26 @@ down over vsock, which also syncs the disk, so checkpoints are cloned from a consistent image on every stop path. `Sandbox::stop()` is graceful and `Sandbox::kill()` is the old hard stop. See docs/rfcs/0004-guest-services.md. +### Recipes + +`shuru run --recipe REF` and `shuru checkpoint create NAME --recipe REF` +build a checkpoint from a recipe: a directory with `recipe.json` and shell +steps, fetched from GitHub at an exact commit or read from a local path. +`shuru recipe list` shows the official catalog in superhq-ai/recipes and +`shuru recipe show REF` prints a recipe before it is built. Checkpoints built +this way record their source and revision, visible in `shuru checkpoint +list`, and a changed recipe rebuilds on the next run. Third-party recipes +ask for confirmation or `--yes`. See docs/rfcs/0005-recipes.md. + ### Docker Engine runs inside the VM -`scripts/prepare-docker-checkpoint.sh` builds a checkpoint with pinned -docker-ce 29.9.2 and containerd 2.4.2 and one pre-pulled image, with dockerd -declared as a guest service so `shuru run --from docker -- docker run ...` -just works. Containers get the same boundary as any guest process: no egress -without `--allow-net`, the host allowlist applied by the proxy, host ports -only through `-p`. +The `docker` recipe installs pinned docker-ce 29.9.2 and containerd 2.4.2, +declares dockerd as a guest service, and pre-pulls one image, so +`shuru checkpoint create docker --recipe docker` followed by +`shuru run --from docker -- docker run ...` just works, as does +`shuru run --recipe docker` on its own. Containers get the same boundary as +any guest process: no egress without `--allow-net`, the host allowlist +applied by the proxy, host ports only through `-p`. To support it, the guest kernel gains cgroup v2 controllers, cgroup BPF, seccomp filters, veth, and the netfilter targets dockerd installs, and moves diff --git a/README.md b/README.md index 3264aa6..e7b8611 100644 --- a/README.md +++ b/README.md @@ -207,14 +207,37 @@ uv run --with browser-use --with openai examples/browser-use.py The example keeps Chromium inside the microVM and exposes only its CDP port to the host. +## Recipes + +A recipe is a versioned description of a checkpoint: a `recipe.json` with +metadata and services, plus shell steps that run in fresh boots. The official +catalog lives in [superhq-ai/recipes](https://github.com/superhq-ai/recipes). + +```sh +shuru recipe list # the official catalog +shuru recipe show docker # metadata, services and every step +shuru checkpoint create docker --recipe docker # build the checkpoint under that name +shuru run --from docker -- docker ps # and start from it like any other +shuru run --recipe docker -- docker ps # or both at once: builds on first use, reuses after +shuru checkpoint create mydocker --recipe docker # the same recipe under a name of your own +shuru run --recipe owner/repo/path@v1 --yes -- ... # third-party, pinned to a tag +shuru run --recipe ./my-recipe -- ... # local directory while developing +``` + +References resolve to an exact commit, which is printed and recorded next to +the checkpoint. `shuru checkpoint list` shows where each one came from, and a +changed recipe rebuilds on the next `shuru run --recipe`. Builds use the +network allowlist the recipe declares, never the project `shuru.json`. See +docs/rfcs/0005-recipes.md. + ## Docker -Docker Engine runs inside the VM. Install it into a checkpoint once, then run -containers from that checkpoint with networking disabled: +Docker Engine runs inside the VM through the `docker` recipe. Build the +checkpoint once, then start from it; after that containers run with +networking disabled: ```sh -# One-time: pinned docker-ce + containerd, with one image pre-pulled -./scripts/prepare-docker-checkpoint.sh +shuru checkpoint create docker --recipe docker # Serve the pre-pulled nginx-unprivileged image on host port 8080 shuru run --from docker -p 8080:8080 -- \ @@ -222,6 +245,9 @@ shuru run --from docker -p 8080:8080 -- \ curl http://127.0.0.1:8080/ ``` +`shuru run --recipe docker -- ...` does both: it builds the checkpoint on +first use and reuses it afterwards. + dockerd is a guest service: it starts when the VM boots, the command waits until `docker info` answers, and the daemon is stopped and the disk synced before the VM powers off. Pulling other images needs `--allow-net`, and the diff --git a/crates/shuru-cli/tests/docker.rs b/crates/shuru-cli/tests/docker.rs index 04a050b..9d02645 100644 --- a/crates/shuru-cli/tests/docker.rs +++ b/crates/shuru-cli/tests/docker.rs @@ -1,6 +1,7 @@ //! Docker Engine inside a Shuru VM (RFC 0003). Boots real VMs from the -//! checkpoint built by scripts/prepare-docker-checkpoint.sh, so every test -//! is #[ignore]d. Run with: +//! checkpoint built by the docker recipe (`shuru checkpoint create docker +//! --recipe docker`, or `--recipe /docker` from a local clone of +//! superhq-ai/recipes), so every test is #[ignore]d. Run with: //! //! SHURU_BIN=target/debug/shuru cargo test -p shuru-cli --test docker -- --ignored //! diff --git a/docs/rfcs/0003-docker-on-shuru-evidence.log b/docs/rfcs/0003-docker-on-shuru-evidence.log index 6795244..f846f15 100644 --- a/docs/rfcs/0003-docker-on-shuru-evidence.log +++ b/docs/rfcs/0003-docker-on-shuru-evidence.log @@ -1,4 +1,3 @@ - running 9 tests test container_cannot_reach_host_loopback_services ... $ shuru run --from docker --- stdout --- @@ -17,7 +16,7 @@ HOSTNAME_BLOCKED shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... ok -test container_cannot_write_to_host_through_default_mount ... $ shuru run --from docker --mount /.tmpthbsMx:/workspace +test container_cannot_write_to_host_through_default_mount ... $ shuru run --from docker --mount /.tmplVg3uU:/workspace --- stdout --- from-host WROTE_IN_GUEST @@ -68,45 +67,45 @@ seccomp-mode=Seccomp: 2 shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... ok -test http_through_port_forward_reaches_container ... $ shuru run --from docker -p 61603:8080 +test http_through_port_forward_reaches_container ... $ shuru run --from docker -p 62055:8080 --- stdout --- READY STOPPED --- stderr --- shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... -shuru: forwarding 127.0.0.1:61603 -> guest:8080 +shuru: forwarding 127.0.0.1:62055 -> guest:8080 -$ GET http://127.0.0.1:61603/ +$ GET http://127.0.0.1:62055/ HTTP/1.1 200 OK Server: nginx/1.31.7 -Date: Mon, 26 Oct 2026 01:02:26 GMT +Date: Mon, 26 Oct 2026 01:52:48 GMT Content-Type: text/html -Content-Length: 19 -Last-Modified: Mon, 26 Oct 2026 01:02:26 GMT +Content-Length: 18 +Last-Modified: Mon, 26 Oct 2026 01:52:48 GMT Connection: close -ETag: "6adea6a2-13" +ETag: "6adeb270-12" Accept-Ranges: bytes -shuru-docker-98351 +shuru-docker-3781 ok test named_volume_persists_across_container_restart ... $ shuru run --from docker --- stdout --- -after-container-restart=persisted-98351 -after-new-container=persisted-98351 +after-container-restart=persisted-3781 +after-new-container=persisted-3781 --- stderr --- shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... ok -test named_volume_persists_across_vm_stop_start_via_checkpoint ... $ shuru checkpoint create shuru-test-docker-data-98351 --verbose --from docker +test named_volume_persists_across_vm_stop_start_via_checkpoint ... $ shuru checkpoint create shuru-test-docker-data-3781 --verbose --from docker --- stdout --- --- stderr --- shuru: creating working copy... shuru: kernel=/Image -shuru: rootfs=/instances/98441/rootfs.ext4 (work copy) +shuru: rootfs=/instances/3954/rootfs.ext4 (work copy) shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... shuru: VM created and validated successfully shuru: VM started, waiting for guest... @@ -114,7 +113,7 @@ random: crng init done virtio_blk virtio1: 1/0/0 default/read/poll queues virtio_blk virtio1: [vda] 8388608 512-byte logical blocks (4.29 GB/4.00 GiB) rtc-pl031 20050000.pl031: registered as rtc0 -rtc-pl031 20050000.pl031: setting system clock to 2026-10-26T01:02:32 UTC (1792976552) +rtc-pl031 20050000.pl031: setting system clock to 2026-10-26T01:52:55 UTC (1792979575) NET: Registered PF_INET6 protocol family Segment Routing with IPv6 In-situ OAM (IOAM) with IPv6 @@ -126,37 +125,37 @@ clk: Disabling unused clocks Freeing unused kernel memory: 896K Run /init as init process EXT4-fs (vda): mounted filesystem 728de991-e6e3-4e1a-873d-bc29aeff5c07 r/w with ordered data mode. Quota mode: disabled. -shuru-guest[ 213.6ms]: starting as PID 1 -shuru-guest[ 213.9ms]: filesystems mounted +shuru-guest[ 197.7ms]: starting as PID 1 +shuru-guest[ 198.0ms]: filesystems mounted shuru-guest: no network device (sandbox mode) -shuru-guest[ 214.0ms]: networking ready -shuru-guest[ 216.6ms]: 1 service(s) starting -shuru-guest[ 216.6ms]: vsock listening on port 1024 -shuru-guest[ 216.6ms]: port forward listener on port 1025 +shuru-guest[ 198.1ms]: networking ready +shuru-guest[ 201.2ms]: 1 service(s) starting +shuru-guest[ 201.2ms]: vsock listening on port 1024 +shuru-guest[ 201.3ms]: port forward listener on port 1025 shuru-guest: accepted vsock connection shuru-guest: service docker ready -docker0: port 1(veth2b33299) entered blocking state -docker0: port 1(veth2b33299) entered disabled state -veth2b33299: entered allmulticast mode -veth2b33299: entered promiscuous mode -eth0: renamed from vethd3aa798 -docker0: port 1(veth2b33299) entered blocking state -docker0: port 1(veth2b33299) entered forwarding state -docker0: port 1(veth2b33299) entered disabled state -vethd3aa798: renamed from eth0 -docker0: port 1(veth2b33299) entered disabled state -veth2b33299 (unregistering): left allmulticast mode -veth2b33299 (unregistering): left promiscuous mode -docker0: port 1(veth2b33299) entered disabled state +docker0: port 1(vethc9efcd6) entered blocking state +docker0: port 1(vethc9efcd6) entered disabled state +vethc9efcd6: entered allmulticast mode +vethc9efcd6: entered promiscuous mode +eth0: renamed from vethd1f34a1 +docker0: port 1(vethc9efcd6) entered blocking state +docker0: port 1(vethc9efcd6) entered forwarding state +docker0: port 1(vethc9efcd6) entered disabled state +vethd1f34a1: renamed from eth0 +docker0: port 1(vethc9efcd6) entered disabled state +vethc9efcd6 (unregistering): left allmulticast mode +vethc9efcd6 (unregistering): left promiscuous mode +docker0: port 1(vethc9efcd6) entered disabled state shuru-guest: accepted vsock connection shuru-guest: services stopped in 1.0s (stopped: ["docker"], killed: []) shuru: stopped services: docker -shuru: saving checkpoint 'shuru-test-docker-data-98351'... -shuru: checkpoint 'shuru-test-docker-data-98351' saved +shuru: saving checkpoint 'shuru-test-docker-data-3781'... +shuru: checkpoint 'shuru-test-docker-data-3781' saved -$ shuru run --from shuru-test-docker-data-98351 +$ shuru run --from shuru-test-docker-data-3781 --- stdout --- -after-vm-restart=vm-persisted-98351 +after-vm-restart=vm-persisted-3781 --- stderr --- shuru: booting VM (2cpus, 2048MB RAM, 4096MB disk)... @@ -177,5 +176,4 @@ WARNING: Your kernel does not support swap limit capabilities or the cgroup is n ok -test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 78.78s - +test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 78.79s diff --git a/docs/rfcs/0003-docker-on-shuru.md b/docs/rfcs/0003-docker-on-shuru.md index e984ff3..80e6b8a 100644 --- a/docs/rfcs/0003-docker-on-shuru.md +++ b/docs/rfcs/0003-docker-on-shuru.md @@ -85,8 +85,9 @@ checkpoints. ### Docker checkpoint -`scripts/prepare-docker-checkpoint.sh` creates a checkpoint (default name -`docker`) by running, inside a VM with a strict host allowlist: +The `docker` recipe in `superhq-ai/recipes` (RFC 0005; originally a script +in this repository) creates the checkpoint by running, inside a VM with a +strict host allowlist: 1. Enable the trixie-security and trixie-updates archives (debootstrap only lists main) and `apt-get upgrade`. @@ -210,7 +211,7 @@ SELinux, AppArmor, btrfs, macvlan, ipvlan, ftp conntrack helpers. ### Checkpoint -`scripts/prepare-docker-checkpoint.sh` ran inside a VM allowed to reach only +The Docker checkpoint build ran inside a VM allowed to reach only deb.debian.org, security.debian.org, download.docker.com, `*.docker.io`, `*.docker.com`, `*.cloudflarestorage.com`: @@ -233,7 +234,7 @@ the rebuilt checkpoint: Rerun after RFC 0004 moved dockerd to a guest service, same nine tests: - test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 78.78s + test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 78.79s Raw output of the rerun is in `docs/rfcs/0003-docker-on-shuru-evidence.log`. Excerpts, identical between the two runs: @@ -296,8 +297,8 @@ Image, Trivy 0.76 with the 2026-10-25 database, `linux/arm64`: Both fixes landed in Alpine after the 2026-10-19 image build. There is no newer `nginx-unprivileged` build yet. Residual: a medium zlib issue in a -process that runs as uid 101 under seccomp inside a VM. Re-run -`prepare-docker-checkpoint.sh` with a newer digest when the image rebuilds. +process that runs as uid 101 under seccomp inside a VM. Update the digest in +the recipe when the image rebuilds. Guest Debian layer, `debsecan --suite trixie --only-fixed` inside the VM: 36 fixable package entries (openssl, curl, expat, pcre2, brotli, xz) before @@ -333,6 +334,6 @@ the kernel against per-CVE data (LTS point release is the mitigation). export SHURU_KERNEL=$SHURU_DATA_DIR/Image SHURU_INITRD=$SHURU_DATA_DIR/initramfs.cpio.gz export SHURU_ROOTFS=~/.local/share/shuru/rootfs.ext4 - SHURU_BIN=/tmp/shuru-signed ./scripts/prepare-docker-checkpoint.sh + /tmp/shuru-signed checkpoint create docker --recipe docker SHURU_BIN=/tmp/shuru-signed SHURU_TEST_NET=1 \ cargo test -p shuru-cli --test docker -- --ignored --test-threads=1 diff --git a/docs/rfcs/0004-guest-services.md b/docs/rfcs/0004-guest-services.md index c59e0f5..e2ff366 100644 --- a/docs/rfcs/0004-guest-services.md +++ b/docs/rfcs/0004-guest-services.md @@ -132,12 +132,11 @@ share one path, and the SDK gets the same shutdown through its existing ### Docker checkpoint -`scripts/prepare-docker-checkpoint.sh` installs Docker, writes -`/etc/shuru/services/docker.json`, and saves that as an intermediate -checkpoint. It then boots from it, where the service model has already -started dockerd, runs `docker pull` for the pinned image, and saves the -final checkpoint. The intermediate one is deleted. The build itself is the -first consumer of the feature. +The Docker recipe in `superhq-ai/recipes` (RFC 0005) installs Docker and +declares `/etc/shuru/services/docker.json` in its first step. Its second +step boots from that result, where the service model has already started +dockerd, and runs `docker pull` for the pinned image. The build itself is +the first consumer of the feature. The `daemon.json` from RFC 0003 is unchanged. The `with-dockerd` helper is no longer installed. @@ -232,23 +231,25 @@ got-term shuru: services ignored SIGTERM and were killed: stubborn ``` -Docker checkpoint build with the two step script, with dockerd started by -the service model in step two: +Docker checkpoint build from the docker recipe (RFC 0005). The service +file is written in step one, so dockerd is already up when step two pulls: ``` -==> Step 2/2: pulling the image into 'docker' with dockerd running as a service -shuru-guest: service docker ready +shuru: building recipe docker from /docker@dcbbf2c (2 steps) +shuru: step 1/2: install.sh +shuru: checkpoint 'docker-step1' saved +shuru: step 2/2: pull.sh Digest: sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7 -shuru: stopped services: docker -==> Checkpoint 'docker' ready -real 2m6.213s +shuru: checkpoint 'docker' saved +shuru: checkpoint 'docker-step1' deleted +real 2m3.869s ``` RFC 0003 Docker suite, nine tests, against that checkpoint with no `with-dockerd` anywhere: ``` -test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 78.78s +test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 78.79s ``` The same nine tests took 125.51s with the wrapper, because every script diff --git a/scripts/prepare-docker-checkpoint.sh b/scripts/prepare-docker-checkpoint.sh deleted file mode 100755 index 1838818..0000000 --- a/scripts/prepare-docker-checkpoint.sh +++ /dev/null @@ -1,131 +0,0 @@ -#!/bin/bash -# Create a Shuru checkpoint with Docker Engine installed as a guest service -# (RFC 0004) and one pinned image pulled, so -# `shuru run --from docker -- docker run ...` works with networking disabled. -# -# Everything is pinned: Docker apt packages by exact version, the apt signing -# key by SHA-256, the image by manifest digest. The VM that performs the -# install only reaches the hosts listed below. -# -# The build has two steps. The first installs Docker and declares the -# dockerd service, saved as an intermediate checkpoint. The second boots from -# it, which starts dockerd through the service model, pulls the image, and -# saves the final checkpoint. The intermediate checkpoint is then deleted. -# -# Needs a kernel and guest init with container support (RFC 0003). Until a -# release ships them, point SHURU_KERNEL and SHURU_INITRD at a local build. -set -euo pipefail - -SHURU_BIN="${SHURU_BIN:-shuru}" -CHECKPOINT_NAME="${CHECKPOINT_NAME:-docker}" -FROM_CHECKPOINT="${FROM_CHECKPOINT:-}" -DISK_SIZE_MB="${DISK_SIZE_MB:-4096}" -MEMORY_MB="${MEMORY_MB:-2048}" - -DOCKER_VERSION="${DOCKER_VERSION:-5:29.9.2-1~debian.13~trixie}" -CONTAINERD_VERSION="${CONTAINERD_VERSION:-2.4.2-3~debian.13~trixie}" -# Docker Release (CE deb), fingerprint 9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88 -DOCKER_GPG_SHA256="${DOCKER_GPG_SHA256:-1500c1f56fa9e26b9b8f42452a553675796ade0807cdce11975eb98170b3a570}" -# nginxinc/nginx-unprivileged 1.31.7-alpine-slim, multi-arch index digest, -# runs as uid 101 and listens on 8080. -DOCKER_IMAGE="${DOCKER_IMAGE:-nginxinc/nginx-unprivileged:1.31.7-alpine-slim@sha256:a8cb0f33d51fa107c96fd2bd3a71aaf564ec131e9d2bdf8700944f0ed8b170d7}" - -BASE_NAME="${CHECKPOINT_NAME}-base" - -INSTALL_SCRIPT="$(cat << EOF -set -eu -export DEBIAN_FRONTEND=noninteractive -echo "==> Upgrading Debian base (main, security and updates archives)" -cat > /etc/apt/sources.list.d/debian.sources << SRCEOF -Types: deb -URIs: http://deb.debian.org/debian -Suites: trixie trixie-updates -Components: main -Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg - -Types: deb -URIs: http://security.debian.org/debian-security -Suites: trixie-security -Components: main -Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg -SRCEOF -rm -f /etc/apt/sources.list -apt-get update -qq -apt-get upgrade -y -qq --no-install-recommends -echo "==> Adding Docker apt repository (key pinned by SHA-256)" -install -m 0755 -d /etc/apt/keyrings -curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc -echo "${DOCKER_GPG_SHA256} /etc/apt/keyrings/docker.asc" | sha256sum -c - -chmod a+r /etc/apt/keyrings/docker.asc -echo "deb [arch=arm64 signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian trixie stable" > /etc/apt/sources.list.d/docker.list -apt-get update -qq -echo "==> Installing docker-ce ${DOCKER_VERSION}, containerd.io ${CONTAINERD_VERSION}" -apt-get install -y -qq --no-install-recommends \ - "docker-ce=${DOCKER_VERSION}" "docker-ce-cli=${DOCKER_VERSION}" "containerd.io=${CONTAINERD_VERSION}" -apt-mark hold docker-ce docker-ce-cli containerd.io > /dev/null -apt-get clean -rm -rf /var/lib/apt/lists/* -mkdir -p /etc/docker -printf '{\n "no-new-privileges": true\n}\n' > /etc/docker/daemon.json -echo "==> Declaring the dockerd service" -mkdir -p /etc/shuru/services -cat > /etc/shuru/services/docker.json << SVCEOF -{ - "exec": ["dockerd"], - "ready": ["docker", "info"], - "ready_timeout_secs": 60, - "stop_timeout_secs": 30 -} -SVCEOF -cat /etc/shuru/services/docker.json -echo "==> Installed versions" -docker --version -containerd --version -runc --version | head -n 1 -EOF -)" - -PULL_SCRIPT="$(cat << EOF -set -eu -echo "==> Pulling ${DOCKER_IMAGE}" -docker pull "${DOCKER_IMAGE}" -docker image ls --digests -EOF -)" - -ALLOW_ARGS=( - --allow-net - --disk-size "$DISK_SIZE_MB" - --memory "$MEMORY_MB" - --allow-host deb.debian.org - --allow-host security.debian.org - --allow-host download.docker.com - --allow-host "*.docker.io" - --allow-host "*.docker.com" - --allow-host "*.cloudflarestorage.com") -if [ -n "${VERBOSE:-}" ]; then - ALLOW_ARGS+=(--verbose) -fi - -run_checkpoint() { - local name="$1" from="$2" script="$3" - local args=(checkpoint create "$name" "${ALLOW_ARGS[@]}") - if [ -n "$from" ]; then - args+=(--from "$from") - fi - local b64 - b64="$(printf '%s\n' "$script" | base64 | tr -d '\n')" - "$SHURU_BIN" "${args[@]}" -- sh -c "echo ${b64} | base64 -d | sh" -} - -echo "==> Step 1/2: installing Docker ${DOCKER_VERSION} into '${BASE_NAME}'" -run_checkpoint "$BASE_NAME" "$FROM_CHECKPOINT" "$INSTALL_SCRIPT" - -echo "==> Step 2/2: pulling the image into '${CHECKPOINT_NAME}' with dockerd running as a service" -if run_checkpoint "$CHECKPOINT_NAME" "$BASE_NAME" "$PULL_SCRIPT"; then - "$SHURU_BIN" checkpoint delete "$BASE_NAME" - echo "==> Checkpoint '${CHECKPOINT_NAME}' ready" -else - echo "==> Pull failed; intermediate checkpoint '${BASE_NAME}' left in place for debugging" >&2 - exit 1 -fi diff --git a/www/src/components/landing/CliSection.astro b/www/src/components/landing/CliSection.astro index 4d11975..96ecb0e 100644 --- a/www/src/components/landing/CliSection.astro +++ b/www/src/components/landing/CliSection.astro @@ -35,8 +35,8 @@ const tabs = [ }, { id: "docker", - title: "Docker inside", - description: "Run containers in the sandbox. dockerd starts as a guest service and follows the same network rules.", + title: "Recipes & Docker", + description: "Build checkpoints from versioned recipes. The docker recipe runs containers in the sandbox under the same network rules.", }, ]; --- @@ -116,9 +116,13 @@ const tabs = [
-

# One-time: scripts/prepare-docker-checkpoint.sh builds a 'docker' checkpoint

+

$ shuru checkpoint create docker --recipe docker

+

shuru: building recipe docker from superhq-ai/recipes/docker@2a5c726 (2 steps)

+

shuru: checkpoint 'docker' saved

+

$ shuru run --from docker -p 8080:8080 -- docker run --rm -p 8080:8080 nginxinc/nginx-unprivileged:1.31.7-alpine-slim

shuru: forwarding 127.0.0.1:8080 -> guest:8080

+

# Or skip the create: shuru run --recipe docker builds it on first use.


$ curl -sI http://127.0.0.1:8080/ | head -1

HTTP/1.1 200 OK

From 9464cad76c234a2f2faf53abdef2893aa91c1967 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 07:31:01 +0530 Subject: [PATCH 19/57] chore: bump versions for 0.8.0 proto, vm and guest move to 0.4.0 for the shutdown frames and service model, the sdk to 0.5.0 for the new vm and proto, and the lockfile follows the cli at 0.8.0. --- Cargo.lock | 10 +++++----- crates/shuru-guest/Cargo.toml | 2 +- crates/shuru-proto/Cargo.toml | 2 +- crates/shuru-sdk/Cargo.toml | 6 +++--- crates/shuru-vm/Cargo.toml | 4 ++-- 5 files changed, 12 insertions(+), 12 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index ab4a423..607774e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1476,7 +1476,7 @@ checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" [[package]] name = "shuru-cli" -version = "0.7.0" +version = "0.8.0" dependencies = [ "anyhow", "base64", @@ -1512,7 +1512,7 @@ dependencies = [ [[package]] name = "shuru-guest" -version = "0.3.6" +version = "0.4.0" dependencies = [ "flate2", "ignore", @@ -1540,7 +1540,7 @@ dependencies = [ [[package]] name = "shuru-proto" -version = "0.3.3" +version = "0.4.0" dependencies = [ "serde", "serde_json", @@ -1571,7 +1571,7 @@ dependencies = [ [[package]] name = "shuru-sdk" -version = "0.4.0" +version = "0.5.0" dependencies = [ "anyhow", "blake3", @@ -1598,7 +1598,7 @@ dependencies = [ [[package]] name = "shuru-vm" -version = "0.3.8" +version = "0.4.0" dependencies = [ "anyhow", "crossbeam-channel", diff --git a/crates/shuru-guest/Cargo.toml b/crates/shuru-guest/Cargo.toml index 3d82ae5..013b2c2 100644 --- a/crates/shuru-guest/Cargo.toml +++ b/crates/shuru-guest/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "shuru-guest" -version = "0.3.6" +version = "0.4.0" edition = "2021" [[bin]] diff --git a/crates/shuru-proto/Cargo.toml b/crates/shuru-proto/Cargo.toml index d7dc7ff..b04cf6f 100644 --- a/crates/shuru-proto/Cargo.toml +++ b/crates/shuru-proto/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "shuru-proto" -version = "0.3.3" +version = "0.4.0" edition = "2021" description = "Shared wire protocol for shuru host/guest communication" license = "Apache-2.0" diff --git a/crates/shuru-sdk/Cargo.toml b/crates/shuru-sdk/Cargo.toml index 377a37e..fbc8d01 100644 --- a/crates/shuru-sdk/Cargo.toml +++ b/crates/shuru-sdk/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "shuru-sdk" -version = "0.4.0" +version = "0.5.0" edition = "2021" description = "Async Rust SDK for Shuru microVMs" license = "Apache-2.0" @@ -11,8 +11,8 @@ default = [] cas = ["shuru-store", "blake3"] [dependencies] -shuru-vm = { version = "0.3.8", path = "../shuru-vm" } -shuru-proto = { version = "0.3.3", path = "../shuru-proto" } +shuru-vm = { version = "0.4.0", path = "../shuru-vm" } +shuru-proto = { version = "0.4.0", path = "../shuru-proto" } shuru-proxy = { version = "0.3.0", path = "../shuru-proxy" } shuru-store = { version = "0.1.1", path = "../shuru-store", optional = true } tokio = { version = "1", features = ["sync"] } diff --git a/crates/shuru-vm/Cargo.toml b/crates/shuru-vm/Cargo.toml index 4fa7f69..8583ce5 100644 --- a/crates/shuru-vm/Cargo.toml +++ b/crates/shuru-vm/Cargo.toml @@ -1,13 +1,13 @@ [package] name = "shuru-vm" -version = "0.3.8" +version = "0.4.0" edition = "2021" description = "High-level VM management for shuru" license = "Apache-2.0" repository = "https://github.com/superhq-ai/shuru" [dependencies] -shuru-proto = { version = "0.3.3", path = "../shuru-proto" } +shuru-proto = { version = "0.4.0", path = "../shuru-proto" } anyhow = "1" crossbeam-channel = "0.5" serde = { version = "1", features = ["derive"] } From 21bde581878a88725875b65fc37e94890e7533cb Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 07:36:32 +0530 Subject: [PATCH 20/57] cli: checkpoint update shuru checkpoint update NAME takes the same arguments as create and replaces an existing checkpoint, or creates it when missing. The new checkpoint is built under NAME.update and swapped in only when the command exits 0, so a failed update leaves the old one in place. --from NAME layers the command onto the existing checkpoint and --recipe REF rebuilds from a recipe at the current revision. create now points at update instead of asking for a delete. Closes #44 --- CHANGELOG.md | 9 ++ README.md | 7 ++ crates/shuru-cli/src/checkpoint.rs | 60 +++++++++++- crates/shuru-cli/src/cli.rs | 27 ++++++ crates/shuru-cli/src/main.rs | 18 ++++ crates/shuru-cli/src/recipe.rs | 21 +++- crates/shuru-cli/tests/checkpoint_update.rs | 101 ++++++++++++++++++++ crates/shuru-cli/tests/recipes.rs | 30 ++++++ docs/rfcs/0005-recipes.md | 4 + 9 files changed, 275 insertions(+), 2 deletions(-) create mode 100644 crates/shuru-cli/tests/checkpoint_update.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index c050354..fed7165 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,15 @@ this way record their source and revision, visible in `shuru checkpoint list`, and a changed recipe rebuilds on the next run. Third-party recipes ask for confirmation or `--yes`. See docs/rfcs/0005-recipes.md. +### checkpoint update + +`shuru checkpoint update NAME ...` takes the same arguments as `create` and +replaces an existing checkpoint, or creates it when missing. The new +checkpoint is built under a staging name and swapped in only when the +command exits 0, so a failed update leaves the old one in place. +`--from NAME` layers the command onto the existing checkpoint and +`--recipe REF` rebuilds from a recipe. Closes #44. + ### Docker Engine runs inside the VM The `docker` recipe installs pinned docker-ce 29.9.2 and containerd 2.4.2, diff --git a/README.md b/README.md index e7b8611..cf1d847 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,12 @@ shuru run --from myenv -- python3 script.py # Branch from an existing checkpoint shuru checkpoint create myenv2 --from myenv --allow-net -- sh -c 'pip install numpy' +# Rebuild in place: the old checkpoint stays until the new build succeeds +shuru checkpoint update myenv --allow-net -- sh -c 'apt-get install -y python3 gcc make' + +# Or layer onto the existing one +shuru checkpoint update myenv --from myenv --allow-net -- sh -c 'pip install numpy' + # List and delete shuru checkpoint list shuru checkpoint delete myenv @@ -220,6 +226,7 @@ shuru checkpoint create docker --recipe docker # build the checkpoint under shuru run --from docker -- docker ps # and start from it like any other shuru run --recipe docker -- docker ps # or both at once: builds on first use, reuses after shuru checkpoint create mydocker --recipe docker # the same recipe under a name of your own +shuru checkpoint update docker --recipe docker # force a rebuild at the current revision shuru run --recipe owner/repo/path@v1 --yes -- ... # third-party, pinned to a tag shuru run --recipe ./my-recipe -- ... # local directory while developing ``` diff --git a/crates/shuru-cli/src/checkpoint.rs b/crates/shuru-cli/src/checkpoint.rs index f19e5e7..f8b8807 100644 --- a/crates/shuru-cli/src/checkpoint.rs +++ b/crates/shuru-cli/src/checkpoint.rs @@ -40,7 +40,10 @@ pub(crate) fn create_with_config( let checkpoints_dir = format!("{}/checkpoints", data_dir); // Check both formats if checkpoint_exists(&checkpoints_dir, &name) { - bail!("checkpoint '{}' already exists, delete it first", name); + bail!( + "checkpoint '{}' already exists; use `shuru checkpoint update` to replace it", + name + ); } let prepared = vm::prepare_vm(vm_args, cfg, from)?; @@ -63,6 +66,61 @@ pub(crate) fn create_with_config( Ok(result.exit_code) } +/// `shuru checkpoint update NAME`: the new checkpoint is built under a +/// staging name and swapped in once the command succeeds, so a failed build +/// leaves the old checkpoint untouched. `--from NAME` layers the command on +/// top of the existing checkpoint instead of starting from the base image. +pub(crate) fn update( + name: String, + vm_args: &VmArgs, + from: Option<&str>, + command: Vec, +) -> Result { + shuru_vm::validate_checkpoint_name(&name).map_err(|e| anyhow::anyhow!(e))?; + if !exists(&name) { + return create(name, vm_args, from, command); + } + let cfg = load_config(vm_args.config.as_deref())?; + let staging = staging_name(&name); + if exists(&staging) { + delete(&staging)?; + } + let code = create_with_config(staging.clone(), vm_args, &cfg, from, command)?; + if code != 0 { + let _ = delete(&staging); + bail!( + "command exited with status {}, checkpoint '{}' unchanged", + code, + name + ); + } + replace(&name, &staging)?; + Ok(0) +} + +/// Where an update builds before it replaces `name`. +pub(crate) fn staging_name(name: &str) -> String { + format!("{}.update", name) +} + +/// Move the files of `staging` over those of `name`, in either format, +/// including the recipe sidecar. +pub(crate) fn replace(name: &str, staging: &str) -> Result<()> { + let checkpoints_dir = format!("{}/checkpoints", default_data_dir()); + for ext in ["idx", "ext4", "json"] { + let target = format!("{}/{}.{}", checkpoints_dir, name, ext); + let source = format!("{}/{}.{}", checkpoints_dir, staging, ext); + if std::path::Path::new(&target).exists() { + std::fs::remove_file(&target)?; + } + if std::path::Path::new(&source).exists() { + std::fs::rename(&source, &target)?; + } + } + eprintln!("shuru: checkpoint '{}' updated", name); + Ok(()) +} + pub(crate) fn list() -> Result<()> { let data_dir = default_data_dir(); let checkpoints_dir = format!("{}/checkpoints", data_dir); diff --git a/crates/shuru-cli/src/cli.rs b/crates/shuru-cli/src/cli.rs index 054d026..b798db2 100644 --- a/crates/shuru-cli/src/cli.rs +++ b/crates/shuru-cli/src/cli.rs @@ -181,6 +181,33 @@ pub(crate) enum CheckpointCommands { command: Vec, }, + /// Rebuild a checkpoint in place: like delete then create, except the + /// old one stays until the new build succeeds + Update { + /// Checkpoint name + name: String, + + #[command(flatten)] + vm: VmArgs, + + /// Start from an existing checkpoint; NAME itself layers the command on top + #[arg(long)] + from: Option, + + /// Build from a recipe instead of running a command + /// (NAME, OWNER/REPO[/PATH][@REF], or a local directory) + #[arg(long, conflicts_with = "from", value_name = "REF")] + recipe: Option, + + /// Build a third-party recipe without the confirmation prompt + #[arg(long)] + yes: bool, + + /// Command and arguments to run inside the VM + #[arg(trailing_var_arg = true, allow_hyphen_values = true)] + command: Vec, + }, + /// List all checkpoints List, diff --git a/crates/shuru-cli/src/main.rs b/crates/shuru-cli/src/main.rs index dba0084..9b255ff 100644 --- a/crates/shuru-cli/src/main.rs +++ b/crates/shuru-cli/src/main.rs @@ -136,6 +136,24 @@ fn main() -> Result<()> { let exit_code = checkpoint::create(name, &vm, from.as_deref(), command)?; process::exit(exit_code); } + CheckpointCommands::Update { + name, + vm, + from, + recipe, + yes, + command, + } => { + if let Some(ref reference) = recipe { + if !command.is_empty() { + anyhow::bail!("--recipe builds from the recipe steps; drop the command"); + } + recipe::update_checkpoint(&name, reference, &vm, yes)?; + return Ok(()); + } + let exit_code = checkpoint::update(name, &vm, from.as_deref(), command)?; + process::exit(exit_code); + } CheckpointCommands::List => checkpoint::list()?, CheckpointCommands::Delete { name } => checkpoint::delete(&name)?, CheckpointCommands::Push { name: _ } => { diff --git a/crates/shuru-cli/src/recipe.rs b/crates/shuru-cli/src/recipe.rs index 436b72a..adcc4f2 100644 --- a/crates/shuru-cli/src/recipe.rs +++ b/crates/shuru-cli/src/recipe.rs @@ -611,11 +611,30 @@ pub(crate) fn create_checkpoint(name: &str, reference: &str, vm: &VmArgs, yes: b let recipe = resolve(reference)?; confirm(&recipe, yes)?; if checkpoint::exists(name) { - bail!("checkpoint {} already exists, delete it first", name); + bail!( + "checkpoint {} already exists; use `shuru checkpoint update` to replace it", + name + ); } build(name, &recipe, vm) } +/// `shuru checkpoint update NAME --recipe REF`: rebuild even when the +/// revision matches. The old checkpoint stays until the build succeeds. +pub(crate) fn update_checkpoint(name: &str, reference: &str, vm: &VmArgs, yes: bool) -> Result<()> { + let recipe = resolve(reference)?; + confirm(&recipe, yes)?; + if !checkpoint::exists(name) { + return build(name, &recipe, vm); + } + let staging = checkpoint::staging_name(name); + if checkpoint::exists(&staging) { + checkpoint::delete(&staging)?; + } + build(&staging, &recipe, vm)?; + checkpoint::replace(name, &staging) +} + /// `shuru run --recipe REF`: make sure a checkpoint named after the recipe /// exists at the resolved revision, and return its name. pub(crate) fn ensure_checkpoint(reference: &str, vm: &VmArgs, yes: bool) -> Result { diff --git a/crates/shuru-cli/tests/checkpoint_update.rs b/crates/shuru-cli/tests/checkpoint_update.rs new file mode 100644 index 0000000..d2323be --- /dev/null +++ b/crates/shuru-cli/tests/checkpoint_update.rs @@ -0,0 +1,101 @@ +//! `shuru checkpoint update` (issue #44). Every test boots real VMs, so all +//! are #[ignore]d. Run with: +//! +//! SHURU_BIN=target/debug/shuru cargo test -p shuru-cli --test checkpoint_update -- --ignored +//! +//! SHURU_BIN must be a codesigned binary (see tests/docker.rs). SHURU_DATA_DIR, +//! SHURU_KERNEL and SHURU_INITRD are inherited by the CLI. + +use std::process::{Command, Output, Stdio}; + +fn shuru_bin() -> String { + std::env::var("SHURU_BIN") + .expect("SHURU_BIN not set: point it at a codesigned shuru binary (e.g. just build)") +} + +fn text(out: &Output) -> String { + format!( + "--- stdout ---\n{}\n--- stderr ---\n{}", + String::from_utf8_lossy(&out.stdout), + String::from_utf8_lossy(&out.stderr) + ) +} + +fn stdout(out: &Output) -> String { + String::from_utf8_lossy(&out.stdout).to_string() +} + +fn stderr(out: &Output) -> String { + String::from_utf8_lossy(&out.stderr).to_string() +} + +fn shuru(args: &[&str]) -> Output { + let out = Command::new(shuru_bin()) + .args(args) + .stdin(Stdio::null()) + .output() + .expect("failed to spawn shuru"); + eprintln!("$ shuru {}\n{}", args.join(" "), text(&out)); + out +} + +fn unique(prefix: &str) -> String { + format!("{}-{}", prefix, std::process::id()) +} + +struct Cleanup(Vec); + +impl Drop for Cleanup { + fn drop(&mut self) { + for name in &self.0 { + let _ = Command::new(shuru_bin()) + .args(["checkpoint", "delete", name]) + .output(); + } + } +} + +fn files_in(name: &str) -> String { + let out = shuru(&["run", "--from", name, "--", "ls", "/opt/m"]); + assert!(out.status.success(), "{}", text(&out)); + stdout(&out).trim().to_string() +} + +#[test] +#[ignore] +fn update_creates_replaces_layers_and_keeps_the_old_one_on_failure() { + let name = unique("shuru-test-update"); + let _cleanup = Cleanup(vec![name.clone(), format!("{}.update", name)]); + + // Missing checkpoint: update behaves like create. + let out = shuru(&["checkpoint", "update", &name, "--", "sh", "-c", "mkdir -p /opt/m && touch /opt/m/one"]); + assert!(out.status.success(), "{}", text(&out)); + assert!(stderr(&out).contains(&format!("checkpoint '{}' saved", name)), "{}", text(&out)); + assert_eq!(files_in(&name), "one"); + + // Plain update starts from the base image again. + let out = shuru(&["checkpoint", "update", &name, "--", "sh", "-c", "mkdir -p /opt/m && touch /opt/m/two"]); + assert!(out.status.success(), "{}", text(&out)); + assert!(stderr(&out).contains(&format!("checkpoint '{}' updated", name)), "{}", text(&out)); + assert_eq!(files_in(&name), "two"); + + // --from NAME layers the command on top of the existing checkpoint. + let out = shuru(&["checkpoint", "update", &name, "--from", &name, "--", "touch", "/opt/m/three"]); + assert!(out.status.success(), "{}", text(&out)); + assert_eq!(files_in(&name), "three\ntwo"); + + // A failing command leaves the old checkpoint in place and no staging copy. + let out = shuru(&["checkpoint", "update", &name, "--from", &name, "--", "sh", "-c", "touch /opt/m/four; exit 3"]); + assert!(!out.status.success(), "{}", text(&out)); + let e = stderr(&out); + assert!(e.contains("exited with status 3"), "{}", e); + assert!(e.contains(&format!("checkpoint '{}' unchanged", name)), "{}", e); + assert_eq!(files_in(&name), "three\ntwo"); + let list = stdout(&shuru(&["checkpoint", "list"])); + assert!(!list.contains(&format!("{}.update", name)), "{}", list); + + // create still refuses to overwrite and points at update. + let out = shuru(&["checkpoint", "create", &name, "--", "true"]); + assert!(!out.status.success(), "{}", text(&out)); + assert!(stderr(&out).contains("shuru checkpoint update"), "{}", text(&out)); +} diff --git a/crates/shuru-cli/tests/recipes.rs b/crates/shuru-cli/tests/recipes.rs index 6db66b3..0a5327d 100644 --- a/crates/shuru-cli/tests/recipes.rs +++ b/crates/shuru-cli/tests/recipes.rs @@ -220,6 +220,36 @@ fn create_builds_under_a_chosen_name_and_refuses_a_command() { assert!(stderr(&out).contains("already exists"), "{}", text(&out)); } +#[test] +#[ignore] +fn update_rebuilds_a_recipe_checkpoint_at_the_same_revision() { + let name = unique("shuru-test-recipe-update"); + let _cleanup = Cleanup(vec![name.clone(), format!("{}.update", name)]); + let recipe = LocalRecipe::new( + "irrelevant", + r#"{"name": "NAME", "steps": ["build.sh"]}"#, + &[("build.sh", "date +%s%N > /opt/built\n")], + ); + + let out = shuru(&["checkpoint", "create", &name, "--recipe", &recipe.path_str()]); + assert!(out.status.success(), "{}", text(&out)); + let first = stdout(&shuru(&["run", "--from", &name, "--", "cat", "/opt/built"])); + assert!(!first.trim().is_empty(), "{}", first); + + let out = shuru(&["checkpoint", "update", &name, "--recipe", &recipe.path_str()]); + assert!(out.status.success(), "{}", text(&out)); + let e = stderr(&out); + assert!(e.contains("building recipe"), "{}", e); + assert!(e.contains(&format!("checkpoint '{}' updated", name)), "{}", e); + let second = stdout(&shuru(&["run", "--from", &name, "--", "cat", "/opt/built"])); + assert_ne!(first.trim(), second.trim(), "{}", second); + + let list = stdout(&shuru(&["checkpoint", "list"])); + let row = list.lines().find(|l| l.starts_with(&name)).unwrap_or(""); + assert!(row.contains(&recipe.path_str()), "{}", list); + assert!(!list.contains(&format!("{}.update", name)), "{}", list); +} + #[test] #[ignore] fn failing_step_keeps_no_final_checkpoint() { diff --git a/docs/rfcs/0005-recipes.md b/docs/rfcs/0005-recipes.md index bd8e411..c8c1c5b 100644 --- a/docs/rfcs/0005-recipes.md +++ b/docs/rfcs/0005-recipes.md @@ -151,6 +151,10 @@ with the image. - Absent: build. 3. Run the command from that checkpoint with the flags the user gave. +`shuru checkpoint update NAME --recipe REF` forces a rebuild at the current +revision. It builds under `NAME.update` and swaps the files in only when +every step succeeds, so the old checkpoint survives a failed build. + The build and the run are separate phases with separate network policy. The build uses the recipe allowlist. The run uses whatever `--allow-net` and `--allow-host` the user passed, which by default is nothing. From c714f838656510ecbd5cc4431524d900c5137244 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 07:41:26 +0530 Subject: [PATCH 21/57] docs: environment variables in the README SHURU_DATA_DIR, SHURU_KERNEL, SHURU_INITRD, SHURU_ROOTFS, SHURU_STORAGE and SHURU_BOOT_TRACE were undocumented. They are the per-machine layer; permissions stay on flags and in shuru.json. --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index cf1d847..cdb4c67 100644 --- a/README.md +++ b/README.md @@ -162,6 +162,20 @@ Shuru loads `shuru.json` from the current directory (or `--config PATH`). All fi The `network.allow` list restricts which hosts the guest can reach. Omit it to allow all hosts. +### Environment variables + +Per-machine settings live in the environment rather than in `shuru.json`, so +a project file never decides where assets live or how checkpoints are stored +on someone else. None of these can grant a permission; networking, mounts and +host writes stay on flags and in the project file. + +| Variable | Effect | +|---|---| +| `SHURU_DATA_DIR` | Where assets, checkpoints and instance data live. Default `~/.local/share/shuru`. | +| `SHURU_KERNEL`, `SHURU_INITRD`, `SHURU_ROOTFS` | Boot from these files instead of the installed assets. Same as `--kernel`, `--initrd` and `--rootfs`, which win when both are given. | +| `SHURU_STORAGE` | `cas` saves new checkpoints as `.idx` indexes into the chunk store under the data dir. Unset or any other value keeps the default flat `.ext4` copies. A `.idx` checkpoint always boots through the chunk store. | +| `SHURU_BOOT_TRACE` | When set, prints boot timings to stderr. | + ## SDK Use shuru programmatically from TypeScript with the [`@superhq/shuru`](https://www.npmjs.com/package/@superhq/shuru) package. From 415cda134eba9a7dc4a738fe9503c7130b3f027a Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 07:46:34 +0530 Subject: [PATCH 22/57] cli: --checkpoint names the checkpoint run --recipe builds Two recipes that share a name, such as a fork and the official one, would otherwise rebuild over each other on every switch. The flag requires --recipe; the default stays the recipe name. --- README.md | 1 + crates/shuru-cli/src/cli.rs | 4 ++++ crates/shuru-cli/src/main.rs | 8 +++++++- crates/shuru-cli/src/recipe.rs | 16 +++++++++++---- crates/shuru-cli/tests/recipes.rs | 33 +++++++++++++++++++++++++++++++ docs/rfcs/0005-recipes.md | 4 +++- 6 files changed, 60 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index cdb4c67..c1c6da6 100644 --- a/README.md +++ b/README.md @@ -241,6 +241,7 @@ shuru run --from docker -- docker ps # and start from it like any shuru run --recipe docker -- docker ps # or both at once: builds on first use, reuses after shuru checkpoint create mydocker --recipe docker # the same recipe under a name of your own shuru checkpoint update docker --recipe docker # force a rebuild at the current revision +shuru run --recipe docker --checkpoint ci -- ... # the one-liner under a name of your own shuru run --recipe owner/repo/path@v1 --yes -- ... # third-party, pinned to a tag shuru run --recipe ./my-recipe -- ... # local directory while developing ``` diff --git a/crates/shuru-cli/src/cli.rs b/crates/shuru-cli/src/cli.rs index b798db2..a96e3ea 100644 --- a/crates/shuru-cli/src/cli.rs +++ b/crates/shuru-cli/src/cli.rs @@ -96,6 +96,10 @@ pub(crate) enum Commands { #[arg(long)] yes: bool, + /// Name of the checkpoint --recipe builds and reuses (default: the recipe name) + #[arg(long, requires = "recipe", value_name = "NAME")] + checkpoint: Option, + /// Attach to raw serial console instead of running a command #[arg(long)] console: bool, diff --git a/crates/shuru-cli/src/main.rs b/crates/shuru-cli/src/main.rs index 9b255ff..a88ece7 100644 --- a/crates/shuru-cli/src/main.rs +++ b/crates/shuru-cli/src/main.rs @@ -32,6 +32,7 @@ fn main() -> Result<()> { from, recipe, yes, + checkpoint, console, stdio, command, @@ -40,7 +41,12 @@ fn main() -> Result<()> { // A recipe is built (once) before the run, with its own policy. let from = match recipe { - Some(ref reference) => Some(recipe::ensure_checkpoint(reference, &vm, yes)?), + Some(ref reference) => Some(recipe::ensure_checkpoint( + reference, + &vm, + yes, + checkpoint.as_deref(), + )?), None => from, }; diff --git a/crates/shuru-cli/src/recipe.rs b/crates/shuru-cli/src/recipe.rs index adcc4f2..e8b22c8 100644 --- a/crates/shuru-cli/src/recipe.rs +++ b/crates/shuru-cli/src/recipe.rs @@ -635,12 +635,20 @@ pub(crate) fn update_checkpoint(name: &str, reference: &str, vm: &VmArgs, yes: b checkpoint::replace(name, &staging) } -/// `shuru run --recipe REF`: make sure a checkpoint named after the recipe -/// exists at the resolved revision, and return its name. -pub(crate) fn ensure_checkpoint(reference: &str, vm: &VmArgs, yes: bool) -> Result { +/// `shuru run --recipe REF [--checkpoint NAME]`: make sure a checkpoint +/// named after the recipe, or as given, exists at the resolved revision, and +/// return its name. +pub(crate) fn ensure_checkpoint( + reference: &str, + vm: &VmArgs, + yes: bool, + name: Option<&str>, +) -> Result { let recipe = resolve(reference)?; confirm(&recipe, yes)?; - let name = recipe.spec.name.clone(); + let name = name + .map(str::to_string) + .unwrap_or_else(|| recipe.spec.name.clone()); if checkpoint::exists(&name) { match read_meta(&name) { Some(meta) if meta.recipe.revision == recipe.revision => { diff --git a/crates/shuru-cli/tests/recipes.rs b/crates/shuru-cli/tests/recipes.rs index 0a5327d..5b0bf85 100644 --- a/crates/shuru-cli/tests/recipes.rs +++ b/crates/shuru-cli/tests/recipes.rs @@ -193,6 +193,39 @@ fn run_builds_once_reuses_and_rebuilds_when_the_recipe_changes() { assert!(!leftovers.contains(&format!("{}-step1", name)), "{}", leftovers); } +#[test] +fn checkpoint_flag_requires_recipe() { + let out = shuru(&["run", "--checkpoint", "x", "--", "true"]); + assert!(!out.status.success(), "{}", text(&out)); + assert!(stderr(&out).contains("--recipe"), "{}", text(&out)); +} + +#[test] +#[ignore] +fn run_recipe_under_a_chosen_checkpoint_name() { + let name = unique("shuru-test-recipe-named-run"); + let _cleanup = Cleanup(vec![name.clone()]); + let recipe = LocalRecipe::new( + "some-recipe", + r#"{"name": "NAME", "steps": ["build.sh"]}"#, + &[("build.sh", "echo named > /opt/marker\n")], + ); + + let args = ["run", "--recipe", &recipe.path_str(), "--checkpoint", &name, "--", "cat", "/opt/marker"]; + let out = shuru(&args); + assert!(out.status.success(), "{}", text(&out)); + assert!(stderr(&out).contains("building recipe some-recipe"), "{}", text(&out)); + assert!(stdout(&out).contains("named"), "{}", text(&out)); + + let out = shuru(&args); + assert!(out.status.success(), "{}", text(&out)); + assert!(stderr(&out).contains(&format!("using checkpoint {}", name)), "{}", text(&out)); + + let list = stdout(&shuru(&["checkpoint", "list"])); + assert!(list.lines().any(|l| l.starts_with(&name)), "{}", list); + assert!(!list.lines().any(|l| l.starts_with("some-recipe ")), "{}", list); +} + #[test] #[ignore] fn create_builds_under_a_chosen_name_and_refuses_a_command() { diff --git a/docs/rfcs/0005-recipes.md b/docs/rfcs/0005-recipes.md index c8c1c5b..5fe9d27 100644 --- a/docs/rfcs/0005-recipes.md +++ b/docs/rfcs/0005-recipes.md @@ -144,7 +144,9 @@ with the image. ### `shuru run --recipe` 1. Resolve the reference and confirm trust. -2. Look for a checkpoint named after the recipe. +2. Look for a checkpoint named after the recipe, or after `--checkpoint + NAME` when given. The flag keeps two recipes that share a `name`, such + as a fork and the official one, from rebuilding over each other. - Present with a matching revision: reuse it. - Present with a different revision: say so, delete it, rebuild. - Present without a sidecar: refuse, since it is not ours to replace. From 150ba55fc69cb778255d98d05b239c9bc7ae2b90 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 07:46:34 +0530 Subject: [PATCH 23/57] release: tags with a hyphen publish as pre-releases v0.8.0-rc.1 and the like are rehearsals of the workflow: marked pre-release so shuru upgrade and the GitHub latest release ignore them, and the Homebrew tap is left alone. The changelog heading moves from Unreleased to 0.8.0. --- .github/workflows/release.yml | 4 ++++ CHANGELOG.md | 7 ++++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index dafd62e..08ddde7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -127,12 +127,16 @@ jobs: uses: softprops/action-gh-release@v2 with: generate_release_notes: true + # A tag with a hyphen (v0.8.0-rc.1) is a rehearsal: published as a + # pre-release, never marked latest, never pushed to Homebrew. + prerelease: ${{ contains(github.ref_name, '-') }} files: artifacts/* update-homebrew: name: Update Homebrew tap runs-on: ubuntu-latest needs: release + if: ${{ !contains(github.ref_name, '-') }} steps: - uses: actions/checkout@v4 with: diff --git a/CHANGELOG.md b/CHANGELOG.md index fed7165..bbb9d13 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## Unreleased +## 0.8.0 ### Guest services @@ -20,8 +20,9 @@ steps, fetched from GitHub at an exact commit or read from a local path. `shuru recipe list` shows the official catalog in superhq-ai/recipes and `shuru recipe show REF` prints a recipe before it is built. Checkpoints built this way record their source and revision, visible in `shuru checkpoint -list`, and a changed recipe rebuilds on the next run. Third-party recipes -ask for confirmation or `--yes`. See docs/rfcs/0005-recipes.md. +list`, and a changed recipe rebuilds on the next run. `--checkpoint NAME` +on `run` picks the checkpoint name instead of the recipe name. Third-party +recipes ask for confirmation or `--yes`. See docs/rfcs/0005-recipes.md. ### checkpoint update From 9f212525433291c568f3f384d57957145ce51403 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 08:00:25 +0530 Subject: [PATCH 24/57] recipes: a bare name never resolves from the working directory parse_reference probed ./NAME/recipe.json for any reference, so a cloned repository could shadow an official recipe, inherit its trust and run its own steps as root in the build VM without the prompt. Only ./ ../ / ~/ . and .. are local now. A bare name that also exists locally prints a note pointing at ./NAME. Found by the Superagent scan on PR #45. --- crates/shuru-cli/src/recipe.rs | 28 ++++++++++++++++++------- crates/shuru-cli/tests/recipes.rs | 35 +++++++++++++++++++++++++++++++ docs/rfcs/0005-recipes.md | 7 ++++++- 3 files changed, 61 insertions(+), 9 deletions(-) diff --git a/crates/shuru-cli/src/recipe.rs b/crates/shuru-cli/src/recipe.rs index e8b22c8..b69f08f 100644 --- a/crates/shuru-cli/src/recipe.rs +++ b/crates/shuru-cli/src/recipe.rs @@ -109,13 +109,17 @@ struct IndexEntry { // --- Reference parsing --- +/// Only an explicit path form is local. A bare name is never looked up in +/// the working directory: a cloned repository must not be able to shadow +/// an official recipe and inherit its trust. fn parse_reference(reference: &str) -> Result { let looks_local = reference.starts_with("./") || reference.starts_with("../") || reference.starts_with('/') - || reference.starts_with('~') - || reference == "."; - if looks_local || Path::new(reference).join("recipe.json").is_file() { + || reference.starts_with("~/") + || reference == "." + || reference == ".."; + if looks_local { let path = if let Some(rest) = reference.strip_prefix("~/") { let home = std::env::var("HOME").context("HOME is not set")?; PathBuf::from(home).join(rest) @@ -134,11 +138,19 @@ fn parse_reference(reference: &str) -> Result { bail!("invalid recipe reference: {}", reference); } let (owner, repo, path) = match parts.len() { - 1 => ( - OFFICIAL_OWNER.to_string(), - OFFICIAL_REPO.to_string(), - parts[0].to_string(), - ), + 1 => { + if Path::new(parts[0]).join("recipe.json").is_file() { + eprintln!( + "shuru: note: ./{} has a recipe.json, but a bare name means the official catalog; pass ./{} to build the local one", + parts[0], parts[0] + ); + } + ( + OFFICIAL_OWNER.to_string(), + OFFICIAL_REPO.to_string(), + parts[0].to_string(), + ) + } 2 => (parts[0].to_string(), parts[1].to_string(), String::new()), _ => ( parts[0].to_string(), diff --git a/crates/shuru-cli/tests/recipes.rs b/crates/shuru-cli/tests/recipes.rs index 5b0bf85..29767a7 100644 --- a/crates/shuru-cli/tests/recipes.rs +++ b/crates/shuru-cli/tests/recipes.rs @@ -193,6 +193,41 @@ fn run_builds_once_reuses_and_rebuilds_when_the_recipe_changes() { assert!(!leftovers.contains(&format!("{}-step1", name)), "{}", leftovers); } +#[test] +fn bare_name_never_resolves_from_the_working_directory() { + // A cloned repository with NAME/recipe.json must not shadow the official + // recipe of the same name, which would inherit its trust. + let cwd = tempfile::tempdir().unwrap(); + let shadow = cwd.path().join("shadow-test"); + std::fs::create_dir(&shadow).unwrap(); + std::fs::write( + shadow.join("recipe.json"), + r#"{"name": "shadow-test", "description": "local-shadow", "steps": ["evil.sh"]}"#, + ) + .unwrap(); + std::fs::write(shadow.join("evil.sh"), "true\n").unwrap(); + + let out = Command::new(shuru_bin()) + .args(["recipe", "show", "shadow-test"]) + .current_dir(cwd.path()) + .stdin(Stdio::null()) + .output() + .expect("failed to spawn shuru"); + eprintln!("{}", text(&out)); + assert!(!out.status.success(), "{}", text(&out)); + assert!(!stdout(&out).contains("local-shadow"), "{}", text(&out)); + assert!(stderr(&out).contains("pass ./shadow-test"), "{}", text(&out)); + + let out = Command::new(shuru_bin()) + .args(["recipe", "show", "./shadow-test"]) + .current_dir(cwd.path()) + .stdin(Stdio::null()) + .output() + .expect("failed to spawn shuru"); + assert!(out.status.success(), "{}", text(&out)); + assert!(stdout(&out).contains("local-shadow"), "{}", text(&out)); +} + #[test] fn checkpoint_flag_requires_recipe() { let out = shuru(&["run", "--checkpoint", "x", "--", "true"]); diff --git a/docs/rfcs/0005-recipes.md b/docs/rfcs/0005-recipes.md index 5fe9d27..63f0ab9 100644 --- a/docs/rfcs/0005-recipes.md +++ b/docs/rfcs/0005-recipes.md @@ -108,7 +108,12 @@ RFC 0003 script was, so it can use any quoting it likes. It runs with | `owner/repo` | that repository root | | `owner/repo/path/to/dir` | a directory in that repository | | any of the above `@ref` | a branch, tag or commit | -| `./dir`, `/abs/dir`, `../dir` | a local directory | +| `./dir`, `/abs/dir`, `../dir`, `~/dir` | a local directory | + +A bare name is never looked up in the working directory, even when +`./NAME/recipe.json` exists. Otherwise a cloned repository could shadow an +official recipe, inherit its trust and run its own steps without the +prompt. The CLI prints a note pointing at `./NAME` in that case. A GitHub reference is resolved to a commit SHA through the GitHub API before anything is fetched, and the files are then read at that SHA from From 83492811869906e94e4314f776bd1263482f1bcb Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 08:16:22 +0530 Subject: [PATCH 25/57] browser recipe: README, example and gated test The browser recipe in superhq-ai/recipes installs Chromium from Debian and runs it headless as a guest service under an unprivileged user, DevTools on port 9222. The README section and the Browser Use example switch to shuru run --recipe browser, with the example keeping the VM alive instead of launching Chromium as root with --no-sandbox. A gated test builds the recipe and checks CDP inside the VM and through a forwarded host port. --- CHANGELOG.md | 5 ++- README.md | 17 +++++---- crates/shuru-cli/tests/recipes.rs | 59 +++++++++++++++++++++++++++++++ examples/browser-use.py | 24 ++++++------- 4 files changed, 85 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bbb9d13..1795ccc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,7 +22,10 @@ steps, fetched from GitHub at an exact commit or read from a local path. this way record their source and revision, visible in `shuru checkpoint list`, and a changed recipe rebuilds on the next run. `--checkpoint NAME` on `run` picks the checkpoint name instead of the recipe name. Third-party -recipes ask for confirmation or `--yes`. See docs/rfcs/0005-recipes.md. +recipes ask for confirmation or `--yes`. The catalog ships `docker` and +`browser`, headless Chromium as a guest service with the DevTools protocol +on port 9222, which the Browser Use example now uses. See +docs/rfcs/0005-recipes.md. ### checkpoint update diff --git a/README.md b/README.md index c1c6da6..bdc2705 100644 --- a/README.md +++ b/README.md @@ -213,20 +213,23 @@ Once installed, agents will use `shuru run` whenever they need sandboxed executi ## Browser Use -Create a reusable Chromium checkpoint once, then let Browser Use drive that -isolated browser through Shuru's localhost port forwarding: +The `browser` recipe installs Chromium from Debian and runs it headless as a +guest service, under an unprivileged user, with the DevTools protocol on +port 9222 inside the VM. Forward that port and point any CDP client at it: ```sh -shuru checkpoint create browser-use --allow-net -- \ - sh -lc 'apt-get update && apt-get install -y chromium' +shuru run --recipe browser -p 9222:9222 -- sleep infinity +curl -s http://127.0.0.1:9222/json/version +``` + +The Browser Use example does exactly that. Chromium stays inside the +microVM and only its CDP port reaches the host: +```sh OPENAI_API_KEY=... \ uv run --with browser-use --with openai examples/browser-use.py ``` -The example keeps Chromium inside the microVM and exposes only its CDP port to -the host. - ## Recipes A recipe is a versioned description of a checkpoint: a `recipe.json` with diff --git a/crates/shuru-cli/tests/recipes.rs b/crates/shuru-cli/tests/recipes.rs index 29767a7..42a2f48 100644 --- a/crates/shuru-cli/tests/recipes.rs +++ b/crates/shuru-cli/tests/recipes.rs @@ -10,6 +10,9 @@ //! SHURU_DOCKER_RECIPE path to the docker recipe directory from a checkout //! of superhq-ai/recipes; with SHURU_TEST_NET=1 it is //! built for real and runs a container +//! SHURU_BROWSER_RECIPE same for the browser recipe; built for real, then +//! the DevTools endpoint is checked inside the VM and +//! through a forwarded port use std::path::{Path, PathBuf}; use std::process::{Command, Output, Stdio}; @@ -337,6 +340,62 @@ fn failing_step_keeps_no_final_checkpoint() { assert!(!list.lines().any(|l| l.starts_with(&format!("{} ", name))), "{}", list); } +#[test] +#[ignore] +fn browser_recipe_serves_cdp_inside_and_through_a_forwarded_port() { + use std::io::{Read, Write}; + + let Ok(dir) = std::env::var("SHURU_BROWSER_RECIPE") else { + eprintln!("skipped: set SHURU_BROWSER_RECIPE to the browser recipe directory"); + return; + }; + if !std::env::var("SHURU_TEST_NET").map(|v| v == "1").unwrap_or(false) { + eprintln!("skipped: set SHURU_TEST_NET=1"); + return; + } + let name = unique("shuru-test-recipe-browser"); + let _cleanup = Cleanup(vec![name.clone()]); + + let out = shuru(&["checkpoint", "create", &name, "--recipe", &dir]); + assert!(out.status.success(), "{}", text(&out)); + assert!(stderr(&out).contains("step 2/2: check.sh"), "{}", text(&out)); + assert!(stdout(&out).contains("screenshot ok"), "{}", text(&out)); + + // Inside the VM the service is ready before the command runs. + let out = shuru(&["run", "--from", &name, "--", "sh", "-c", "id -un; curl -sf http://127.0.0.1:9222/json/version"]); + assert!(out.status.success(), "{}", text(&out)); + let s = stdout(&out); + assert!(s.contains("Chrome/"), "{}", s); + assert!(s.contains("webSocketDebuggerUrl"), "{}", s); + + // Through -p the host reaches the same endpoint, which is how CDP clients attach. + let port = 19000 + (std::process::id() % 1000) as u16; + let mut child = Command::new(shuru_bin()) + .args(["run", "--from", &name, "-p", &format!("{}:9222", port), "--", "sleep", "30"]) + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .expect("failed to spawn shuru"); + let deadline = std::time::Instant::now() + std::time::Duration::from_secs(20); + let mut body = String::new(); + while std::time::Instant::now() < deadline { + if let Ok(mut stream) = std::net::TcpStream::connect(("127.0.0.1", port)) { + let _ = stream.set_read_timeout(Some(std::time::Duration::from_secs(5))); + let _ = stream.write_all(b"GET /json/version HTTP/1.0\r\nHost: 127.0.0.1\r\n\r\n"); + let _ = stream.read_to_string(&mut body); + if body.contains("Chrome/") { + break; + } + body.clear(); + } + std::thread::sleep(std::time::Duration::from_millis(250)); + } + let _ = child.kill(); + let _ = child.wait(); + assert!(body.contains("Chrome/"), "no CDP answer on host port {}: {:?}", port, body); +} + #[test] #[ignore] fn docker_recipe_builds_and_runs_a_container() { diff --git a/examples/browser-use.py b/examples/browser-use.py index 6a3c950..b27c2ef 100644 --- a/examples/browser-use.py +++ b/examples/browser-use.py @@ -1,4 +1,8 @@ -"""Run a Browser Use agent against Chromium isolated inside Shuru.""" +"""Run a Browser Use agent against Chromium isolated inside Shuru. + +The browser recipe runs headless Chromium as a guest service, so the VM is +ready when the command starts and the only thing to do is keep it alive. +""" import asyncio import os @@ -19,7 +23,9 @@ def free_port() -> int: def wait_for_cdp(url: str, process: subprocess.Popen[bytes]) -> None: - deadline = time.monotonic() + 15 + # The first run builds the browser checkpoint from the recipe, which + # takes a few minutes; later runs answer within seconds. + deadline = time.monotonic() + 600 while time.monotonic() < deadline: if process.poll() is not None: raise RuntimeError(f"Shuru exited with code {process.returncode}") @@ -58,22 +64,16 @@ def main() -> None: [ "shuru", "run", - "--from", - os.getenv("SHURU_BROWSER_CHECKPOINT", "browser-use"), + "--recipe", + os.getenv("SHURU_BROWSER_RECIPE", "browser"), "--allow-net", "--port", f"{host_port}:9222", "--memory", "4096", "--", - "/usr/bin/chromium", - "--headless", - "--no-sandbox", - "--disable-dev-shm-usage", - "--remote-debugging-address=0.0.0.0", - "--remote-debugging-port=9222", - "--user-data-dir=/tmp/browser-use-profile", - "about:blank", + "sleep", + "infinity", ] ) From ef75b2f4dc4b2bb42229ddd91ce954c9b46d3e06 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 08:23:32 +0530 Subject: [PATCH 26/57] tests: the DevTools server ignores HTTP/1.0, ask with HTTP/1.1 --- crates/shuru-cli/tests/recipes.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/crates/shuru-cli/tests/recipes.rs b/crates/shuru-cli/tests/recipes.rs index 42a2f48..4963232 100644 --- a/crates/shuru-cli/tests/recipes.rs +++ b/crates/shuru-cli/tests/recipes.rs @@ -382,7 +382,10 @@ fn browser_recipe_serves_cdp_inside_and_through_a_forwarded_port() { while std::time::Instant::now() < deadline { if let Ok(mut stream) = std::net::TcpStream::connect(("127.0.0.1", port)) { let _ = stream.set_read_timeout(Some(std::time::Duration::from_secs(5))); - let _ = stream.write_all(b"GET /json/version HTTP/1.0\r\nHost: 127.0.0.1\r\n\r\n"); + // The DevTools server ignores HTTP/1.0 requests. + let _ = stream.write_all( + b"GET /json/version HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n", + ); let _ = stream.read_to_string(&mut body); if body.contains("Chrome/") { break; From 74aef5b608032063993c48de78959d8195e5b509 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 08:23:35 +0530 Subject: [PATCH 27/57] www: drop the Hero label and pull the heading up The hero section carried a section label like the ones that sit on the dashed borders further down, but there is no border above it, so the label floated in empty space and the padding that made room for it pushed the heading down. The label and its style block are gone and the top padding now only clears the fixed nav. --- www/src/components/landing/HeroSection.astro | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/www/src/components/landing/HeroSection.astro b/www/src/components/landing/HeroSection.astro index fbb589b..2954470 100644 --- a/www/src/components/landing/HeroSection.astro +++ b/www/src/components/landing/HeroSection.astro @@ -1,6 +1,4 @@ -
- - +

Local-First Sandboxes @@ -32,14 +30,3 @@

- - From 28cc6fff308fa2c77580841a47b9498d04cd7260 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 08:45:29 +0530 Subject: [PATCH 28/57] skill: recipes, guest services, checkpoint update, Docker and browser flows The agent skill predated 0.7.0 and 0.8.0. It now covers run --recipe and checkpoint create --recipe, the bare-name rule for references, --yes for third-party recipes, checkpoint update, the Docker and headless browser patterns, guest services in place of systemd, and experimental Linux hosts. A new references/recipes.md documents the recipe.json fields and the service file contract. --- skills/shuru/SKILL.md | 101 ++++++++++++++++--- skills/shuru/references/checkpoints.md | 47 +++++++-- skills/shuru/references/recipes.md | 132 +++++++++++++++++++++++++ 3 files changed, 261 insertions(+), 19 deletions(-) create mode 100644 skills/shuru/references/recipes.md diff --git a/skills/shuru/SKILL.md b/skills/shuru/SKILL.md index 7361412..6cb55a9 100644 --- a/skills/shuru/SKILL.md +++ b/skills/shuru/SKILL.md @@ -1,15 +1,15 @@ --- name: shuru -description: Run commands in an isolated Linux microVM sandbox using the shuru CLI. Use when the user asks to execute untrusted code, install packages safely, test in a clean environment, or needs Linux-specific tooling on macOS. +description: Run commands in an isolated Linux microVM sandbox using the shuru CLI. Use when the user asks to execute untrusted code, install packages safely, test in a clean environment, run Docker containers or a headless browser inside a VM, or needs Linux-specific tooling on macOS. --- # Sandboxed Execution with Shuru -Shuru boots an ephemeral Linux microVM (Debian, ARM64) on macOS. Each `shuru run` gets a fresh disk clone - all changes are discarded on exit. Use it whenever you need to run commands in isolation from the host. +Shuru boots an ephemeral Linux microVM (Debian, ARM64) on macOS, with experimental support on Linux ARM64 hosts. Each `shuru run` gets a fresh disk clone and all changes are discarded on exit. Use it whenever you need to run commands in isolation from the host. ## Core Workflow -The pattern is: **run in sandbox, mount to share files, checkpoint to persist state**. +The pattern is: **run in sandbox, mount to share files, checkpoint to persist state, recipe for a ready-made environment**. ```bash # 1. Run a command in a fresh VM @@ -24,6 +24,10 @@ shuru run --allow-net -- sh -c 'apt-get install -y curl && curl https://example. # 4. If setup is expensive, save a checkpoint and reuse it shuru checkpoint create node-env --allow-net -- apt-get install -y nodejs npm shuru run --from node-env --mount .:/workspace -- node /workspace/app.js + +# 5. For Docker or a browser, use a recipe from the official catalog +shuru run --recipe docker -- docker run --rm hello-world +shuru run --recipe browser -p 9222:9222 -- sleep infinity ``` ## Command Chaining @@ -60,6 +64,9 @@ shuru run --mount ./src:/src --mount ./data:/data -- ls /src /data # From a checkpoint shuru run --from myenv -- npm test + +# From a recipe: builds the checkpoint on first use, reuses it after +shuru run --recipe docker -- docker ps ``` ### Checkpoints @@ -71,14 +78,47 @@ shuru checkpoint create [flags] [-- command...] # Stack: create from an existing checkpoint shuru checkpoint create with-deps --from base-env --allow-net -- npm install -# List all checkpoints (shows actual disk usage) +# Update: rebuild in place; the old checkpoint stays until the new build succeeds +shuru checkpoint update base-env --allow-net -- apt-get install -y build-essential git + +# Layer onto the existing checkpoint instead of starting over +shuru checkpoint update base-env --from base-env --allow-net -- apt-get install -y jq + +# Build a checkpoint from a recipe +shuru checkpoint create docker --recipe docker + +# List all checkpoints (shows actual disk usage and recipe source) shuru checkpoint list # Delete shuru checkpoint delete ``` -Checkpoint names must be unique - delete the old one before re-creating with the same name. +`create` refuses an existing name. Use `update` to replace a checkpoint; it builds under a staging name and swaps in only when the command exits 0, so a failed update leaves the old one intact. + +### Recipes + +A recipe is a versioned description of a checkpoint: a `recipe.json` plus shell steps, fetched from GitHub at an exact commit or read from a local directory. The official catalog is [superhq-ai/recipes](https://github.com/superhq-ai/recipes) and currently ships `docker` and `browser`. + +```bash +shuru recipe list # the official catalog +shuru recipe show docker # metadata, services and every step, without booting +shuru run --recipe docker -- docker ps # build on first use, reuse after +shuru checkpoint create docker --recipe docker # build explicitly under that name +shuru run --recipe docker --checkpoint ci -- ... # pick the checkpoint name +shuru checkpoint update docker --recipe docker # force a rebuild at the current revision +shuru run --recipe owner/repo/path@v1 --yes -- ... # third-party, pinned to a tag +shuru run --recipe ./my-recipe -- ... # local directory while developing one +``` + +Rules that matter when scripting: + +- A bare name such as `docker` always means the official catalog. A local directory must be written as a path (`./dir`, `../dir`, `/abs`, `~/dir`). +- Official and local recipes build without prompting. Third-party GitHub recipes ask for confirmation, so pass `--yes` in non-interactive runs. +- References resolve to a commit SHA that is recorded next to the checkpoint. A changed recipe rebuilds on the next `run --recipe`; an unchanged one boots the existing checkpoint in seconds. +- Builds use the network allowlist declared by the recipe, never the project `shuru.json`. The first build of `docker` or `browser` takes a few minutes. + +See [references/recipes.md](references/recipes.md) for the `recipe.json` format and guest services. ### Other Commands @@ -108,12 +148,47 @@ shuru checkpoint create python-dev --allow-net -- sh -c 'apt-get install -y pyth shuru run --from python-dev --mount .:/workspace -- sh -c 'cd /workspace && pytest' ``` +### Docker Inside the VM + +The `docker` recipe installs Docker Engine, runs `dockerd` as a guest service, and pre-pulls `nginxinc/nginx-unprivileged:1.31.7-alpine-slim`. The command starts only after `docker info` answers. + +```bash +# Build once (a few minutes), then every run boots in seconds +shuru checkpoint create docker --recipe docker + +# Serve the pre-pulled image on host port 8080; no --allow-net needed +shuru run --from docker -p 8080:8080 -- \ + docker run --rm -p 8080:8080 nginxinc/nginx-unprivileged:1.31.7-alpine-slim + +# Pulling other images needs network +shuru run --from docker --allow-net -- docker run --rm python:3.12-alpine python3 -c 'print(1)' + +# Build an image from a mounted project +shuru run --from docker --mount .:/app -- sh -c 'cd /app && docker build -t app . && docker run --rm app' +``` + +Containers get the same boundary as any guest process: no egress without `--allow-net`, the host allowlist applies, and host ports only open through `-p`. Keep Docker at its defaults inside the VM; do not use `--privileged` or mount the Docker socket. + +### Headless Browser (CDP) + +The `browser` recipe runs Chromium headless as an unprivileged user with the DevTools protocol on port 9222 inside the VM. Forward that port and point any CDP client (Playwright, Puppeteer, browser-use) at `http://127.0.0.1:9222`. + +```bash +# Keep the VM alive while a client on the host drives the browser +shuru run --recipe browser -p 9222:9222 -- sleep infinity + +# In another terminal +curl -s http://127.0.0.1:9222/json/version +``` + +Chromium stays inside the microVM; only its CDP port reaches the host. Add `--allow-net` when the browser must load real websites, and `--allow-host` to restrict which ones. The DevTools HTTP endpoint ignores HTTP/1.0 requests, so use a normal HTTP/1.1 client. + ### Testing Untrusted Code Run untrusted scripts with no network access and no host filesystem access: ```bash -# Fully isolated — no --allow-net, no --mount +# Fully isolated: no --allow-net, no --mount shuru run -- sh -c 'echo "malicious script here" && rm -rf / 2>/dev/null; echo "host is safe"' ``` @@ -176,19 +251,21 @@ Place `shuru.json` in the project root to avoid repeating flags: } ``` -CLI flags override config values. When `secrets` are configured, the guest receives placeholder tokens and the proxy substitutes real values on HTTPS requests to allowed hosts. See [references/config.md](references/config.md) for all fields. +CLI flags override config values. When `secrets` are configured, the guest receives placeholder tokens and the proxy substitutes real values on HTTPS requests to allowed hosts. A secret can also be minted by a `command` and refreshed before it expires. See [references/config.md](references/config.md) for all fields. ## Important Constraints -- **Networking is off by default.** You must pass `--allow-net` to install packages or make HTTP requests. +- **Networking is off by default.** You must pass `--allow-net` to install packages or make HTTP requests. Port forwarding with `-p` works without it. - **The guest is Debian Linux (aarch64).** Use `apt-get install` for packages. - **Ephemeral by default.** Everything is discarded on exit unless you checkpoint. - **Mounts are read-only by default.** Guest writes go to a tmpfs overlay and are discarded on exit. Use `:rw` suffix + `--allow-host-writes` to write to the host. -- **macOS only** (Apple Silicon). Uses Apple Virtualization.framework. +- **No systemd in the guest.** Long-running daemons are declared as guest services (see references/recipes.md); `systemctl` does not exist. +- **Apple Silicon macOS**, plus experimental Linux ARM64 hosts with `/dev/kvm`. - **Default resources:** 2 CPUs, 2048 MB RAM, 4096 MB disk. Override with `--cpus`, `--memory`, `--disk-size`. ## Deep-Dive Documentation -- [references/checkpoints.md](references/checkpoints.md) — checkpoint lifecycle, stacking, disk usage -- [references/config.md](references/config.md) — shuru.json fields and resolution order -- [references/networking.md](references/networking.md) — allow-net, port forwarding, proxy behavior +- [references/checkpoints.md](references/checkpoints.md): checkpoint lifecycle, update, stacking, disk usage +- [references/recipes.md](references/recipes.md): recipe.json format, references, trust, guest services +- [references/config.md](references/config.md): shuru.json fields and resolution order +- [references/networking.md](references/networking.md): allow-net, port forwarding, proxy behavior diff --git a/skills/shuru/references/checkpoints.md b/skills/shuru/references/checkpoints.md index 10cca76..38c1b47 100644 --- a/skills/shuru/references/checkpoints.md +++ b/skills/shuru/references/checkpoints.md @@ -12,6 +12,35 @@ This boots a VM, runs the command (or drops to `/bin/sh` if none given), and sav If `--from` is specified, the VM boots from that checkpoint instead of the base image. +`create` refuses a name that already exists. Use `update` to replace it. + +## Updating a Checkpoint + +```bash +shuru checkpoint update [flags] [-- command...] +``` + +`update` takes the same arguments as `create` and rebuilds the checkpoint in place, or creates it when missing. The new disk is built under a staging name and swapped in only when the command exits 0, so a failed update leaves the old checkpoint untouched and prints that it is unchanged. + +```bash +# Rebuild from the base image +shuru checkpoint update base --allow-net -- apt-get install -y build-essential git make + +# Layer the command onto the existing checkpoint +shuru checkpoint update base --from base --allow-net -- apt-get install -y jq + +# Rebuild a recipe checkpoint at the current recipe revision +shuru checkpoint update docker --recipe docker +``` + +## Building from a Recipe + +```bash +shuru checkpoint create --recipe +``` + +Runs the recipe steps instead of a command, each step in a fresh boot from the previous one. A recipe checkpoint records its source and revision in a sidecar file, and `checkpoint list` shows where it came from. `shuru run --recipe ` builds the same checkpoint on first use under the recipe name (or `--checkpoint `), and rebuilds it when the recipe changes. See [recipes.md](recipes.md). + ## Stacking Checkpoints can be layered. Each layer only stores its diff from the parent: @@ -30,17 +59,21 @@ shuru checkpoint create deps --from node --allow-net --mount .:/app -- sh -c 'cd shuru run --from [flags] [-- command...] ``` -The VM gets a fresh clone of the checkpoint — changes during the run are discarded on exit. +The VM gets a fresh clone of the checkpoint. Changes during the run are discarded on exit. + +If the checkpoint declares guest services (Docker, the browser), they start at boot and the command runs only once their readiness checks pass. They are stopped and the disk synced before the VM powers off. ## Lifecycle -- `checkpoint create` — save disk state -- `checkpoint list` — show all checkpoints with size and age -- `checkpoint delete ` — permanently remove a checkpoint -- Names must be unique. Delete before re-creating with the same name. +- `checkpoint create`: save disk state under a new name +- `checkpoint update`: replace an existing checkpoint, keeping the old one until the new build succeeds +- `checkpoint list`: show all checkpoints with size, age and recipe source +- `checkpoint delete `: permanently remove a checkpoint ## Disk Usage -Checkpoints use APFS clonefile. A fresh checkpoint from a 512MB base image might only use 10-50MB of actual disk space depending on what changed. Use `checkpoint list` to see real usage. +Checkpoints use APFS clonefile. A fresh checkpoint from the base image might only use 10-50MB of actual disk space depending on what changed. Use `checkpoint list` to see real usage. + +`/run`, `/dev/shm` and `/sys/fs/cgroup` are tmpfs inside the guest and are never part of a checkpoint. -If you're running low on disk, delete unused checkpoints with `checkpoint delete`. +If you are running low on disk, delete unused checkpoints with `checkpoint delete`. diff --git a/skills/shuru/references/recipes.md b/skills/shuru/references/recipes.md new file mode 100644 index 0000000..892c19b --- /dev/null +++ b/skills/shuru/references/recipes.md @@ -0,0 +1,132 @@ +# Recipes and Guest Services + +A recipe is a directory with a `recipe.json` and shell steps. Shuru builds it into a checkpoint by running each step in a fresh boot from the previous step, then records the recipe source and revision next to the checkpoint. + +## Commands + +```bash +shuru recipe list # official catalog (github.com/superhq-ai/recipes) +shuru recipe show # metadata, services and every step, without booting +shuru run --recipe [-- command] # build on first use, reuse after, rebuild when the recipe changes +shuru run --recipe --checkpoint -- ... # choose the checkpoint name +shuru checkpoint create --recipe # build explicitly +shuru checkpoint update --recipe # force a rebuild at the current revision +``` + +`--recipe` replaces the command on `checkpoint create` and `update`; passing both is an error. + +## References + +| form | resolves to | +|------|-------------| +| `docker` | the official catalog, directory `docker`, default branch | +| `owner/repo` | that repository root | +| `owner/repo/path/to/dir` | a directory in that repository | +| any of the above `@ref` | a branch, tag or commit | +| `./dir`, `../dir`, `/abs/dir`, `~/dir` | a local directory | + +A bare name never means a local directory, even when one of that name exists in the working directory. Write `./name` for the local one. + +GitHub references resolve to a commit SHA through the GitHub API. Local recipes get a content hash. The resolved revision is printed during the build and stored in `.json` next to the checkpoint, which is what `run --recipe` compares to decide between reuse and rebuild. + +## Trust + +- Official catalog and local paths build without prompting. +- Third-party GitHub recipes print their source and ask for confirmation on a TTY. In scripts and agents pass `--yes`. +- `run --recipe` refuses to replace a checkpoint of the same name that was not built from a recipe. Delete it or pick another name with `--checkpoint`. + +## recipe.json + +```json +{ + "name": "docker", + "description": "Docker Engine 29.9 with dockerd as a guest service and nginx-unprivileged pre-pulled", + "min_shuru_version": "0.8.0", + "disk_size": 4096, + "memory": 2048, + "network": { + "allow": ["deb.debian.org", "security.debian.org", "download.docker.com", "*.docker.io"] + }, + "services": { + "docker": { + "exec": ["dockerd"], + "ready": ["docker", "info"], + "ready_timeout_secs": 60, + "stop_timeout_secs": 30 + } + }, + "steps": ["install.sh", "pull.sh"] +} +``` + +| field | required | meaning | +|-------|----------|---------| +| `name` | yes | default checkpoint name. `[a-z0-9][a-z0-9._-]*` | +| `description` | no | one line for `recipe list` and `recipe show` | +| `min_shuru_version` | no | refuse to build on an older CLI | +| `from` | no | existing checkpoint to start from instead of the base image | +| `cpus`, `memory`, `disk_size` | no | VM size for the build; CLI flags override | +| `network.allow` | no | hosts the build may reach. Absent means the build runs offline. An empty list means unrestricted | +| `services` | no | guest service files, written before the first step runs | +| `steps` | no | scripts run in order, default `["build.sh"]` | + +Builds use the recipe allowlist, never the project `shuru.json`. Every step runs as root in `/bin/sh` from a fresh boot of the previous step, so services declared in `recipe.json` are already running from step 2 onwards. + +## Guest services + +Any image can declare long-running processes in `/etc/shuru/services/.json`. The guest init starts them at boot, waits for the readiness check before running the command, and sends SIGTERM before the VM powers off. There is no systemd in the guest; this is the mechanism for daemons. + +```json +{ + "exec": ["dockerd"], + "ready": ["docker", "info"], + "ready_timeout_secs": 60, + "stop_timeout_secs": 30, + "env": {"HOME": "/root"}, + "cwd": "/" +} +``` + +| field | meaning | +|-------|---------| +| `exec` | argv of the daemon, never passed to a shell | +| `ready` | argv polled until it exits 0; the command waits for it | +| `ready_timeout_secs` | give up and fail the run if `ready` never passes | +| `stop_timeout_secs` | wait this long after SIGTERM before SIGKILL | +| `env` | extra environment for the daemon | +| `cwd` | working directory for the daemon | + +A recipe writes these files for you through its `services` block. A hand-built checkpoint can write them directly during `checkpoint create`. + +## Official recipes + +### docker + +Docker Engine (pinned docker-ce and containerd) with `dockerd` as a guest service and `nginxinc/nginx-unprivileged:1.31.7-alpine-slim` pre-pulled, so `docker run` of that image works offline. Containers reach the internet only through the Shuru proxy with `--allow-net`, host ports only through `-p`. Keep Docker at its defaults inside the VM. + +```bash +shuru run --recipe docker -p 8080:8080 -- \ + docker run --rm -p 8080:8080 nginxinc/nginx-unprivileged:1.31.7-alpine-slim +``` + +### browser + +Chromium from Debian, run headless as the unprivileged `browser` user with the DevTools protocol on port 9222 inside the VM. The service is ready when `/json/version` answers. + +```bash +shuru run --recipe browser -p 9222:9222 -- sleep infinity +curl -s http://127.0.0.1:9222/json/version +``` + +Point Playwright, Puppeteer or browser-use at `http://127.0.0.1:9222`. The DevTools HTTP endpoint ignores HTTP/1.0 requests, so use an HTTP/1.1 client. Add `--allow-net` for real websites and `--allow-host` to restrict them. Use `--memory 4096` for heavy pages. + +## Writing a recipe + +``` +my-recipe/ + recipe.json + install.sh + check.sh +``` + +Pin everything a step installs (package versions, signing keys, image digests) so two people building the recipe get the same checkpoint. Test locally with `shuru run --recipe ./my-recipe -- ...`, and share it from any GitHub repository as `owner/repo/my-recipe@tag`. From 80672bdf7f97209bd25fbcc6cd48bafdd418ca59 Mon Sep 17 00:00:00 2001 From: harshdoesdev Date: Mon, 26 Oct 2026 08:49:15 +0530 Subject: [PATCH 29/57] www: blog index, post layout, RSS feed and the 0.8.0 post Posts are registered in src/data/posts.ts and rendered through a shared BlogPost layout, so the index at /blog, the feed at /rss.xml and every post read the same metadata. The floating Blog label and the duplicated prose styles are gone. Layout.astro now emits a canonical URL and og:url per page. Nav and footer link to /blog and the banner announces 0.8.0. --- www/src/components/landing/Footer.astro | 2 +- www/src/components/landing/Nav.astro | 7 +- www/src/data/posts.ts | 70 +++++ www/src/layouts/BlogPost.astro | 142 +++++++++ www/src/layouts/Layout.astro | 12 +- .../blog/experimental-linux-builds.astro | 136 ++------- www/src/pages/blog/index.astro | 68 +++++ ...xecution-layer-for-autonomous-agents.astro | 272 ++++++------------ ...ecipes-docker-and-a-headless-browser.astro | 227 +++++++++++++++ www/src/pages/rss.xml.ts | 50 ++++ 10 files changed, 690 insertions(+), 296 deletions(-) create mode 100644 www/src/data/posts.ts create mode 100644 www/src/layouts/BlogPost.astro create mode 100644 www/src/pages/blog/index.astro create mode 100644 www/src/pages/blog/recipes-docker-and-a-headless-browser.astro create mode 100644 www/src/pages/rss.xml.ts diff --git a/www/src/components/landing/Footer.astro b/www/src/components/landing/Footer.astro index f500cc6..a53f788 100644 --- a/www/src/components/landing/Footer.astro +++ b/www/src/components/landing/Footer.astro @@ -9,7 +9,7 @@ Linux Blog diff --git a/www/src/components/landing/Nav.astro b/www/src/components/landing/Nav.astro index b1af14f..3996d38 100644 --- a/www/src/components/landing/Nav.astro +++ b/www/src/components/landing/Nav.astro @@ -1,9 +1,9 @@