1 files changed, 127 insertions, 0 deletions
diff --git a/share/man/man4/p9fs.4 b/share/man/man4/p9fs.4
new file mode 100644
index 000000000000..04f27abd2545
--- /dev/null
+++ b/share/man/man4/p9fs.4
@@ -0,0 +1,127 @@
+.\"
+.\" Copyright (c) 2022-present Doug Rabson
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd November 7, 2024
+.Dt P9FS 4
+.Os
+.Sh NAME
+.Nm p9fs
+.Nd "9P file system"
+.Sh SYNOPSIS
+To use this filesystem,
+either add the following to the kernel config:
+.Bd -ragged -offset indent
+.Cd "options P9FS"
+.Cd "device virtio_p9fs"
+.Ed
+.Pp
+Alternatively, load the driver as a kernel module,
+either at boot time by adding the following to
+.Xr loader.conf 5 :
+.Bd -literal -offset indent
+virtio_p9fs_load="YES"
+.Ed
+.Pp
+or on system startup using the command:
+.Pp
+.Dl "# sysrc kld_list+=virtio_p9fs"
+.Sh DESCRIPTION
+The
+.Nm
+filesystem uses the 9P protocol to mount a host file system directory
+into a
+.Xr bhyve 8
+guest.
+Multiple host directories can be accessed using the
+.Xr 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
+.Xr mount 8
+to mount the host directory in the guest:
+.Pp
+.Dl "# mount -t p9fs mysharename /mnt"
+.Pp
+Host directories can be mounted on system startup using
+.Xr fstab 5
+like this:
+.Pp
+.Bd -literal -offset indent
+mysharename	/mnt	p9fs	rw	0	0
+.Ed
+.Pp
+Using
+.Nm
+as a root file system is supported by adding the following to
+.Xr loader.conf 5 :
+.Bd -literal -offset indent
+vfs.root.mountfrom="p9fs:mysharename"
+.Ed
+.Sh LIMITATIONS
+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
+.Nm
+uses heuristics to guess the right FID to use for file operations.
+.Pp
+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.
+.Pp
+In particular, accessing unlinked files using open file descriptor
+may not work correctly.
+If
+.Nm
+is the root filesystem,
+it is recommented to use with
+.Xr tmpfs 5
+to ensure that temporary files created in
+.Pa /tmp
+or
+.Pa /var/tmp
+have the expected semantics.
+.Sh SEE ALSO
+.Xr fstab 5
+.Sh 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.
+.Sh AUTHORS
+This is derived from software released by Juniper Networks, Inc.
+with many improvements and fixes from
+.An Steve Wills .
+.Pp
+This manual page was written by
+.An -nosplit
+.An Doug Rabson Aq Mt dfr@FreeBSD.org .
+.Sh BUGS
+A better name for this filesystem would be
+.Ar 9pfs
+but for technical reasons,
+the names of filesystems must be valid C identifiers.
+As a compromise,
+the filesystem is named
+.Nm .