Skip to content

openvmm: virtiofs: aggregate synthetic root st_nlink counts single-file shares as subdirectories #1632

Open

Description

@tangruize

Summary

On a microVM aggregate mount (VirtioFs::new_microvm_aggregate) configured with one or more single-file child shares (MicroVmAggregateChild::new_file), FUSE_GETATTR and FUSE_STATX on the synthetic root (FUSE_ROOT_ID) report nlink = 2 + entries.len(), counting every attached child regardless of whether it exposes a directory or a regular file. Under POSIX stat(2) directory link-count semantics, a directory's st_nlink is 2 plus one per subdirectory (..), whereas regular-file entries do not increment their parent directory's link count. Found by testing.

Root Cause

In vm/devices/virtio/virtiofs/src/aggregate.rs#L256-L264, VirtioFs::synthetic_root_nlink—used by both synthetic_root_attr and synthetic_root_statx—sums all registered aggregate entries indiscriminately:

    fn synthetic_root_nlink(&self) -> u32 {
        let child_count = self
            .inner
            .aggregate()
            .map_or(0, |aggregate| aggregate.registry.read().entries.len());
        u32::try_from(child_count)
            .unwrap_or(u32::MAX)
            .saturating_add(2)
    }

Meanwhile, plain READDIR in VirtioFs::write_child_entry correctly distinguishes single-file shares (volume.exposed_file().is_some(), emitted as lx::DT_REG) from directory shares (lx::DT_DIR), creating an inconsistency between st_nlink and the directory entries emitted by READDIR / READDIRPLUS.

Consequence

Guest utilities that rely on POSIX directory link-count invariants (such as find, fts, and backup/traversal tools applying the st_nlink - 2 leaf-directory optimization) observe a larger subdirectory count on the mount root than the number of DT_DIR entries actually present when single-file shares are attached.

Reproduction

  1. Construct a microVM aggregate via VirtioFs::new_microvm_aggregate with one directory share (MicroVmAggregateChild::new("work", ...)) and one single-file share (MicroVmAggregateChild::new_file("seed", ...)).
  2. Query Fuse::get_attr(&fs, &request(FUSE_ROOT_ID), 0, 0) and Fuse::get_statx(&fs, &request(FUSE_ROOT_ID), ...).
  3. Observe nlink == 4 instead of 3.

Related: #1617, #1598, #1624.

Activity

  1. tangruize commented on Nov 15, 2026

    @tangruize
    ContributorAuthor

    Suggested Fix

    In VirtioFs::synthetic_root_nlink, count only aggregate entries whose volume exposes a directory (entry.volume.exposed_file().is_none()) before saturatingly adding 2, matching the DT_DIR vs. DT_REG distinction in VirtioFs::write_child_entry.

    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..45d00c942 100644
    --- a/vm/devices/virtio/virtiofs/src/aggregate.rs
    +++ b/vm/devices/virtio/virtiofs/src/aggregate.rs
    @@ -254,10 +254,17 @@ pub(crate) fn synthetic_root_statx(&self, mask: lx::StatExMask) -> fuse_statx {
         }
     
         fn synthetic_root_nlink(&self) -> u32 {
    -        let child_count = self
    -            .inner
    -            .aggregate()
    -            .map_or(0, |aggregate| aggregate.registry.read().entries.len());
    +        let child_count = self.inner.aggregate().map_or(0, |aggregate| {
    +            // Only directory shares contribute a `..` link; single-file shares
    +            // expose a regular file.
    +            aggregate
    +                .registry
    +                .read()
    +                .entries
    +                .iter()
    +                .filter(|entry| entry.volume.exposed_file().is_none())
    +                .count()
    +        });
             u32::try_from(child_count)
                 .unwrap_or(u32::MAX)
                 .saturating_add(2)
    diff --git a/vm/devices/virtio/virtiofs/tests/synthetic_root_nlink.rs b/vm/devices/virtio/virtiofs/tests/synthetic_root_nlink.rs
    new file mode 100644
    index 000000000..5c31f82de
    --- /dev/null
    +++ b/vm/devices/virtio/virtiofs/tests/synthetic_root_nlink.rs
    @@ -0,0 +1,86 @@
    +// Copyright (c) Microsoft Corporation.
    +// Licensed under the MIT License.
    +
    +//! Tests that an aggregate synthetic root directory's link count (`st_nlink`)
    +//! counts `2` plus only directory shares, excluding single-file shares.
    +
    +use fuse::Fuse;
    +use fuse::protocol::FUSE_LOOKUP;
    +use fuse::protocol::FUSE_ROOT_ID;
    +use fuse::protocol::fuse_in_header;
    +use tempfile::tempdir;
    +use test_with_tracing::test;
    +use virtiofs::VirtioFs;
    +use virtiofs::profile::MICROVM_ATTACHMENT_ID;
    +use virtiofs::profile::MicroVmAggregateChild;
    +use virtiofs::profile::MicroVmVirtioFsProfile;
    +use virtiofs::profile::microvm_file_identity;
    +use virtiofs::profile::microvm_root_identity;
    +use zerocopy::IntoBytes;
    +
    +fn request(node_id: u64) -> fuse::Request {
    +    let header = fuse_in_header {
    +        len: size_of::<fuse_in_header>() as u32,
    +        opcode: FUSE_LOOKUP,
    +        unique: 1,
    +        nodeid: node_id,
    +        uid: 0,
    +        gid: 0,
    +        pid: 0,
    +        padding: 0,
    +    };
    +    fuse::Request::new(header.as_bytes()).unwrap()
    +}
    +
    +/// A directory's `st_nlink` is `2` plus one per subdirectory (each
    +/// subdirectory's `..` entry). Single-file shares are regular files (`DT_REG`)
    +/// and do not add a link back to the synthetic root.
    +#[test]
    +fn synthetic_root_link_count_counts_directory_shares() {
    +    let directory = tempdir().unwrap();
    +    let work = directory.path().join("work");
    +    std::fs::create_dir(&work).unwrap();
    +    let seed = directory.path().join("seed.txt");
    +    std::fs::write(&seed, b"seed").unwrap();
    +
    +    let children = vec![
    +        MicroVmAggregateChild::new(
    +            "work".to_owned(),
    +            microvm_root_identity(&work).unwrap(),
    +            false,
    +            Vec::new(),
    +            Vec::new(),
    +            Vec::new(),
    +        )
    +        .unwrap(),
    +        MicroVmAggregateChild::new_file(
    +            "seed".to_owned(),
    +            microvm_file_identity(&seed).unwrap(),
    +            true,
    +        )
    +        .unwrap(),
    +    ];
    +    let profile =
    +        MicroVmVirtioFsProfile::from_aggregate(MICROVM_ATTACHMENT_ID.to_owned(), children).unwrap();
    +    let fs = VirtioFs::new_microvm_aggregate(&[&work, &seed], profile).unwrap();
    +
    +    let attr = Fuse::get_attr(&fs, &request(FUSE_ROOT_ID), 0, 0)
    +        .unwrap()
    +        .attr;
    +    assert_eq!(attr.mode, lx::S_IFDIR | 0o500);
    +    assert_eq!(
    +        attr.nlink, 3,
    +        "synthetic root nlink must be 2 plus directory shares only"
    +    );
    +
    +    let statx = Fuse::get_statx(
    +        &fs,
    +        &request(FUSE_ROOT_ID),
    +        0,
    +        0,
    +        fuse::protocol::StatxFlags::new(),
    +        lx::StatExMask::new().with_nlink(true),
    +    )
    +    .unwrap();
    +    assert_eq!(statx.statx.nlink, 3, "statx nlink must match get_attr");
    +}
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