19.1 使用 freebsd-update 更新 FreeBSD

警告

freebsd-update 支持 amd64 和 arm64（aarch64）架构的 RELEASE、ALPHA、BETA、RC 版本。CURRENT、STABLE 和 PRERELEASE 分支不提供二进制更新，若使用 freebsd-update 将直接报错退出。上述分支必须通过源码编译方式或者 PkgBase 更新。

freebsd-update 是 FreeBSD 的基本系统更新工具，支持从 FreeBSD 官方更新服务器下载、校验并安装二进制更新，亦可用于跨 RELEASE 版本的升级与回滚。

注意

仅 amd64 和 arm64（aarch64）架构的 ALPHA、BETA、RC、RELEASE 版本提供更新源。CURRENT、STABLE 与 PRERELEASE 均无二进制更新。关于架构的支持等级说明请参见：FreeBSD Project. Supported Platforms[EB/OL]. [2026-03-26]. https://www.freebsd.org/platforms。

注意

ZFS 相关升级请参见 ZFS 章节。

历史

FreeBSD 提供了实用工具 freebsd-update，用于安装系统更新，包括升级到新的大版本。freebsd-update 最早随 FreeBSD 6.2-RELEASE 纳入基本系统，用于安全更新和勘误补丁；在 FreeBSD 6.3-RELEASE 中引入了 upgrade 命令，至 7.0-RELEASE 时正式成为官方支持的升级途径。

参考文献

• FreeBSD Project. FreeBSD 6.2-RELEASE Release Notes[EB/OL]. [2026-04-16]. https://www.freebsd.org/releases/6.2R/relnotes.html. 发行说明，“The freebsd-update(8) utility is now included in the FreeBSD base system.”
• FreeBSD Project. FreeBSD 7.0-RELEASE Announcement[EB/OL]. [2026-03-25]. https://www.freebsd.org/releases/7.0R/announce/. 官方公告明确 freebsd-update 为支持的二进制更新工具，适用于版本升级、安全修复及勘误补丁。
• FreeBSD Project. freebsd-update -- fetch, install, and rollback FreeBSD updates[EB/OL]. [2026-04-17]. https://man.freebsd.org/cgi/man.cgi?query=freebsd-update&sektion=8. FreeBSD 系统更新工具手册页。

将默认文本编辑器替换为更简单的编辑器

Bash、Zsh 或 sh

# export EDITOR=/usr/bin/ee  # 将默认编辑器从 vi 切换为 ee
# export VISUAL=/usr/bin/ee  # 将可视化编辑器从 vi 切换为 ee

csh / tcsh

# setenv EDITOR /usr/bin/ee  # 将默认编辑器从 vi 切换为 ee
# setenv VISUAL /usr/bin/ee  # 将可视化编辑器从 vi 切换为 ee

检查与验证

• 查看当前终端默认文本编辑器：

# echo $EDITOR
/usr/bin/ee

• 查看当前终端可视化文本编辑器：

# echo $VISUAL
/usr/bin/ee

常规补丁/安全更新（X.Y-RELEASE → X.Y-RELEASE-pN）

警告

无论是大版本更新、点版本更新还是常规更新，都应该先执行该流程。不可跳过，否则可能导致依赖缺失或系统无法正常启动。

FreeBSD 版本检查

# freebsd-version -kru
14.3-RELEASE
14.3-RELEASE
14.3-RELEASE

进行更新

• 获取更新

# freebsd-update fetch

当出现类似如下信息时：

usr/include/c++/v1/tr1/vector usr/include/c++/v1/tr1/version usr/include/c++/v1/tr1/wchar.h usr/include/c++/v1/tr1/wctype.h usr/include/c++/v1/unwind-arm.h
usr/include/c++/v1/unwind-itanium.h usr/include/c++/v1/unwind.h
usr/include/crypto/cryptodev.h usr/include/crypto/cbcmac.h usr/include/crypto/deflate.h usr/include/crypto/gfmult.h usr/include/crypto/gmac.h
usr/include/crypto/rijndael.h usr/include/crypto/rmd160.h usr/include/crypto/xform.h
usr/lib/clang/19.1.7/include
: q # 输入 q 并回车退出

上述路径仅为示例输出，实际系统中的路径名称和数量可能会略有不同，请以实际输出为准。

此处列出的是发生变动的文件，确认后输入字母 q（quit，退出）并按回车键即可。

随后安装更新：

# freebsd-update install

若需自动化定期检查更新，可改用 freebsd-update cron，该命令会随机延迟 1 至 3600 秒后执行 fetch。

验证更新后的 FreeBSD 版本

• 查看更新后的 FreeBSD 版本：

# freebsd-version -kru
14.3-RELEASE-p5
14.3-RELEASE
14.3-RELEASE-p6

注意

有时补丁未涉及内核，内核版本不会改变，使用 uname -r 无法体现，但用户空间版本会发生变化。因此可能显示两个版本号，应以较高者为准。

重启系统：

# reboot

查看 FreeBSD 版本：

# freebsd-version -kru
14.3-RELEASE-p5
14.3-RELEASE-p5
14.3-RELEASE-p6

大版本更迭（X.Z-RELEASE-pN → A.0-RELEASE）

注意

freebsd-update 下载速率较低并非由于其更新源位于境外（使用境外服务器更新同样存在此问题）。可能与其设计方式有关，freebsd-update 是一个由数千行代码组成的纯 Shell 脚本。这是长期存在的问题。

freebsd-update upgrade 在工作目录（默认 /var/db/freebsd-update/）中可能需要最多 500 MB 空间，具体取决于已安装的基本系统组件。如果升级中断，可使用 -F 标志强制 fetch 继续处理未完成的升级。

以 FreeBSD 14.3-RELEASE 升级到 15.0-RELEASE 为例

检查版本

# freebsd-version -kru
14.3-RELEASE-p5
14.3-RELEASE-p5
14.3-RELEASE-p6

警告

由于大版本间的变动可能影响 freebsd-update 更新工具本身，所以务必：

先更新到当前版本最新的补丁版本（如 X.Y-RELEASE-pN），随后再更新到最新的点版本（如 X.Z-RELEASE）。

接下来，更新到最新的点版本及该点版本上最新的补丁版本（如 X.Z-RELEASE-pN）

最后：完成大版本（X.Z-RELEASE-pN——>A.0-RELEASE）的更迭。

参见：libsys.so.7 not found when upgrading userland with legacy freebsd-update[EB/OL]. [2026-03-26]. https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=289769。

更新到 15.0-RELEASE

升级系统到 FreeBSD 15.0-RELEASE 版本：

# freebsd-update upgrade -r 15.0-RELEASE

……当出现类似于下列信息时，按照下方提示操作……

src component not installed, skipped
Looking up update.FreeBSD.org mirrors... 3 mirrors found.
Fetching metadata signature for 14.3-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 2 metadata patches.. done.
Applying metadata patches... done.
Fetching 1 metadata files... done.
Inspecting system... done.

The following components of FreeBSD seem to be installed:
kernel/generic kernel/generic-dbg world/base world/lib32

The following components of FreeBSD do not seem to be installed:
world/base-dbg world/lib32-dbg

Does this look reasonable (y/n)? y # 输入 y 并回车，确认基本组件的安装情况

Fetching metadata signature for 15.0-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 1 metadata patches. done.
Applying metadata patches... done.
Fetching 1 metadata files... done.
Inspecting system...

…………此处是在检查系统，从上面的回车到这里需要等待约 10 分钟…………

Fetching metadata signature for 15.0-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 1 metadata patches. done.
Applying metadata patches... done.
Fetching 1 metadata files... done.
Inspecting system... done.
Fetching files from 14.3-RELEASE for merging... done.
Preparing to download files... done.

…………此处是在准备要下载的文件，需要等待约 15 分钟…………

Fetching 6735 patches.....10....20....30....40....50....60....70....80....90.

………………下面需要等待约 30 分钟。注意，跨大版本更新时，有时需要等待 5 小时或更长时间，这都属于正常现象。………………

....100....110....120....130....140....150....160....170....180....190....200

…………中间省略………………

20....6630....6640....6650....6660....6670....6680....6690....6700....6710....6720....6730.. done.
Applying patches...

………………打补丁，需要等待约 5 分钟………………

Applying patches... done.
Fetching 880 files... ....10....20....30....4

………………省略一部分进度条………………

0....880 done.
Attempting to automatically merge changes in files... done.

The following file could not be merged automatically: /etc/pkg/FreeBSD.conf
Press Enter to edit this file in /usr/bin/ee and resolve the conflicts
manually...

……这里提示按回车键编辑无法自动合并而需手动处理的文件……

The following changes, which occurred between FreeBSD 14.3-RELEASE and
FreeBSD 15.0-RELEASE have been merged into /etc/login.conf:
--- current version
+++ new version

……此处列出的是发生变动的文件，省略一部分输出……

 #site:\
-#      :ignoretime:\
 #      :passwordtime@:\
 #      :refreshtime@:\
 #      :refreshperiod@:\
 #      :sessionlimit@:\
 #      :autodelete@:\
Does this look reasonable (y/n)? # 输入 y 并按回车键，以确认系统文件变动

The following changes, which occurred between FreeBSD 14.3-RELEASE and
FreeBSD 15.0-RELEASE have been merged into /etc/pkg/FreeBSD.conf:
--- current version
+++ new version

……此处列出的是发生变动的文件，省略一部分输出……

Does this look reasonable (y/n)?  # 输入 y 并按回车键，以确认系统文件变动

The following changes, which occurred between FreeBSD 14.3-RELEASE and
FreeBSD 15.0-RELEASE have been merged into /etc/ssh/sshd_config:
--- current version
+++ new version

……此处列出的是发生变动的文件，省略一部分输出……

 # override default of no subsystems
Does this look reasonable (y/n)? # 输入 y 并按回车键，以确认系统文件变动

The following files are affected by updates. No changes have
been downloaded, however, because the files have been modified
locally:
/etc/ssl/cert.pem
(END) # 上述为发生变动的文件，确认后输入 q 并回车退出

# 上述路径仅为示例输出，实际系统中的路径名称和数量可能会略有不同，以本机实际显示为准。

The following files will be removed as part of updating to
15.0-RELEASE-p0:
/.cshrc
/.profile
/boot/kernel/callout_test.ko
/boot/kernel/geom_bde.ko
/boot/kernel/geom_vinum.ko

…………中间省略，这些是将删除的文件………………

/usr/share/examples/sound/sndstat_nv.c
: # 输入 q 确认变动，直至无新内容出现

…………中间省略………………

The following files will be added as part of updating to
15.0-RELEASE-p0:
/boot/firmware/iwm3160fw
/boot/firmware/iwm3168fw
/boot/firmware/iwm7260f

…………中间省略这些是新增的文件………………

/boot/kernel/nvmf_tcp.ko
/boot/kernel/nvmf_transport.ko
/boot/kernel/nvmft.ko
/boot/kernel/p9fs.ko
: # 输入 q 确认变动，直至无新内容出现

The following files will be updated as part of updating to
15.0-RELEASE-p0:
/COPYRIGHT
/bin/[
/bin/cat

…………中间省略这些是更新的文件………………

/bin/kenv
/bin/kill
/bin/link
/bin/ln
/bin/ls
/bin/mkdir
/bin/mv
/bin/nproc
To install the downloaded upgrades, run 'freebsd-update [options] install'.

运行 freebsd-update install 以安装更新：

# freebsd-update install
src component not installed, skipped
Creating snapshot of existing boot environment... done.
Installing updates...
Kernel updates have been installed.  Please reboot and run
'freebsd-update [options] install' again to finish installing updates.

内核更新已安装：

# freebsd-version -kru
15.0-RELEASE
14.3-RELEASE-p5
14.3-RELEASE-p6

可以看到，当前已安装内核的版本和补丁级别是 15.0-RELEASE。但用户空间和当前正在运行的系统仍是 14.3-RELEASE，因此需要按照 freebsd-update 的提示重启：

# reboot

运行 freebsd-update install 安装用户空间的更新部分：

# freebsd-update install
src component not installed, skipped
Creating snapshot of existing boot environment... done.
Installing updates...
Restarting sshd after upgrade
Performing sanity check on sshd configuration.
Stopping sshd.
Waiting for PIDS: 906.
Performing sanity check on sshd configuration.
Starting sshd.

Completing this upgrade requires removing old shared object files.
Please rebuild all installed 3rd party software (e.g., programs
installed from the ports tree) and then run
'freebsd-update [options] install' again to finish installing updates.

重新安装 pkg 本身，将 ABI 更新到 15.0-RELEASE：

# pkg bootstrap -fy
Bootstrapping pkg from pkg+https://pkg.FreeBSD.org/FreeBSD:15:amd64/quarterly, please wait...
Verifying signature with trusted certificate pkg.freebsd.org.2013102301... done
Installing pkg-2.4.2...
package pkg is already installed, forced install
Extracting pkg-2.4.2: 100%

将第三方程序的 ABI 更新到 15.0-RELEASE：

# pkg upgrade
Updating nju repository catalogue...
Fetching meta.conf:   0%
Fetching data.pkg: 100%    7 MiB   7.6MB/s    00:01
Processing entries: 100%
nju repository update completed. 35765 packages processed.
All repositories are up to date.
Updating database digests format: 100%
Checking for upgrades (215 candidates): 100%
Processing candidates (215 candidates): 100%
The following 223 package(s) will be affected (of 0 checked):

New packages to be INSTALLED:
	ceres-solver: 2.2.0_10

…………中间省略………………

The process will require 45 MiB more space.
687 MiB to be downloaded.

Proceed with this action? [y/N]:  # 输入 y 并回车继续

…………中间省略…………

Proceed with this action? [y/N]:  # 输入 y 并回车继续，可能会出现多次，下同

第三方程序的更新至此完成。

再次执行 freebsd-update 以完成更新流程。

# freebsd-update install
src component not installed, skipped
Creating snapshot of existing boot environment... done.
Installing updates... done.

验证操作系统版本：

# freebsd-version -kru
15.0-RELEASE
15.0-RELEASE
15.0-RELEASE

系统更新完成。

故障排除与未竟事宜

回滚更新

回滚最近一次系统更新：

# freebsd-update rollback

pkg 找不到 .so 文件

终端执行命令强制初始化 pkg 包管理器：

# pkg bootstrap -f

FreeBSD 升级出错，导致缺少 ntpd 用户

终端执行命令：

# pw groupadd ntpd -g 123  # 创建 ntpd 用户组，GID 为 123
# pw useradd ntpd -u 123 -g ntpd -h - -d /var/db/ntp -s /usr/sbin/nologin -c "NTP Daemon"  # 创建 ntpd 用户，UID 为 123，主目录 /var/db/ntp，禁止登录，仅用于 NTP 守护进程

课后习题

1. 阅读 freebsd-update 脚本的源代码，使用高级编程语言重构，并验证是否能显著提升更新速度。
2. 制作一个 freebsd-update 镜像站。
3. freebsd-update 的二进制补丁模型依赖于对基本系统组件版本的精确跟踪，而第三方软件的更新则交由 pkg 管理。分析这种“基本系统与 Ports 分离”的更新策略在 ABI（Application Binary Interface）兼容性保障方面的优势，及其对滚动更新需求造成的限制。