Skip to content

openvmm: virtiofs: HandleMap::can_insert hands out u64::MAX, colliding with SYNTHETIC_ROOT_FH #1627

Open

Description

@tangruize

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 $2^{64} - 2$ handles is impractical during a single fresh boot, 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

  1. Construct let mut handles = HandleMap::starting_at(u64::MAX); (or restore a microVM virtio-fs state whose next_handle_id is u64::MAX and open a file or directory).
  2. Call handles.insert("last") (or FUSE_OPEN on a child file in an aggregate share): HandleMap returns Some(u64::MAX) (SYNTHETIC_ROOT_FH) instead of None (ENOSPC).
  3. In an aggregate share where a child file holds fh = u64::MAX, issuing FUSE_RELEASE on (FUSE_ROOT_ID, SYNTHETIC_ROOT_FH) removes the child's VirtioFsFile from self.inner.files, and saving microVM state while fh = u64::MAX remains open produces next_handle_id = 0, which validate_microvm_state rejects on restore.

Related: #1624, #1633.

Activity

  1. tangruize commented on Nov 15, 2026

    @tangruize
    ContributorAuthor

    Suggested Fix

    Update HandleMap::can_insert in vm/devices/virtio/virtiofs/src/lib.rs to require self.next_handle != 0 && self.next_handle != u64::MAX && !self.values.contains_key(&self.next_handle) so HandleMap treats u64::MAX as exhausted and never allocates SYNTHETIC_ROOT_FH, and update the SYNTHETIC_ROOT_FH documentation and HandleMap boundary unit tests accordingly.

    Patch against OpenVMM 9d64daad3cbe14fb0591081b73c6c9648e18d0fb. Save the contents below as fix.patch and run git apply fix.patch.

    fix.patch
    diff --git a/vm/devices/virtio/virtiofs/src/aggregate.rs b/vm/devices/virtio/virtiofs/src/aggregate.rs
    index 5b9694132..bbf05e91f 100644
    --- a/vm/devices/virtio/virtiofs/src/aggregate.rs
    +++ b/vm/devices/virtio/virtiofs/src/aggregate.rs
    @@ -27,7 +27,8 @@
     /// 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.
    +/// handle: `HandleMap` allocates from 1 upward and never hands out
    +/// `u64::MAX` (`HandleMap::can_insert`).
     pub(crate) const SYNTHETIC_ROOT_FH: u64 = u64::MAX;
     
     /// A single host folder exposed as a named child of the synthetic aggregate root.
    diff --git a/vm/devices/virtio/virtiofs/src/lib.rs b/vm/devices/virtio/virtiofs/src/lib.rs
    index 71780f585..be2285dda 100644
    --- a/vm/devices/virtio/virtiofs/src/lib.rs
    +++ b/vm/devices/virtio/virtiofs/src/lib.rs
    @@ -1015,8 +1015,14 @@ fn is_current(&self, reservation: &HandleReservation) -> bool {
             Arc::ptr_eq(&self.generation, &reservation.generation)
         }
     
    +    /// Whether the next handle may be handed out. `u64::MAX` never is: it is
    +    /// the aggregate root's own handle (`aggregate::SYNTHETIC_ROOT_FH`), so a
    +    /// table that reaches it is full. (A restored table starts above every
    +    /// saved handle, so it never holds `u64::MAX` either.)
         pub fn can_insert(&self) -> bool {
    -        self.next_handle != 0 && !self.values.contains_key(&self.next_handle)
    +        self.next_handle != 0
    +            && self.next_handle != u64::MAX
    +            && !self.values.contains_key(&self.next_handle)
         }
     
         /// Retrieves a value from the map.
    @@ -1693,8 +1699,8 @@ fn plain_readdir_revalidates_sandbox_ancestors() {
         fn unused_reservations_release_on_drop() {
             let root = tempfile::tempdir().unwrap();
             let fs = VirtioFs::new(root.path(), None).unwrap();
    -        fs.inner.files.write().next_handle = u64::MAX;
    -        fs.inner.inodes.write().inodes_by_node_id.next_handle = u64::MAX;
    +        fs.inner.files.write().next_handle = u64::MAX - 1;
    +        fs.inner.inodes.write().inodes_by_node_id.next_handle = u64::MAX - 1;
     
             let file = fs.reserve_file().unwrap();
             let inode = fs.reserve_inode().unwrap();
    @@ -1703,8 +1709,8 @@ fn unused_reservations_release_on_drop() {
             drop(file);
             drop(inode);
     
    -        assert_eq!(fs.reserve_file().unwrap().reservation.handle, u64::MAX);
    -        assert_eq!(fs.reserve_inode().unwrap().reservation.handle, u64::MAX);
    +        assert_eq!(fs.reserve_file().unwrap().reservation.handle, u64::MAX - 1);
    +        assert_eq!(fs.reserve_inode().unwrap().reservation.handle, u64::MAX - 1);
         }
     
         #[test]
    @@ -1764,7 +1770,7 @@ fn create_releases_inode_when_file_reservation_fails() {
             let root = tempfile::tempdir().unwrap();
             let fs = VirtioFs::new(root.path(), None).unwrap();
             fs.inner.files.write().next_handle = 0;
    -        fs.inner.inodes.write().inodes_by_node_id.next_handle = u64::MAX;
    +        fs.inner.inodes.write().inodes_by_node_id.next_handle = u64::MAX - 1;
     
             let result = fs.create(
                 &request(FUSE_ROOT_ID),
    @@ -1774,7 +1780,7 @@ fn create_releases_inode_when_file_reservation_fails() {
     
             assert!(matches!(result, Err(lx::Error::ENOSPC)));
             assert!(!root.path().join("file").exists());
    -        assert_eq!(fs.reserve_inode().unwrap().reservation.handle, u64::MAX);
    +        assert_eq!(fs.reserve_inode().unwrap().reservation.handle, u64::MAX - 1);
         }
     
         #[test]
    @@ -1782,8 +1788,8 @@ fn create_releases_both_reservations_on_host_failure() {
             let root = tempfile::tempdir().unwrap();
             std::fs::write(root.path().join("file"), b"original").unwrap();
             let fs = VirtioFs::new(root.path(), None).unwrap();
    -        fs.inner.files.write().next_handle = u64::MAX;
    -        fs.inner.inodes.write().inodes_by_node_id.next_handle = u64::MAX;
    +        fs.inner.files.write().next_handle = u64::MAX - 1;
    +        fs.inner.inodes.write().inodes_by_node_id.next_handle = u64::MAX - 1;
     
             let result = fs.create(
                 &request(FUSE_ROOT_ID),
    @@ -1800,8 +1806,8 @@ fn create_releases_both_reservations_on_host_failure() {
                 std::fs::read(root.path().join("file")).unwrap(),
                 b"original"
             );
    -        assert_eq!(fs.reserve_file().unwrap().reservation.handle, u64::MAX);
    -        assert_eq!(fs.reserve_inode().unwrap().reservation.handle, u64::MAX);
    +        assert_eq!(fs.reserve_file().unwrap().reservation.handle, u64::MAX - 1);
    +        assert_eq!(fs.reserve_inode().unwrap().reservation.handle, u64::MAX - 1);
         }
     
         #[test]
    @@ -1814,7 +1820,7 @@ fn deduplicated_inode_releases_unused_reservation() {
                 .lookup_child(lx::LxStr::from_bytes(b"file"))
                 .unwrap();
             let (existing, node_id) = fs.insert_inode(inode).unwrap();
    -        fs.inner.inodes.write().inodes_by_node_id.next_handle = u64::MAX;
    +        fs.inner.inodes.write().inodes_by_node_id.next_handle = u64::MAX - 1;
     
             let reservation = fs.reserve_inode().unwrap();
             let (inode, _) = root_inode
    @@ -1824,7 +1830,7 @@ fn deduplicated_inode_releases_unused_reservation() {
     
             assert!(Arc::ptr_eq(&existing, &reused));
             assert_eq!(reused_node_id, node_id);
    -        assert_eq!(fs.reserve_inode().unwrap().reservation.handle, u64::MAX);
    +        assert_eq!(fs.reserve_inode().unwrap().reservation.handle, u64::MAX - 1);
         }
     
         #[test]
    @@ -1940,11 +1946,17 @@ fn inode_reservation_does_not_survive_destroy() {
     
         #[test]
         fn handle_map_stops_after_max_handle() {
    -        let mut handles = HandleMap::starting_at(u64::MAX);
    +        // `u64::MAX` is the aggregate root's own handle, never handed out.
    +        let mut handles = HandleMap::starting_at(u64::MAX - 1);
     
    -        assert_eq!(handles.insert("last"), Some(u64::MAX));
    -        assert_eq!(handles.get(u64::MAX), Some(&"last"));
    +        assert_eq!(handles.insert("last"), Some(u64::MAX - 1));
    +        assert_eq!(handles.get(u64::MAX - 1), Some(&"last"));
             assert_eq!(handles.insert("overflow"), None);
    +        assert_eq!(handles.reserve().map(|r| r.handle), None);
    +
    +        let mut handles = HandleMap::<&str>::starting_at(u64::MAX);
    +        assert_eq!(handles.insert("reserved"), None);
    +        assert_eq!(handles.get(u64::MAX), None);
         }
     
         #[test]
    @@ -1983,11 +1995,11 @@ fn handle_map_ignores_stale_reservation_release() {
     
         #[test]
         fn handle_map_reuses_latest_released_reservation() {
    -        let mut handles = HandleMap::starting_at(u64::MAX);
    +        let mut handles = HandleMap::starting_at(u64::MAX - 1);
     
             let reservation = handles.reserve().unwrap();
    -        assert_eq!(reservation.handle, u64::MAX);
    +        assert_eq!(reservation.handle, u64::MAX - 1);
             handles.release_reservation(&reservation);
    -        assert_eq!(handles.insert("last"), Some(u64::MAX));
    +        assert_eq!(handles.insert("last"), Some(u64::MAX - 1));
         }
     }
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: openvmmInitial title-keyword triage suggestion

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions