1.\" 2.\" Copyright (c) 2022-present Doug Rabson 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.Dd November 7, 2024 26.Dt P9FS 4 27.Os 28.Sh NAME 29.Nm p9fs 30.Nd "9P file system" 31.Sh SYNOPSIS 32To use this filesystem, 33either add the following to the kernel config: 34.Bd -ragged -offset indent 35.Cd "options P9FS" 36.Cd "device virtio_p9fs" 37.Ed 38.Pp 39Alternatively, load the driver as a kernel module, 40either at boot time by adding the following to 41.Xr loader.conf 5 : 42.Bd -literal -offset indent 43virtio_p9fs_load="YES" 44.Ed 45.Pp 46or on system startup using the command: 47.Pp 48.Dl "# sysrc kld_list+=virtio_p9fs" 49.Sh DESCRIPTION 50The 51.Nm 52filesystem uses the 9P protocol to mount a host file system directory 53into a 54.Xr bhyve 8 55guest. 56Multiple host directories can be accessed using the 57.Xr bhyve 8 58virtio-9p virtual PCI device. 59Each device is configured with a share name and a host directory path. 60The share name can be used with 61.Xr mount 8 62to mount the host directory in the guest: 63.Pp 64.Dl "# mount -t p9fs mysharename /mnt" 65.Pp 66Host directories can be mounted on system startup using 67.Xr fstab 5 68like this: 69.Pp 70.Bd -literal -offset indent 71mysharename /mnt p9fs rw 0 0 72.Ed 73.Pp 74Using 75.Nm 76as a root file system is supported by adding the following to 77.Xr loader.conf 5 : 78.Bd -literal -offset indent 79vfs.root.mountfrom="p9fs:mysharename" 80.Ed 81.Sh LIMITATIONS 82The 9P protocol relies on stateful file opens 83which map protocol-level FIDs to host file descriptors. 84The FreeBSD vnode interface doesn't support this and 85.Nm 86uses heuristics to guess the right FID to use for file operations. 87.Pp 88This can be confused by privilege lowering and 89does not guarantee that the FID created for a 90given file open is always used, 91even if the calling process is using the file descriptor from 92the original open call. 93.Pp 94In particular, accessing unlinked files using open file descriptor 95may not work correctly. 96If 97.Nm 98is the root filesystem, 99it is recommented to use with 100.Xr tmpfs 5 101to ensure that temporary files created in 102.Pa /tmp 103or 104.Pa /var/tmp 105have the expected semantics. 106.Sh SEE ALSO 107.Xr fstab 5 108.Sh HISTORY 109The 9P protocol first appeared in the Plan 9 operating system. 110More recently, the protocol has been widely used with virtual machines 111to allow the use of host file resources inside a guest VM. 112.Sh AUTHORS 113This is derived from software released by Juniper Networks, Inc. 114with many improvements and fixes from 115.An Steve Wills . 116.Pp 117This manual page was written by 118.An -nosplit 119.An Doug Rabson Aq Mt dfr@FreeBSD.org . 120.Sh BUGS 121A better name for this filesystem would be 122.Ar 9pfs 123but for technical reasons, 124the names of filesystems must be valid C identifiers. 125As a compromise, 126the filesystem is named 127.Nm . 128