From 5f5416f2961b00bc00e78be307386434a4d17a1b Mon Sep 17 00:00:00 2001 From: Jason Lenthe Date: Mon, 23 Feb 2026 19:46:22 -0500 Subject: [PATCH] Update VirtualBox guest section * Clarify guest additions package versions * Use sysrc for rc.conf examples * Add VM setup section * Add sub-section headings --- .../books/handbook/virtualization/_index.adoc | 78 +++++++++++++++---- 1 file changed, 62 insertions(+), 16 deletions(-) diff --git a/documentation/content/en/books/handbook/virtualization/_index.adoc b/documentation/content/en/books/handbook/virtualization/_index.adoc index bd9dc390076d..3bb9f3f6e8ae 100644 --- a/documentation/content/en/books/handbook/virtualization/_index.adoc +++ b/documentation/content/en/books/handbook/virtualization/_index.adoc @@ -296,42 +296,85 @@ The virtualization software is available for most common operating systems, incl The VirtualBox(TM) guest additions provide support for: -* Clipboard sharing. -* Mouse pointer integration. -* Host time synchronization. -* Window scaling. -* Seamless mode. +* Clipboard sharing +* Mouse pointer integration +* Host time synchronization +* Window scaling +* Seamless mode + +[[virtualization-virtualbox-vm-setup]] +=== Virtual Machine Setup + +The FreeBSD project provides VM images that have FreeBSD pre-installed. +Files in VHD format can be imported into VirtualBox(TM) media manager and used to create a new VM, avoiding the OS installation process. + +Alternatively, a FreeBSD ISO image can be used as media for the VM's optical drive and the crossref:bsdinstall[bsdinstall,installation process] performed as normal. + +Most VirtualBox(TM) VM defaults are suitable to running FreeBSD. +Memory and CPU resources should be allocated based on the intended workload. +However, consideration should be given to the following values in particular: + +* _Hardware Clock in UTC_ - Select this option, if using host time synchronization. +* _Graphics controller_ - Select `VBoxSVGA`, if running X11. +Warnings that `VBoxSVGA` is not the recommended option may be safely ignored. + +[[virtualization-virtualbox-guest-additions]] +=== Guest Additions Setup + +First, install the package:emulators/virtualbox-ose-additions-72[virtualbox-ose-additions] package that corresponds to the version of VirtualBox(TM) installed on the host machine and whether support for X11 is desired or not, as in the following table. + +[cols="1,2,2", options="header"] +|=== +|VirtualBox(TM) Version | Guest Additions Package (with X11) |Guest Additions Package (without X11) +| 7.2 | package:emulators/virtualbox-ose-additions-72[virtualbox-ose-additions-72] | package:emulators/virtualbox-ose-additions-nox11-72[virtualbox-ose-additions-nox11-72] +| 7.1 | package:emulators/virtualbox-ose-additions-71[virtualbox-ose-additions-71] | package:emulators/virtualbox-ose-additions-nox11-71[virtualbox-ose-additions-nox11-71] +| 7.0 | package:emulators/virtualbox-ose-additions-70[virtualbox-ose-additions-70] | package:emulators/virtualbox-ose-additions-nox11-70[virtualbox-ose-additions-nox11-70] +| 6.1 | package:emulators/virtualbox-ose-additions[virtualbox-ose-additions] | package:emulators/virtualbox-ose-additions-nox11[virtualbox-ose-additions-nox11] +|=== + +Or identify newer versions released after the time of this writing with: + +[source,shell] +.... +# pkg search virtualbox-ose-additions +.... [NOTE] ==== These commands are run in the FreeBSD guest. ==== -First, install the package:emulators/virtualbox-ose-additions[] package or port in the FreeBSD guest. -This will install the port: +As an example, guest additions for VirtualBox(TM) version 7.2 with X11 support are installed with: [source,shell] .... -# cd /usr/ports/emulators/virtualbox-ose-additions && make install clean +# pkg install virtualbox-ose-additions-72 .... -Add these lines to [.filename]#/etc/rc.conf#: +Enable the `vboxguest` and `vboxservice` daemons: -[.programlisting] +[source,shell] .... -vboxguest_enable="YES" -vboxservice_enable="YES" +# sysrc vboxguest_enable="YES" +# sysrc vboxservice_enable="YES" .... If man:ntpd[8] or man:ntpdate[8] is used, disable host time synchronization: -[.programlisting] +[source,shell] .... -vboxservice_flags="--disable-timesync" +# sysrc vboxservice_flags="--disable-timesync" .... -Xorg will automatically recognize the `vboxvideo` driver. -It can also be manually entered in [.filename]#/etc/X11/xorg.conf#: +Restart the guest system for the changes to take effect. + +[[virtualization-virtualbox-x11]] +=== X11 Configuration + +When the `VBoxSVGA` graphics controller is selected for the VM, the `vboxvideo` driver from the guest additions package auto-detects the graphics controller when Xorg starts. +Usually no further configuration is needed. + +These drivers can also be configured manually, if necessary, in [.filename]#/etc/X11/xorg.conf#: [.programlisting] .... @@ -353,6 +396,9 @@ Section "InputDevice" EndSection .... +[[virtualization-virtualbox-shared-folders]] +=== Shared Folders + Shared folders for file transfers between host and VM are accessible by mounting them using `mount_vboxvfs`. A shared folder can be created on the host using the VirtualBox GUI or via `vboxmanage`. For example, to create a shared folder called _myshare_ under [.filename]#/mnt/bsdboxshare# for the VM named _BSDBox_, run: