docs: mounting into a VM guest

[pi0x]

Serve a driver on the host, mount it inside a VM with one command and nothing installed in the guest. New page at /guide/vms, slotted in after Mounting.

The guide index already described 9P as serving "the local kernel, or a VM guest" — this is that page.

QEMU → 9P

The recipe is three commands, and the reason it is that short is worth stating: QEMU's default user-mode networking already routes 10.0.2.2 to the host's loopback. So there is no tap device, no bridge, no host-side ip command and no root on the host, and the server stays bound to 127.0.0.1 where nothing on the network can reach it.

mount -t 9p -o trans=tcp,port=5640,version=9p2000.L 10.0.2.2 /mnt/x

Verified end to end against a stock Alpine 3.21.3 virt guest (kernel 6.12.13-0-virt) driven over the serial console:

• mounts with those three options and no modprobe — mount -t 9p autoloads v9fs/9pnet_fd
• ls, read, write, mkdir -p, 16 MiB dd both directions, mv across directories, rm, df -T, umount
• the mount table shows no msize=, which is the same proof-by-omission the local-mount notes already rely on; asking for msize=1048576 makes it appear
• the minimal guest-side network setup is one line, since the host is on-link — no default route needed for the mount

The page also separates this from QEMU's own -virtfs, which exports a host directory through QEMU's built-in 9P server. Every -fsdev backend is directory-based (-fsdev sock,… → fsdriver sock not found), so there is no way to point virtio-9p at an external server — TCP is genuinely the route, not a fallback.

Firecracker → NFSv4.1

Firecracker cannot do 9P, for two independent reasons, and the page says so plainly rather than offering a recipe that cannot work:

• it emulates only virtio-net/block/vsock (plus balloon and rng) — there is no virtio-9p device
• its published guest kernels ship # CONFIG_NET_9P is not set

What those kernels do carry is CONFIG_NFS_V4=y / CONFIG_NFS_V4_1=y and # CONFIG_NFS_V3 is not set — so the transport is NFSv4.1 specifically, the half that landed in #7.

NFSv4.1 now has a real kernel client

AGENTS.md listed NFSv4.1 as having no real-client verification, for want of a mount.nfs on this host. A VM guest supplies one. The same server was mounted vers=4.1 from a real Linux kernel NFSv4.1 client and passed the same workload — mount, read, write, mkdir, 16 MiB dd, rename, unlink, unmount — with no rpcbind and no MOUNT program involved. AGENTS.md is amended accordingly.

This is still not a Tier-2 test column: the host itself has no mount.nfs, so a v4.1 mount test would have to carry a VM, which is a bigger decision than this PR.

Not verified, and marked as such

The Firecracker tap wiring has not been exercised end to end — this container has no /dev/net/tun, and every Firecracker network is a tap device. The kernel-config and device facts are read from Firecracker's own published kernels and docs, and the NFSv4.1 mount itself was verified from a QEMU guest (which needs no tap). The page carries a note saying exactly this, and it can come out once the run happens.

Notes

• No perf numbers published — that stays restricted to .agents/benchmarks.md.
• Guide pages renumbered to slot the new one after Mounting; URLs are unaffected, since the numeric prefix is routing-only. Confirmed against the built output: tuning and troubleshooting are unchanged and vms is new.
• .agents/environment.md records the reproduction details, including the two container limits that shaped this (/dev/kvm needs sudo here; /dev/net/tun is absent).
• pnpm test: 58 files passed / 4 skipped, 2779 tests passed. Docs site builds clean (22 pages).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
mountx	Ready	Preview	Jul 29, 2026 11:51pm

[pi0x]

Firecracker is verified now — and it needs less than the page claimed

A real Firecracker v1.16.1 microVM (guest kernel 6.1.102, their own ubuntu-22.04 root image) mounted this NFSv4.1 server and passed the same workload as the QEMU columns: ls, read, write, mkdir -p, 16 MiB dd both directions, rename, unlink, umount.

172.20.0.1:/ /mnt/x nfs4 rw,relatime,vers=4.1,rsize=1047672,wsize=1047532,namlen=255,hard,
proto=tcp,timeo=600,retrans=2,sec=sys,clientaddr=172.20.0.2,local_lock=none,addr=172.20.0.1 0 0

The "not witnessed" note is gone, and the section now carries the tap setup, a complete vm.json and the mount that was actually run.

Two findings that changed the page

No nfs-common in the guest. which mount.nfs mount.nfs4 finds nothing in Firecracker's root image, and the mount works anyway — with addr= and clientaddr= given explicitly there is nothing left for the helper to resolve, so mount(8) falls through to the mount(2) syscall. That is the difference between "rebuild your image" and "nothing to install", so the page now spells both options out on purpose rather than incidentally.

The guest needs no network commands at all, given an ip= kernel boot argument — the kernel configures eth0 before userspace starts.

On the container restart

Not needed in the end. /dev/net/tun is present, but CAP_NET_ADMIN is still absent from the bounding set (CapEff: 00000000a82425fb decodes to cap_sys_admin + cap_net_raw, no cap_net_admin), so ip tuntap add answers ioctl(TUNSETIFF): Operation not permitted even under sudo.

A new user namespace grants a full capability set (000001ffffffffff) over the network namespace it owns, so the tap, the mountx server and the VM all run inside one unshare -Urn --map-root-user and the guest never touches the container's real network. Recorded in .agents/environment.md along with the two gotchas (--map-root-user is required, and assets must live outside the drwx------ session scratchpad).

pnpm test: 58 files passed / 4 skipped, 2780 passed. Docs build clean.