25.5 更新 ZFS 的 zpool

更新 zpool

FreeBSD 大版本间通常 ZFS 版本都会发生变动，如从 14.3 到 15.0 的 zpool 版本就有所升级。

警告

请准备好备份和急救 CD 以应对意外。因为旧的基本系统内置的 ZFS 不支持新版的 ZFS 文件系统（功能集不向下兼容）。

验证版本

• 查看当前系统版本

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

• 查看 ZFS/zpool 相关版本

# zpool version
2.4.0-rc4-FreeBSD_g099f69ff5
zfs-kmod-2.4.0-rc4-FreeBSD_g099f69ff5

警告

这意味着凡是 ZFS 低于 2.4.0-rc4 的操作系统，在升级后均可能无法启动。

进行更新

由于未升级前不能充分利用 ZFS 新功能，下面进行升级：

# zpool status
  pool: zroot
 state: ONLINE
status: Some supported and requested features are not enabled on the pool.
        The pool can still be used, but some features are unavailable.
action: Enable all features using 'zpool upgrade'. Once this is done,
        the pool may no longer be accessible by software that does not support
        the features. See zpool-features(7) for details.
  scan: scrub repaired 0B in 00:01:08 with 0 errors on Sun Dec  7 20:34:48 2025
config:

        NAME        STATE     READ WRITE CKSUM
        zroot       ONLINE       0     0     0
          nda0p4    ONLINE       0     0     0

errors: No known data errors

根据提示：

状态：存储池上有一些支持的且已请求的功能尚未启用。存储池仍然可以使用，但部分功能不可用。

操作：使用 zpool upgrade 启用所有功能。在完成后，未支持这些功能的软件可能无法再访问该存储池。详细信息请参见 zpool-features(7)。

我们的确需要更新，并且更新后旧系统可能再也无法启动。

我们预览一下有哪些功能会被更新：

# zpool upgrade
This system supports ZFS pool feature flags.

All pools are formatted using feature flags.


Some supported features are not enabled on the following pools. Once a
feature is enabled the pool may become incompatible with software
that does not support the feature. See zpool-features(7) for details.

Note that the pool 'compatibility' feature can be used to inhibit
feature upgrades.

Features marked with (*) are not applied automatically on upgrade, and
must be applied explicitly with zpool-set(7).

POOL  FEATURE
---------------
zroot
      redaction_list_spill
      raidz_expansion
      fast_dedup
      longname
      large_microzap
      dynamic_gang_header(*)
      block_cloning_endian
      physical_rewrite

可以看到，除了带 * 的需要手动启用外，其他功能均会在升级后默认启用。

警告

zpool upgrade 并 不能 真正启用这些特性，只是 预览 那些功能可以启用。要更新，必须同时 指定存储池名 才能进行更新：zpool upgrade zroot。参见 'zpool status' gives confusing suggestion with 'zpool upgrade'。

思考题

有贡献者认为上面 issue 关联的修补 PR 是琐碎的，无关紧要的细枝末节，甚至以每行不得超出 80 字符的客观理由予以拒绝，可问题在于无数人都被这种“小事”浪费了不止一个小时的时间。你怎样理解对于文字力量的忽视，其代价究竟是什么？

现在让我们来真正升级看看：

# zpool upgrade zroot
This system supports ZFS pool feature flags.

Enabled the following features on 'zroot':
  redaction_list_spill
  raidz_expansion
  fast_dedup
  longname
  large_microzap
  block_cloning_endian
  physical_rewrite

Pool 'zroot' has the bootfs property set, you might need to update
the boot code. See gptzfsboot(8) and loader.efi(8) for details.

• 检查状态：

# zpool status
  pool: zroot
 state: ONLINE
  scan: scrub repaired 0B in 00:01:08 with 0 errors on Sun Dec  7 20:34:48 2025
config:

        NAME        STATE     READ WRITE CKSUM
        zroot       ONLINE       0     0     0
          nda0p4    ONLINE       0     0     0

errors: No known data errors

一如既往。

附录：启用那些需要手动启用的特性

如果你还希望手动启用一些功能：

# zpool upgrade 
This system supports ZFS pool feature flags.

All pools are formatted using feature flags.


Some supported features are not enabled on the following pools. Once a
feature is enabled the pool may become incompatible with software
that does not support the feature. See zpool-features(7) for details.

Note that the pool 'compatibility' feature can be used to inhibit
feature upgrades.

Features marked with (*) are not applied automatically on upgrade, and
must be applied explicitly with zpool-set(7).

POOL  FEATURE
---------------
zroot
      dynamic_gang_header(*)

这说明可以手动启用 dynamic_gang_header，我们来查看其状态

# zpool get feature@dynamic_gang_header 
NAME   PROPERTY                     VALUE                        SOURCE
zroot  feature@dynamic_gang_header  disabled                     local

的确未启用。我们为 zroot 启用：

# zpool set feature@dynamic_gang_header=enabled zroot

再看看：

# zpool get feature@dynamic_gang_header
NAME   PROPERTY                     VALUE                        SOURCE
zroot  feature@dynamic_gang_header  enabled                      local

检查看看：

# zpool upgrade
This system supports ZFS pool feature flags.

All pools are formatted using feature flags.

Every feature flags pool has all supported and requested features enabled.

重写引导（仅 BIOS 传统引导需要）

警告

bootfs 属性是在 ZFS 上引导 FreeBSD 的重要标志，不理睬这个提示可能没事，但出了问题就不能引导系统，建议按提示重写 boot code (为什么这么建议？因为我炸了)。如果你没有 freebsd-boot 分区就 不需要 以下操作。

查看分区信息：

# gpart show

=>      40  33554352  ada0  GPT  (16G)
        40      1024     1  freebsd-boot  (512K)
      1064       984        - free -  (492K)
      2048   4194304     2  freebsd-swap  (2.0G)
   4196352  29356032     3  freebsd-zfs  (14G)
  33552384      2008        - free -  (1.0M)

找到 freebsd-boot 类型分区，这里序号为 1，对应下面命令中 -i 选项，接着重写 bootcode：

# gpart bootcode -p /boot/gptzfsboot -i 1 ada0
partcode written to ada0p1

可再次查看 zpool 状态：

# zpool status

  pool: zroot
 state: ONLINE
config:

NAME        STATE     READ WRITE CKSUM
zroot       ONLINE       0     0     0
  ada0p3    ONLINE       0     0     0

errors: No known data errors