Repository navigation
Description
Summary
aggregate::SYNTHETIC_ROOT_FH reserves u64::MAX as the sentinel directory handle returned when opening the synthetic aggregate root (FUSE_ROOT_ID), assuming HandleMap never allocates u64::MAX to a real file or directory. However, HandleMap::can_insert only rejects next_handle == 0 and explicitly allows allocating u64::MAX before wrapping next_handle to 0, creating a handle-ID collision between a real open handle in self.inner.files and the synthetic aggregate root sentinel (as well as making a microVM state with an open u64::MAX handle unsaveable/unrestorable). Found during formal specification (blocks formal verification).
Root Cause
aggregate.rs defines SYNTHETIC_ROOT_FH = u64::MAX on the assumption that u64::MAX cannot collide with a HandleMap entry:
/// Reserved file handle `open_dir` returns for the synthetic aggregate root;
/// `read_dir`/`read_dir_plus`/`release_dir` recognize it and serve the root
/// registry instead of the handle map. `u64::MAX` can't collide with a real
/// handle, since `HandleMap` allocates from 1 upward.
pub(crate) const SYNTHETIC_ROOT_FH: u64 = u64::MAX;In HandleMap, however, can_insert only checks self.next_handle != 0, so insert and reserve hand out u64::MAX and only afterward set self.next_handle = handle.checked_add(1).unwrap_or(0):
pub fn can_insert(&self) -> bool {
self.next_handle != 0 && !self.values.contains_key(&self.next_handle)
}Although sequentially exhausting validate_microvm_state accepts a saved state with next_handle_id = u64::MAX (and next_node_id = u64::MAX) whenever largest_handle_id < u64::MAX, and restore_microvm_state initializes HandleMap::starting_at(state.next_handle_id), immediately arming the very next open, open_dir, or create to allocate fh = u64::MAX.
Consequence
Once HandleMap allocates fh = u64::MAX for a real file or directory in an aggregate share, u64::MAX simultaneously identifies both that real VirtioFsFile in self.inner.files and the synthetic aggregate root sentinel (SYNTHETIC_ROOT_FH). Any read_dir, read_dir_plus, or release_dir issued with nodeid = FUSE_ROOT_ID and fh = u64::MAX is intercepted by is_synthetic_root_handle and never reaches or releases self.inner.files[&u64::MAX], whereas operations that do not check is_synthetic_root_handle (such as read, write, fsync, flush, or release) issued against (FUSE_ROOT_ID, SYNTHETIC_ROOT_FH) unexpectedly resolve self.inner.files[&u64::MAX] and read, mutate, or close the real child's handle. Furthermore, in microVM mode, if a guest keeps handle u64::MAX open when the VM is saved, save_microvm_state emits a SavedHandle with handle_id = u64::MAX and next_handle_id = 0, which subsequently fails validate_microvm_state (state.next_handle_id != 0 and state.next_handle_id > largest_handle_id), breaking VM restore.
Reproduction
- Construct
let mut handles = HandleMap::starting_at(u64::MAX);(or restore a microVM virtio-fs state whosenext_handle_idisu64::MAXand open a file or directory). - Call
handles.insert("last")(orFUSE_OPENon a child file in an aggregate share):HandleMapreturnsSome(u64::MAX)(SYNTHETIC_ROOT_FH) instead ofNone(ENOSPC). - In an aggregate share where a child file holds
fh = u64::MAX, issuingFUSE_RELEASEon(FUSE_ROOT_ID, SYNTHETIC_ROOT_FH)removes the child'sVirtioFsFilefromself.inner.files, and saving microVM state whilefh = u64::MAXremains open producesnext_handle_id = 0, whichvalidate_microvm_staterejects on restore.
Activity
tangruize commentedon Nov 15, 2026
Suggested Fix
Update
HandleMap::can_insertinvm/devices/virtio/virtiofs/src/lib.rsto requireself.next_handle != 0 && self.next_handle != u64::MAX && !self.values.contains_key(&self.next_handle)soHandleMaptreatsu64::MAXas exhausted and never allocatesSYNTHETIC_ROOT_FH, and update theSYNTHETIC_ROOT_FHdocumentation andHandleMapboundary unit tests accordingly.Patch against OpenVMM
9d64daad3cbe14fb0591081b73c6c9648e18d0fb. Save the contents below asfix.patchand rungit apply fix.patch.fix.patch