# 20.4 在 FreeBSD 上安装 VirtualBox

VirtualBox 是甲骨文（Oracle）公司开发的跨平台第二类虚拟机管理程序（Type-2 hypervisor）。

VirtualBox 自 7.0 版本起采用 GNU 通用公共许可证第三版（GPLv3）协议开源发布（4.0 至 6.1 版本为 GPLv2），支持 x86 与 AMD64 架构的硬件辅助虚拟化（Intel VT-x 与 AMD-V）。硬件辅助虚拟化技术使虚拟机可以直接访问部分硬件资源，显著提升虚拟化性能。

闭源的 VirtualBox 扩展包（VirtualBox Extension Pack）尚不支持 FreeBSD，该扩展包提供 USB 2.0/3.0 支持、磁盘镜像加密、VRDP 远程桌面协议等附加功能。

## 安装 VirtualBox

VirtualBox 在 FreeBSD 上有多个版本可供选择。6.1 版本（legacy）和 7.0 版本已停止上游支持，7.1 版本已于 2026 年 4 月停止上游支持，7.2 版本为当前维护版本。各版本均提供无 X11 的 `-nox11` 变体（例如 **emulators/virtualbox-ose-nox11-71**），适用于无图形界面的服务器环境，仅可通过命令行工具 `VBoxManage` 操作。

本节安装 **emulators/virtualbox-ose-71**。

使用 pkg 安装的预编译内核模块可能与当前运行的内核版本不匹配，而通过 Ports 编译安装可以确保内核模块与当前系统内核完全匹配，因此推荐使用 Ports 安装：

```sh
# cd /usr/ports/emulators/virtualbox-ose-71/
# make install clean
```

> **注意**
>
> 编译过程需要在 **/usr/src/** 目录下存在内核源代码。

## 安装后的说明

VirtualBox 安装完成后，可以通过以下命令查看详细的安装说明和配置指导：

```sh
# pkg info -D virtualbox-ose-71
virtualbox-ose-71-7.1.10:
On install:
VirtualBox was installed.
VirtualBox 已安装。

You need to load the vboxdrv kernel module via /boot/loader.conf:
你需要通过 /boot/loader.conf 加载 vboxdrv 内核模块：

vboxdrv_load="YES"

You also have to add all users to your vboxusers group in order to use vbox.
你还需要将使用 VirtualBox 的用户加入 vboxusers 组：

% pw groupmod vboxusers -m jerry

Reboot the machine to load the needed kernel modules.
重启系统以加载所需的内核模块。


Bridging Support:
=================
桥接支持：

For bridged networking please add the following line to your /etc/rc.conf:
要启用桥接网络，请将以下行添加到 /etc/rc.conf：

vboxnet_enable="YES"


USB Support:
============
USB 支持：

For USB support your user needs to be in the operator group and needs read
and write permissions to the USB device.
要启用 USB 支持，用户需要属于 operator 组，并具有对 USB 设备的读写权限。

% pw groupmod operator -m jerry

Add the following to /etc/devfs.rules (create if it doesn't exist):
将以下内容添加到 /etc/devfs.rules（如文件不存在，请创建）：

[system=10]
add path 'usb/*' mode 0660 group operator

To load these new rule add the following to /etc/rc.conf:
要加载这些新规则，请在 /etc/rc.conf 中添加以下行：

devfs_system_ruleset="system"

Then restart devfs to load the new rules:
然后重启 devfs 以使新规则生效：

% /etc/rc.d/devfs restart


Troubleshooting:
================
故障排查：

Running VirtualBox as non-root user may fail with a fatal error
NS_ERROR_FACTORY_NOT_REGISTERED. In this case delete /tmp/.vbox-*-ipc file.
以非 root 用户运行 VirtualBox 时可能会因致命错误 NS_ERROR_FACTORY_NOT_REGISTERED 而失败。此时请删除 /tmp/.vbox-*-ipc 文件。

If you experience "Network: write Failed: Cannot allocate memory" errors
try to increase net.graph.maxdata in /boot/loader.conf
如果遇到“Network: write Failed: Cannot allocate memory”错误，请尝试在 /boot/loader.conf 中增加 net.graph.maxdata 的值。

If you are using AIO, then increase these limits (https://bugs.freebsd.org/168298):
如果正在使用 AIO，请提高以下限制值（详见 https://bugs.freebsd.org/168298）：
vfs.aio.max_buf_aio=8192
vfs.aio.max_aio_queue_per_proc=65536
vfs.aio.max_aio_per_proc=8192
vfs.aio.max_aio_queue=65536
To check if AIO is used use: kldstat -v | grep aio
要检查是否启用了 AIO，可运行：kldstat -v | grep aio

If you are experiencing VMs freezes with an error in VBox.log such as:
如果虚拟机出现冻结，并在 VBox.log 中出现如下错误信息：

"
00:01:29.590192 AssertLogRel /usr/ports/emulators/virtualbox-ose/work/VirtualBox-6.1.44
/src/VBox/VMM/VMMR3/PGMPhys.cpp(5148) int PGMR3PhysAllocateHandyPages(PVM): RT_SUCCESS(rc)
00:01:29.590221 87/128: idPage=0x3d400 HCPhysGCPhys=000000027eaed000 rc=VERR_NO_MEMORY
00:01:29.590247 Changing the VM state from 'RUNNING' to 'GURU_MEDITATION'
00:01:29.590261 Console: Machine state changed to 'GuruMeditation'
00:01:29.590695 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
00:01:29.590696 !!
00:01:29.590697 !!         VCPU0: Guru Meditation -8 (VERR_NO_MEMORY)
"

and see a lot of free RAM, then increase sysctl vm.max_user_wired
(https://bugs.freebsd.org/252227).
如果系统存在大量空闲内存，但仍出现问题，请增加 sysctl vm.max_user_wired 的值（详见 https://bugs.freebsd.org/252227）。

For dedicated VM servers, a good start is:
对于专用虚拟机服务器，可以按以下公式设置初始值：
（“内存容量（GB）” − max(1, “内存容量（GB） / 32”)） × 1024 × 1024 × 1024 ÷ PAGE_SIZE
x86 架构下 PAGE_SIZE 为 4096。

Examples with different RAM sizes in GB:
不同内存容量的示例（单位为 GB）：
 16: ( 16-max(1, 16/32)*1024*1024*1024/4096 ) = 3932160  =>  15GB
 32: ( 32-max(1, 32/32)*1024*1024*1024/4096 ) = 8126464  =>  31GB
 48: ( 48-max(1, 48/32)*1024*1024*1024/4096 ) = 12189696 =>  46.5GB
 64: ( 64-max(1, 64/32)*1024*1024*1024/4096 ) = 16252928 =>  62GB
128: (128-max(1,128/32)*1024*1024*1024/4096 ) = 32505856 => 124GB
256: (256-max(1,256/32)*1024*1024*1024/4096 ) = 65011712 => 248GB

When assigning IP addresses in host-only mode from ranges outside
of VirtualBox's defaults, the respective ranges need to be listed
in /usr/local/etc/vbox/networks.conf (https://bugs.freebsd.org/259399).
如果在 host-only 模式下分配的 IP 地址超出 VirtualBox 默认范围，请将对应的地址范围写入 /usr/local/etc/vbox/networks.conf（详见 https://bugs.freebsd.org/259399）。

Check the wiki page for known issues and troubleshooting:
查看官方 Wiki 页面获取已知问题和故障排查信息：
https://wiki.freebsd.org/VirtualBox

Please report any problems to emulation@. Thanks!
如遇问题，请发送邮件报告至 emulation@，谢谢！


On upgrade from virtualbox-ose-71<6.1.22:
从 virtualbox-ose-71 小于 6.1.22 的版本升级时：

The PULSEAUDIO option has been forcibly disabled since VirtualBox
version 6.1.24 due to a bug in it preventing virtual machines
configured to use it from starting.
从 VirtualBox 6.1.24 起，PULSEAUDIO 选项已被强制禁用，因为其存在导致配置使用它的虚拟机无法启动的错误。

When upgrading from a previous version please reconfigure any virtual
machines using the Pulseaudio host audio driver to use another
supported one.
升级后，请将所有使用 Pulseaudio 主机音频驱动的虚拟机改为使用其他受支持的音频驱动。


On upgrade from virtualbox-ose-71>6.1.26<6.1.32_1:
从 virtualbox-ose-71 版本大于 6.1.26 且小于 6.1.32_1 的版本升级时：

To comply to hier(7) requirements, networks.conf's location changed
to /usr/local/etc/vbox/networks.conf.
为符合 hier(7) 要求，networks.conf 的位置已更改为 /usr/local/etc/vbox/networks.conf。

In case /etc/vbox/networks.conf exists, it needs to be moved to
/usr/local/etc/vbox and /etc/vbox should be deleted.
如果 /etc/vbox/networks.conf 存在，请将其移动到 /usr/local/etc/vbox，并删除 /etc/vbox 目录。
```

## 文件结构

```sh
/
├── boot/
│   └── loader.conf # 内核模块加载配置
├── etc/
│   ├── rc.conf # 系统启动配置
│   ├── devfs.rules # DevFS 规则文件
│   └── vbox/
│       └── networks.conf # 旧版 VirtualBox 网络配置位置
├── tmp/
│   └── .vbox-*-ipc # VirtualBox IPC 临时文件
└── usr/
    ├── local/
    │   └── etc/
    │       └── vbox/
    │           └── networks.conf # VirtualBox 网络配置
    ├── ports/
    │   └── emulators/
    │       └── virtualbox-ose-71/ # VirtualBox Ports 目录
    └── src/ # 内核源代码目录
```

## 配置

加载 vboxdrv 内核模块，该模块为 VirtualBox 提供核心虚拟化功能。

1. **加载内核模块**：将以下行写入 **/boot/loader.conf** 文件，设置系统在启动时加载 VirtualBox 内核模块

   ```ini
   vboxdrv_load="YES"
   ```
2. **启用桥接网络支持**：允许虚拟机直接连接物理网络

   ```sh
   # service vboxnet enable # 设置 VirtualBox 网络服务开机自启
   ```

默认的 `net.graph.maxdata` 值通常足够，不需要修改。

### 普通用户所需

普通用户使用 VirtualBox 前，需要将用户加入相应的用户组以获取必要权限：

需要分别加入 `vboxusers`、`operator`（USB 支持）组：

```sh
# 将当前用户添加到 operator 用户组
# pw groupmod operator -m 实际用户名

# 将当前用户添加到 vboxusers 用户组
# pw groupmod vboxusers -m 实际用户名
```

将以下内容添加到 **/etc/devfs.rules** 文件（如不存在请创建）：

```ini
[system=10]
add path 'usb/*' mode 0660 group operator
```

为 USB 设备添加访问权限，设置文件模式为 `0660`，所属组为 `operator`。

加载这些新规则，需要编辑 **/etc/rc.conf** 文件并添加以下行：

```ini
devfs_system_ruleset="system" # 设置 DevFS 使用规则集 "system"
```

重启 DevFS 服务以应用新的规则集：

```sh
# /etc/rc.d/devfs restart
```

以非 root 用户运行 VirtualBox 时报错 `NS_ERROR_FACTORY_NOT_REGISTERED`，可删除匹配该模式的临时文件：

```sh
# rm /tmp/.vbox-*-ipc
```

## 测试

完成所有配置后，可以启动 VirtualBox 并创建虚拟机测试，如图所示：

![VirtualBox 界面](/files/K5eEl5oQunYgU0milRuL)

## 故障排除与未竟事宜

本节提供 VirtualBox 使用过程中可能遇到的问题及其解决方法。

### TPM 不支持

设置界面可见该选项，但虚拟机无法启动。

## 参考文献

* Oracle Corporation. GPL\[EB/OL]. (2022-10-10)\[2026-04-17]. <https://www.virtualbox.org/wiki/GPL>. 从 4.0 版本到 6.1 版本（含），VirtualBox 基础包根据 GPLv2 授权分发。（VirtualBox 的某些部分，尤其是库，也可能以其他许可证发布。）
* Oracle Corporation. GPLv3\[EB/OL]. (2022-10-10)\[2026-04-17]. <https://www.virtualbox.org/wiki/GPLv3>. 从 7.0 版本开始，VirtualBox 基础包根据 GPLv3 许可证进行许可。由于 Qt 库更改了其许可证，因此需要进行许可证变更以保持兼容性。
* Oracle. VirtualBox Licensing FAQ\[EB/OL]. virtualbox.org, \[2026-04-17]. <https://www.virtualbox.org/wiki/Licensing_FAQ>. VirtualBox 基础包以 GPLv3 发布，扩展包以 [PUEL](https://www.virtualbox.org/wiki/VirtualBox_PUEL)（VirtualBox 扩展包个人使用和教育许可证）许可。
* Oracle. Oracle VM VirtualBox Extension Pack\[EB/OL]. docs.oracle.com, \[2026-04-17]. <https://docs.oracle.com/en/virtualization/virtualbox/7.0/user/Introduction.html>. 扩展包提供 USB 2.0/3.0、磁盘镜像加密、VRDP 等功能。
* FreeBSD Wiki. VirtualBox\[EB/OL]. \[2026-04-17]. <https://wiki.freebsd.org/VirtualBox>. FreeBSD 上 VirtualBox 的已知问题与故障排查。
* FreshPorts. virtualbox-ose-72\[EB/OL]. \[2026-04-17]. <https://www.freshports.org/emulators/virtualbox-ose-72/>. FreeBSD Ports 中 VirtualBox 各版本的当前维护状态。

## 课后习题

1. 使用 VBoxManage 命令行工具创建虚拟机并启动，记录操作步骤。
2. 对比 VirtualBox 与 bhyve 在 FreeBSD 上的性能差异，使用基准测试工具进行测量。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://book.bsdcn.org/di-20-zhang-xu-ni-hua-yu-rong-qi-guan-li/di-20.4-jie-zai-freebsd-shang-an-zhuang-virtualbox.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.