git: d26c8ae527bb - main - vmm.4: Add information on VM access control

The branch main has been updated by markj:

URL: https://cgit.FreeBSD.org/src/commit/?id=d26c8ae527bbf2cc3da98c0857f634f162622752

commit d26c8ae527bbf2cc3da98c0857f634f162622752
Author:     Mark Johnston <markj@FreeBSD.org>
AuthorDate: 2026-02-19 14:38:59 +0000
Commit:     Mark Johnston <markj@FreeBSD.org>
CommitDate: 2026-02-19 17:16:15 +0000

    vmm.4: Add information on VM access control
    
    Add a section to vmm.4 explaining how vmm device file ownership works.
    
    MFC after:      2 months
    Sponsored by:   The FreeBSD Foundation
    Sponsored by:   Klara, Inc.
    Differential Revision:  https://reviews.freebsd.org/D54742
---
 share/man/man4/vmm.4   | 39 +++++++++++++++++++++++++++++++++++++++
 usr.sbin/bhyve/bhyve.8 | 25 ++++++++++++++++++++-----
 2 files changed, 59 insertions(+), 5 deletions(-)

diff --git a/share/man/man4/vmm.4 b/share/man/man4/vmm.4
index 07c40541f404..9c16bff8398a 100644
--- a/share/man/man4/vmm.4
+++ b/share/man/man4/vmm.4
@@ -59,6 +59,29 @@ riscv: The CPUs must implement the H (hypervisor) RISC-V ISA extension.
 .Pp
 PCI device passthrough to a virtual machine requires
 hardware with VT-d support and is available only on amd64.
+.Sh ACCESS CONTROL
+Only the super-user and processes with write access to the
+.Pa /dev/vmmctl
+device file may create and destroy virtual machines.
+By default, members of the
+.Va vmm
+group have such access.
+Once created, a virtual machine may be destroyed only by that user or
+the super-user.
+.Pp
+Unprivileged users must use
+.Dq monitor mode
+to run the virtual machine; in this mode, the virtual machine is automatically
+destroyed when its device file is closed.
+When running
+.Xr bhyve 8 ,
+this mode can be selected by specifying the
+.Fl M
+flag.
+.Pp
+Virtual machines can be created in a jail if the jail has the
+.Va allow.vmm
+flag set.
 .Sh PCI PASSTHROUGH
 On amd64 where the hardware supports VT-d,
 PCI devices can be reserved for use by the hypervisor.
@@ -99,6 +122,12 @@ The
 and
 .Va pptdevs3
 variables can be used for additional entries.
+.Pp
+In general, PCI passthrough cannot be used when running
+.Xr bhyve 8
+as an unprivileged user or in a jail, as this feature requires write
+access to
+.Pa /dev/pci .
 .Sh LOADER TUNABLES
 Tunables can be set at the
 .Xr loader 8
@@ -109,6 +138,14 @@ prompt before booting the kernel or stored in
 Maximum number of virtual CPUs.
 The default is the number of physical CPUs in the system.
 .El
+.Sh FILES
+.Bl -tag -width /dev/vmmctl -compact
+.It Pa /dev/vmmctl
+control interface for creating and destroying virtual machines.
+.It Pa /dev/vmm/*
+device interface for individual virtual machines.
+.It Pa /dev/vmm.io/*
+device interface for device memory mapped into virtual machines.
 .Sh EXAMPLES
 Reserve three PCI devices for use by the hypervisor: bus 10 slot 0 function 0,
 bus 6 slot 5 function 0, and bus 6 slot 5 function 1.
@@ -143,8 +180,10 @@ back:
 .Xr bhyve 4 ,
 .Xr loader.conf 5 ,
 .Xr bhyve 8 ,
+.Xr bhyvectl 8 ,
 .Xr bhyveload 8 ,
 .Xr devctl 8 ,
+.Xr jail 8 ,
 .Xr kldload 8
 .Sh HISTORY
 .Nm vmm.ko
diff --git a/usr.sbin/bhyve/bhyve.8 b/usr.sbin/bhyve/bhyve.8
index 4c73a119b1ed..be906419d74e 100644
--- a/usr.sbin/bhyve/bhyve.8
+++ b/usr.sbin/bhyve/bhyve.8
@@ -25,7 +25,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd January 5, 2026
+.Dd January 23, 2026
 .Dt BHYVE 8
 .Os
 .Sh NAME
@@ -117,8 +117,23 @@ on arm64 the
 package provides a U-Boot image that can be used to boot the guest.
 .Pp
 .Nm
-runs until the guest operating system reboots or an unhandled hypervisor
-exit is detected.
+runs until the guest operating system reboots (if
+.Ql monitor
+mode is not enabled) or halts, or an unhandled hypervisor exit is
+detected.
+.Pp
+Generally
+.Nm
+must be run by the super-user, but users belonging to the
+.Va vmm
+group can create and run virtual machines as well.
+See
+.Xr vmm 4 .
+When run by an unprivileged user,
+.Nm
+must have access to any required resources such as disk images or
+network devices.
+PCI passthrough cannot be used by unprivileged users.
 .Sh OPTIONS
 .Bl -tag -width 10n
 .It Fl a
@@ -605,8 +620,8 @@ addressing rules.
 The
 .Cm slirp
 backend can be used to provide a NATed network to the guest.
-This backend has poor performance but does not require any network
-configuration on the host system.
+This backend has limited performance but does not require any network
+configuration on the host system and can be used by unprivileged users.
 It depends on the
 .Pa net/libslirp
 port.