feat(snapshot): persist+restore virtio-fs inode map (fixes exec EBADF on restored guest)

ROOT CAUSE (workflow-confirmed via FUSE errno trace 'do_getattr MAP-MISS inode=1 ->
EBADF, map has 0 inodes'): the host virtio-fs PassthroughFs is rebuilt fresh on
restore with an EMPTY inode map. The root inode (nodeid=1) is only inserted by the
FUSE_INIT handler, which the restored (already-mounted) guest never re-sends — so every
rootfs op the guest makes (execve reading /bin/sh) resolves a cached nodeid the host
has forgotten and returns EBADF, surfacing as 'Failed to spawn command sh: Bad file
descriptor'.

Fix: serialize the inode map (nodeid -> host path, recovered via readlink(/proc/self/fd/N)
on the live O_PATH fds while the template is paused-but-alive) and rehydrate it on
restore by reopening each path under its original nodeid. Plumbing: VirtioDevice gains
save_device_state/restore_device_state (opaque blob); Fs shares its PassthroughFs with
the worker via Arc (Server now holds Arc<F>) so the device can snapshot it; the blob
rides MmioDeviceState through the snapshot state and is reapplied after activate()
before vCPUs run. Open file handles deferred (a fresh exec opens its own). macOS/Windows
stubs no-op.

Author: RoyLin

src/devices/src/virtio/device.rs

@@ -81,6 +81,18 @@ pub trait VirtioDevice: AsAny + Send {
         self.queues().iter().map(Queue::save_state).collect()
     }
 
+    /// Snapshot device-internal state that is NOT in the virtqueues, as an opaque
+    /// blob (snapshot-fork). Defaults to `None`. virtio-fs overrides this to persist
+    /// its FUSE inode map (nodeid → path), without which a restored guest's cached
+    /// nodeids all resolve to EBADF against the freshly-built, empty host inode map.
+    fn save_device_state(&self) -> Option<Vec<u8>> {
+        None
+    }
+
+    /// Re-apply device-internal state captured by [`save_device_state`]. Called on
+    /// restore after `activate()` and before the vCPUs run. Default no-op.
+    fn restore_device_state(&mut self, _blob: &[u8]) {}
+
     /// Returns the device queues event fds.
     fn queue_events(&self) -> &[EventFd];
 

src/devices/src/virtio/fs/device.rs

@@ -15,7 +15,8 @@ use virtio_bindings::{virtio_config::VIRTIO_F_VERSION_1, virtio_ring::VIRTIO_RIN
 use vm_memory::{ByteValued, GuestMemoryMmap};
 
 use super::super::{
-    ActivateResult, DeviceState, FsError, Queue as VirtQueue, VirtioDevice, VirtioShmRegion,
+    ActivateError, ActivateResult, DeviceState, FsError, Queue as VirtQueue, VirtioDevice,
+    VirtioShmRegion,
 };
 use super::passthrough;
 use super::worker::FsWorker;
@@ -72,6 +73,10 @@ pub struct Fs {
     config: VirtioFsConfig,
     shm_region: Option<VirtioShmRegion>,
     passthrough_cfg: passthrough::Config,
+    // The live FUSE filesystem, shared with the worker thread (via the Server) so
+    // this device can snapshot/restore its inode map for snapshot-fork. `Some` once
+    // activated.
+    passthrough_fs: Option<Arc<passthrough::PassthroughFs>>,
     worker_thread: Option<JoinHandle<()>>,
     worker_stopfd: EventFd,
     exit_code: Arc<AtomicI32>,
@@ -115,6 +120,7 @@ impl Fs {
             config,
             shm_region: None,
             passthrough_cfg: fs_cfg,
+            passthrough_fs: None,
             worker_thread: None,
             worker_stopfd: EventFd::new(EFD_NONBLOCK).map_err(FsError::EventFd)?,
             exit_code,
@@ -192,6 +198,16 @@ impl VirtioDevice for Fs {
         &self.queue_events
     }
 
+    fn save_device_state(&self) -> Option<Vec<u8>> {
+        self.passthrough_fs.as_ref().map(|fs| fs.save_fs_state())
+    }
+
+    fn restore_device_state(&mut self, blob: &[u8]) {
+        if let Some(fs) = self.passthrough_fs.as_ref() {
+            fs.restore_fs_state(blob);
+        }
+    }
+
     fn read_config(&self, offset: u64, mut data: &mut [u8]) {
         let config_slice = self.config.as_slice();
         let config_len = config_slice.len() as u64;
@@ -230,13 +246,21 @@ impl VirtioDevice for Fs {
             .iter()
             .map(|e| e.try_clone().unwrap())
             .collect();
+        // Build the FUSE filesystem and keep a shared handle so this device can
+        // snapshot/restore its inode map (the worker thread otherwise owns it).
+        let passthrough_fs = Arc::new(
+            passthrough::PassthroughFs::new(self.passthrough_cfg.clone())
+                .map_err(|_| ActivateError::BadActivate)?,
+        );
+        self.passthrough_fs = Some(passthrough_fs.clone());
+
         let worker = FsWorker::new(
             self.queues.clone(),
             queue_evts,
             interrupt.clone(),
             mem.clone(),
             self.shm_region.clone(),
-            self.passthrough_cfg.clone(),
+            passthrough_fs,
             self.worker_stopfd.try_clone().unwrap(),
             self.exit_code.clone(),
             #[cfg(target_os = "macos")]

src/devices/src/virtio/fs/linux/passthrough.rs

@@ -417,6 +417,113 @@ impl PassthroughFs {
         })
     }
 
+    /// Snapshot the FUSE inode namespace (nodeid → host path) for snapshot-fork.
+    ///
+    /// Each `InodeData.file` is a live `O_PATH` fd, so while the template VMM is
+    /// paused-but-alive its absolute path is recoverable via
+    /// `readlink(/proc/self/fd/N)`. The opaque blob is consumed by
+    /// [`restore_fs_state`](Self::restore_fs_state) on the forked VM to rebuild the
+    /// same nodeids, so the restored guest's cached nodeids resolve instead of all
+    /// hitting EBADF against an empty inode map.
+    pub fn save_fs_state(&self) -> Vec<u8> {
+        use std::os::unix::ffi::OsStrExt;
+        let inodes = self.inodes.read().unwrap();
+        let mut out = Vec::new();
+        out.extend_from_slice(&self.next_inode.load(Ordering::Relaxed).to_le_bytes());
+        out.extend_from_slice(&self.next_handle.load(Ordering::Relaxed).to_le_bytes());
+        let count_pos = out.len();
+        out.extend_from_slice(&0u64.to_le_bytes());
+        let mut count: u64 = 0;
+        for (nodeid, data) in inodes.iter() {
+            let link = format!("/proc/self/fd/{}", data.file.as_raw_fd());
+            let path = match std::fs::read_link(&link) {
+                Ok(p) => p,
+                Err(_) => continue,
+            };
+            let path_bytes = path.as_os_str().as_bytes();
+            // Unlinked-but-open files read back as "<path> (deleted)" and cannot be
+            // reopened by path; skip them — the guest will re-LOOKUP if needed.
+            if path_bytes.ends_with(b" (deleted)") || path_bytes.contains(&0) {
+                continue;
+            }
+            out.extend_from_slice(&(*nodeid).to_le_bytes());
+            out.extend_from_slice(&data.refcount.load(Ordering::Relaxed).to_le_bytes());
+            out.extend_from_slice(&(path_bytes.len() as u32).to_le_bytes());
+            out.extend_from_slice(path_bytes);
+            count += 1;
+        }
+        out[count_pos..count_pos + 8].copy_from_slice(&count.to_le_bytes());
+        out
+    }
+
+    /// Rebuild the inode map from a [`save_fs_state`](Self::save_fs_state) blob by
+    /// reopening each path under its original nodeid. Runs on restore after the fs
+    /// device is rebuilt and before the vCPUs resume.
+    pub fn restore_fs_state(&self, blob: &[u8]) {
+        if blob.len() < 24 {
+            return;
+        }
+        let rd = |o: usize| u64::from_le_bytes(blob[o..o + 8].try_into().unwrap());
+        let next_inode = rd(0);
+        let next_handle = rd(8);
+        let count = rd(16);
+        let mut off = 24usize;
+        let mut inodes = self.inodes.write().unwrap();
+        for _ in 0..count {
+            if off + 20 > blob.len() {
+                break;
+            }
+            let nodeid = rd(off);
+            off += 8;
+            let refcount = rd(off);
+            off += 8;
+            let plen = u32::from_le_bytes(blob[off..off + 4].try_into().unwrap()) as usize;
+            off += 4;
+            if off + plen > blob.len() {
+                break;
+            }
+            let path = &blob[off..off + plen];
+            off += plen;
+            let cpath = match CString::new(path) {
+                Ok(c) => c,
+                Err(_) => continue,
+            };
+            let fd = unsafe {
+                libc::openat(
+                    libc::AT_FDCWD,
+                    cpath.as_ptr(),
+                    libc::O_PATH | libc::O_NOFOLLOW | libc::O_CLOEXEC,
+                )
+            };
+            if fd < 0 {
+                continue;
+            }
+            // Safe because we just opened this fd.
+            let f = unsafe { File::from_raw_fd(fd) };
+            let (st, mnt_id) = match statx(&f) {
+                Ok(v) => v,
+                Err(_) => continue,
+            };
+            inodes.insert(
+                nodeid,
+                InodeAltKey {
+                    ino: st.st_ino,
+                    dev: st.st_dev,
+                    mnt_id,
+                },
+                Arc::new(InodeData {
+                    inode: nodeid,
+                    file: f,
+                    dev: st.st_dev,
+                    mnt_id,
+                    refcount: AtomicU64::new(refcount),
+                }),
+            );
+        }
+        self.next_inode.store(next_inode, Ordering::Relaxed);
+        self.next_handle.store(next_handle, Ordering::Relaxed);
+    }
+
     fn open_inode(&self, inode: Inode, mut flags: i32) -> io::Result<File> {
         let data = self
             .inodes

src/devices/src/virtio/fs/macos/passthrough.rs

@@ -444,6 +444,15 @@ pub struct PassthroughFs {
 }
 
 impl PassthroughFs {
+    /// Snapshot-fork inode-map persistence is Linux-only (depends on
+    /// `/proc/self/fd`); a no-op on macOS.
+    pub fn save_fs_state(&self) -> Vec<u8> {
+        Vec::new()
+    }
+
+    /// Snapshot-fork inode-map persistence is Linux-only; a no-op on macOS.
+    pub fn restore_fs_state(&self, _blob: &[u8]) {}
+
     pub fn new(cfg: Config) -> io::Result<PassthroughFs> {
         let mut cfg = cfg;
 

src/devices/src/virtio/fs/multikey.rs

@@ -47,6 +47,12 @@ where
         self.main.get(key).map(|(_, v)| v)
     }
 
+    /// Iterate over `(main_key, value)` pairs. Used to walk the inode map when
+    /// snapshotting virtio-fs state.
+    pub fn iter(&self) -> impl Iterator<Item = (&K1, &V)> {
+        self.main.iter().map(|(k, (_, v))| (k, v))
+    }
+
     /// Returns a reference to the value corresponding to the alternate key.
     ///
     /// The key may be any borrowed form of the `K2``, but the ordering on the borrowed form must

src/devices/src/virtio/fs/server.rs

@@ -92,12 +92,15 @@ impl io::Write for ZCWriter<'_> {
 }
 
 pub struct Server<F: FileSystem + Sync> {
-    fs: F,
+    // Shared with the owning device so it can snapshot/restore the filesystem's
+    // inode map (the worker thread that holds this Server is otherwise the only
+    // owner of the live FUSE namespace).
+    fs: std::sync::Arc<F>,
     options: AtomicU64,
 }
 
 impl<F: FileSystem + Sync> Server<F> {
-    pub fn new(fs: F) -> Server<F> {
+    pub fn new(fs: std::sync::Arc<F>) -> Server<F> {
         Server {
             fs,
             options: AtomicU64::new(FsOptions::empty().bits()),

src/devices/src/virtio/fs/windows/passthrough.rs

@@ -157,6 +157,14 @@ pub struct PassthroughFs {
 }
 
 impl PassthroughFs {
+    /// Snapshot-fork inode-map persistence is Linux-only; a no-op on Windows.
+    pub fn save_fs_state(&self) -> Vec<u8> {
+        Vec::new()
+    }
+
+    /// Snapshot-fork inode-map persistence is Linux-only; a no-op on Windows.
+    pub fn restore_fs_state(&self, _blob: &[u8]) {}
+
     pub fn new(cfg: Config) -> io::Result<PassthroughFs> {
         let root_dir = PathBuf::from(&cfg.root_dir);
         virtiofs_debug_log(format!("PassthroughFs::new root_dir={}", root_dir.display()));

src/devices/src/virtio/fs/worker.rs

@@ -65,7 +65,7 @@ impl FsWorker {
         interrupt: InterruptTransport,
         mem: GuestMemoryMmap,
         shm_region: Option<VirtioShmRegion>,
-        passthrough_cfg: passthrough::Config,
+        passthrough_fs: Arc<PassthroughFs>,
         stop_fd: EventFd,
         exit_code: Arc<AtomicI32>,
         #[cfg(target_os = "macos")] map_sender: Option<Sender<WorkerMessage>>,
@@ -76,7 +76,7 @@ impl FsWorker {
             interrupt,
             mem,
             shm_region,
-            server: Server::new(PassthroughFs::new(passthrough_cfg).unwrap()),
+            server: Server::new(passthrough_fs),
             stop_fd,
             exit_code,
             #[cfg(target_os = "macos")]

src/devices/src/virtio/mmio.rs

@@ -106,6 +106,8 @@ pub struct MmioDeviceState {
     pub config_generation: u32,
     pub acked_features: u64,
     pub queues: Vec<QueueState>,
+    /// Opaque device-internal state (e.g. virtio-fs inode map). Empty if none.
+    pub device_blob: Vec<u8>,
 }
 
 pub struct MmioTransport {
@@ -309,6 +311,7 @@ impl MmioTransport {
             config_generation: self.config_generation,
             acked_features: dev.acked_features(),
             queues,
+            device_blob: dev.save_device_state().unwrap_or_default(),
         }
     }
 
@@ -344,6 +347,15 @@ impl MmioTransport {
                 })?;
             activated = true;
         }
+
+        // Rehydrate device-internal state (e.g. the virtio-fs inode map) AFTER
+        // activate() has rebuilt the device's shared backend, and before the vCPUs
+        // run so the guest's first FUSE op finds a populated map.
+        if !state.device_blob.is_empty() {
+            self.locked_device()
+                .restore_device_state(&state.device_blob);
+        }
+
         self.device_status = state.device_status;
         Ok(activated)
     }

src/vmm/src/snapshot.rs

@@ -121,6 +121,8 @@ pub struct MmioDeviceStateSer {
     pub config_generation: u32,
     pub acked_features: u64,
     pub queues: Vec<QueueStateSer>,
+    #[serde(default)]
+    pub device_blob: Vec<u8>,
 }
 
 #[cfg(all(target_os = "linux", target_arch = "x86_64"))]
@@ -135,6 +137,7 @@ impl From<&devices::virtio::MmioDeviceState> for MmioDeviceStateSer {
             config_generation: d.config_generation,
             acked_features: d.acked_features,
             queues: d.queues.iter().map(QueueStateSer::from).collect(),
+            device_blob: d.device_blob.clone(),
         }
     }
 }
@@ -151,6 +154,7 @@ impl From<&MmioDeviceStateSer> for devices::virtio::MmioDeviceState {
             config_generation: d.config_generation,
             acked_features: d.acked_features,
             queues: d.queues.iter().map(devices::virtio::QueueState::from).collect(),
+            device_blob: d.device_blob.clone(),
         }
     }
 }