P9FS(4)

🌸 NAME 🌸

p9fs — 9P file system 💾✨

hiii bestie, welcome to the p9fs(4) page from the Kernel Interfaces Manual — yes, that manual, and this page is about p9fs, the 9P file system. it’s giving host filesystem but make it virtual 🎀🦋

---

🛠️ SYNOPSIS 🛠️

okay so to use this filesystem, pick a route, bestie:

• add the following to the kernel config:

options P9FS
device virtio_p9fs

• alternatively, load the driver as a kernel module, either at boot time by adding the following to loader.conf(5):

virtio_p9fs_load="YES"

• or on system startup using the command:

# sysrc kld_list+=virtio_p9fs

---

🌈 DESCRIPTION 🌈

The p9fs filesystem uses the 9P protocol to mount a host file system directory into a bhyve(8) guest. Multiple host directories can be accessed using the bhyve(8) virtio-9p virtual PCI device. Each device is configured with a share name and a host directory path. The share name can be used with mount(8) to mount the host directory in the guest:

# mount -t p9fs mysharename /mnt

Host directories can be mounted on system startup using fstab(5) like this:

mysharename     /mnt    p9fs    rw      0       0

Using p9fs as a root file system is supported by adding the following to loader.conf(5):

vfs.root.mountfrom="p9fs:mysharename"

---

⚠️ LIMITATIONS ⚠️

real talk, bestie — the 9P protocol relies on stateful file opens which map protocol-level FIDs to host file descriptors. The FreeBSD vnode interface doesn’t support this, and p9fs uses heuristics to guess the right FID to use for file operations. guessy, not guaranteed 😭

This can be confused by privilege lowering and does not guarantee that the FID created for a given file open is always used, even if the calling process is using the file descriptor from the original open call.

In particular, accessing unlinked files using open file descriptor may not work correctly. If p9fs is the root filesystem, it is recommended to use with tmpfs(5) to ensure that temporary files created in /tmp or /var/tmp have the expected semantics.

🚨 bestie please don’t skip the tmpfs(5) part if p9fs is your root filesystem — that’s the recommendation for getting expected semantics for temp files in /tmp or /var/tmp 😭💖

---

🔗 SEE ALSO 🔗

• fstab(5) — that’s the SEE ALSO reference, and it’s serving 💅

---

📜 HISTORY 📜

The 9P protocol first appeared in the Plan 9 operating system. More recently, the protocol has been widely used with virtual machines to allow the use of host file resources inside a guest VM. iconic lineage, no cap 🌟

---

👑 AUTHORS 👑

This is derived from software released by Juniper Networks, Inc. with many improvements and fixes from Steve Wills. slay 🫶

This manual page was written by Doug Rabson <dfr@FreeBSD.org>. 💌

---

💀 BUGS 💀

A better name for this filesystem would be 9pfs but for technical reasons, the names of filesystems must be valid C identifiers. As a compromise, the filesystem is named p9fs. not me crying over naming rules 😭 but rules are rules, and p9fs ate 💅

Later bestie — this page is from Debian, dated November 7, 2024, and it’s the P9FS(4) manual page 🫶💖