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