How to upgrade ZFS storage pools version on FreeBSD

When we update FreeBSD from 12 to 13, we get an updated version of ZFS. FreeBSD 13 released with OpenZFS support with various performance boosts. Sometimes OS patching and minor FreeBSD upgrade can also offer an updated zpool version. In any case, we need to upgrade the ZFS storage pools version to get newer functionality and bug fixes. This page explains how to update the ZFS storage pools version on FreeBSD.

Tutorial details
Difficulty level Easy
Root privileges Yes
Requirements FreeBSD with ZFS
Est. reading time 4 minutes

How To Find Out If My ZFS Pools Are Running Older Versions on FreeBSD

Let us see FreeBSD version:
$ freebsd-version

We can use the zpool command to see the detailed health status for the given pools. The same FreeBSD command will notify us when our pools are running older versions. For instance:
$ zpool status
$ zpool status -v
# we can also state pool name such as zroot #
$ zpool status -v zroot

Here is what I see on FreeBSD 13:

  pool: zroot
 state: ONLINE
status: Some supported 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(5) for details.
  scan: scrub repaired 0B in 00:20:37 with 0 errors on Fri Apr 30 17:11:45 2021
	zroot           ONLINE       0     0     0
	  raidz1-0      ONLINE       0     0     0
	    ada0p3.eli  ONLINE       0     0     0
	    ada1p3.eli  ONLINE       0     0     0
	    ada3p3.eli  ONLINE       0     0     0
errors: No known data errors

To read about all new ZFS pool feature descriptions, run the following man command:
$ man 5 zpool-features

Finding ZFS Storage Pools Version

Try any one of the following commands:
$ zpool get version zroot
$ zfs get version zroot

Let us display system supports ZFS pool feature flags including legacy versions:
$ zpool upgrade -v

This system supports ZFS pool feature flags.
The following features are supported:
async_destroy                         (read-only compatible)
     Destroy filesystems asynchronously.
empty_bpobj                           (read-only compatible)
     Snapshots use less space.
     LZ4 compression algorithm support.
     Crash dumps to multiple vdev pools.
spacemap_histogram                    (read-only compatible)
     Spacemaps maintain space histograms.
enabled_txg                           (read-only compatible)
     Record txg at which a feature is enabled
     Retain hole birth txg for more precise zfs send
The following legacy versions are also supported:
---  --------------------------------------------------------
 1   Initial ZFS version
 2   Ditto blocks (replicated metadata)
 3   Hot spares and double parity RAID-Z
 4   zpool history
 5   Compression using the gzip algorithm
 6   bootfs pool property
 7   Separate intent log devices
 8   Delegated administration
 9   refquota and refreservation properties
 10  Cache devices
 11  Improved scrub performance
 12  Snapshot properties
 13  snapused property
 14  passthrough-x aclinherit
 15  user/group space accounting
 16  stmf property support
 17  Triple-parity RAID-Z
 18  Snapshot user holds
 19  Log device removal
 20  Compression using zle (zero-length encoding)
 21  Deduplication
 22  Received properties
 23  Slim ZIL
 24  System attributes
 25  Improved scrub stats
 26  Improved snapshot deletion performance
 27  Improved snapshot creation performance
 28  Multiple vdev replacements
For more information on a particular version, including supported releases,
see the ZFS Administration Guide.

Upgrading ZFS Storage Pools on FreeBSD

WARNING: You must always keep a backup of all critical data. Once you upgraded the zpool version, you can’t downgrade it. The nixCraft and author are not responsible for any data loss.

First displays pools which do not have all supported features enabled and pools formatted using a legacy ZFS version number:
$ 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(5) for details.

How to upgrade all of your pools

To enables all supported features on all pools pass the -a option as follows and then verify it using the zpool status -v
$ sudo zpool upgrade -a
## verification ##
$ zpool status -v

Upgrading ZFS Storage Pools on FreeBSD 13

Summing Up

And there you have it. Your pool upgraded to the latest supported version. Please note that the pool will not be available on a system that runs an older ZFS version. ZFS has many more options. Hence, you need to read man pages carefully if you need those older features. See the ZFS guide/documentation.

🐧 Get the latest tutorials on Linux, Open Source & DevOps via RSS feed or Weekly email newsletter.

🐧 1 comment so far... add one

CategoryList of Unix and Linux commands
Disk space analyzersdf duf ncdu pydf
File Managementcat cp mkdir tree
FirewallAlpine Awall CentOS 8 OpenSUSE RHEL 8 Ubuntu 16.04 Ubuntu 18.04 Ubuntu 20.04
Modern utilitiesbat exa
Network UtilitiesNetHogs dig host ip nmap
OpenVPNCentOS 7 CentOS 8 Debian 10 Debian 8/9 Ubuntu 18.04 Ubuntu 20.04
Package Managerapk apt
Processes Managementbg chroot cron disown fg glances gtop jobs killall kill pidof pstree pwdx time vtop
Searchingag grep whereis which
User Informationgroups id lastcomm last lid/libuser-lid logname members users whoami who w
WireGuard VPNAlpine CentOS 8 Debian 10 Firewall Ubuntu 20.04
1 comment… add one
  • Tiku May 6, 2021 @ 11:44


    I was getting errors when using rsnapshot on FreeBSD 13. After reading your tutorial I applied updates and I have not seen those errors.

Leave a Reply

Your email address will not be published.

Use HTML <pre>...</pre> for code samples. Still have questions? Post it on our forum