.\"
.\" 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 .