ZFS How to determine which version of zfs I'm running

Ofloo · Feb 26, 2023

I was in the process of moving my zfs pools to the newer version of zfs with zfs send and recv. And I thought I was running solaris version of zfs however, how do I know which version I'm running. Because when I run zfs get all on zroot It returns encryption off, which to me seems like a feature from openzfs ? So why are those flags showing up on the zroot which is a solaris version of zfs? Or at least so I thought?

gotnull · Feb 26, 2023

I think it's not the case anymore.
The following is from the handbook:

OpenZFS 2.0 is available starting with FreeBSD 12.1-RELEASE via sysutils/openzfs and has been the default in since FreeBSD 13.0-RELEASE.

But I am really not an expert, you should wait for a better answer I think.

cmoerz · Feb 26, 2023

Try zdb -C <poolname>

see zdb() for details.

Ofloo · Feb 26, 2023

gotnull I understand that currently it is default but I think I created the pool under freebsd12.0 in 2020

I'm fairly certain it's a solaris pool but the encryption flags just got me confused: but running zdb -C says version 5 does that mean it's solaris ?

Code:

# zdb -C zroot

MOS Configuration:
        version: 5000
        name: 'zroot'
        state: 0
        txg: 17425195
        pool_guid: 15010428517460706589
        errata: 0
        hostname: ''
        com.delphix:has_per_vdev_zaps
        vdev_children: 1
        vdev_tree:
            type: 'root'
            id: 0
            guid: 15010428517460706589
            create_txg: 4
            children[0]:
                type: 'disk'
                id: 0
                guid: 16745988178153554051
                path: '/dev/nvd0p4'
                whole_disk: 1
                metaslab_array: 67
                metaslab_shift: 31
                ashift: 12
                asize: 253697196032
                is_log: 0
                create_txg: 4
                com.delphix:vdev_zap_leaf: 65
                com.delphix:vdev_zap_top: 66
        features_for_read:
            com.delphix:hole_birth
            com.delphix:embedded_data

I mean lake2 is an encrypted pool so i'm fairly certain this is a openzfs pool but for some reason it also says version 5

Code:

zdb -C lake2

MOS Configuration:
        version: 5000
        name: 'lake2'
        state: 0
        txg: 50122
        pool_guid: 9512309839369571113
        errata: 0
        hostid: 4272680724
        hostname: ''
        com.delphix:has_per_vdev_zaps
        vdev_children: 1
        vdev_tree:
            type: 'root'
            id: 0
            guid: 9512309839369571113
            create_txg: 4
            children[0]:
                type: 'mirror'
                id: 0
                guid: 14070067220318027217
                metaslab_array: 256
                metaslab_shift: 34
                ashift: 12
                asize: 4000782221312
                is_log: 0
                create_txg: 4
                com.delphix:vdev_zap_top: 129
                children[0]:
                    type: 'disk'
                    id: 0
                    guid: 3591818149743278968
                    path: '/dev/gpt/lake0'
                    whole_disk: 1
                    create_txg: 4
                    com.delphix:vdev_zap_leaf: 130
                children[1]:
                    type: 'disk'
                    id: 1
                    guid: 1682686172212106832
                    path: '/dev/gpt/lake1'
                    whole_disk: 1
                    create_txg: 4
                    com.delphix:vdev_zap_leaf: 131
        features_for_read:
            com.delphix:hole_birth
            com.delphix:embedded_data

Ofloo · Feb 26, 2023

This is really strange I'm like 100% certain I created the pools when the default was solaris zfs but for some reason I can create encrypted datasets on it and everything?

Code:

# zfs get creation tank
NAME  PROPERTY  VALUE                  SOURCE
tank  creation  Tue May  1 12:09 2018  -
# zfs get encryption tank/test
NAME       PROPERTY    VALUE        SOURCE
tank/test  encryption  aes-256-gcm  -

Ofloo · Feb 26, 2023

Ofloo said:
This is really strange I'm like 100% certain I created the pools when the default was solaris zfs but for some reason I can create encrypted datasets on it and everything?

Code:

# zfs get creation tank NAME PROPERTY VALUE SOURCE tank creation Tue May 1 12:09 2018 - # zfs get encryption tank/test NAME PROPERTY VALUE SOURCE tank/test encryption aes-256-gcm -

weird If i zpool upgrade the pool it becomes openzfs?

Code:

# zfs get creation zroot
NAME   PROPERTY  VALUE                  SOURCE
zroot  creation  Sat Feb 14 12:51 2015  -
# zfs create -o encryption=on -o keyformat=passphrase -o keylocation=prompt zroot/
test
cannot create 'zroot/test': Encryption feature not enabled.
# zpool upgrade zroot
This system supports ZFS pool feature flags.

Enabled the following features on 'zroot':
  large_dnode
  userobj_accounting
  encryption
  project_quota
  allocation_classes
  resilver_defer
  bookmark_v2
  redaction_bookmarks
  redacted_datasets
  bookmark_written
  log_spacemap
  livelist
  device_rebuild
  zstd_compress
  draid

Pool 'zroot' has the bootfs property set, you might need to update
the boot code. See gptzfsboot(8) and loader.efi(8) for details.
# gpart show ada0
=>        34  3907029101  ada0  GPT  (1.8T)
          34        1024     1  freebsd-boot  (512K)
        1058     4194304     2  freebsd-swap  (2.0G)
     4195362  3902833773     3  freebsd-zfs  (1.8T)
# gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0
partcode written to ada0p1
bootcode written to ada0
# gpart show ada1
=>        34  3907029101  ada1  GPT  (1.8T)
          34        1024     1  freebsd-boot  (512K)
        1058     4194304     2  freebsd-swap  (2.0G)
     4195362  3902833773     3  freebsd-zfs  (1.8T)
# gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada1
partcode written to ada1p1
bootcode written to ada1
# zfs create -o encryption=on -o keyformat=passphrase -o keylocation=prompt zroot/
test
Enter new passphrase:
Re-enter new passphrase:

mer · Feb 26, 2023

zpool upgrade takes a pool and brings it to the version the kernel is running. If you are running FreeBSD 12.x it will bring it to the latest "Native FreeBSD ZFS" which is not openZFS. If you are running FreeBSD 13.x or -CURRENT, that is OpenZFS2.0. Basic functionality is pretty much the same, feature flags are where things differ. There may be some OpenZFS things that conflict with native FreeBSD ZFS, but I think the upgrade command wil fail in that case.

CTineo · Mar 17, 2025

Still, the question hasn't been answered.

Yes there is the option of checking the release notes of each release and sub-release of FreeBSD.

But the question remain: is there a way - on a system - to get it to output the version of zfs that is currently used.

Then the subsequent question is: can someone point us to a doc about how to manually upgrade zfs in FreeBSD, say i'm on 14.2-RELEASE and would like to use openZFS 3.0 ?

SirDice · Mar 17, 2025

CTineo said:
But the question remain: is there a way - on a system - to get it to output the version of zfs that is currently used.

zfs --version?

CTineo said:
Then the subsequent question is: can someone point us to a doc about how to manually upgrade zfs in FreeBSD, say i'm on 14.2-RELEASE and would like to use openZFS 3.0 ?

There is a development version of ZFS in filesystems/openzfs

T-Daemon · Mar 17, 2025

SirDice said:
There is a development version of ZFS in filesystems/openzfs

That port doesn't provide the latest (or near latest) openzfs version, it's even behind 14.2-RELEASE version.

Rich (BB code):

% zfs --version
zfs-2.2.6-FreeBSD_g33174af15
zfs-kmod-2.2.6-FreeBSD_g33174af15

Port version is 2.2.2

/usr/ports/filesystems/openzfs

Rich (BB code):

USE_GITHUB=     yes
GH_PROJECT=     zfs
GH_TAGNAME=     494aaae

Tag zfs-2.2.2 · openzfs/zfs@494aaae

META file and changelog updated. Signed-off-by: Tony Hutter <hutter2@llnl.gov>

github.com

T-Daemon · Mar 17, 2025

CTineo said:
can someone point us to a doc about how to manually upgrade zfs in FreeBSD, say i'm on 14.2-RELEASE and would like to use openZFS 3.0 ?

Try OpenZFS Documentation "Development on FreeBSD".

Erichans · Mar 17, 2025

CTineo said:
Then the subsequent question is: can someone point us to a doc about how to manually upgrade zfs in FreeBSD, say i'm on 14.2-RELEASE and would like to use openZFS 3.0 ?

There is indeed the development version but it is currently unmaintained and looking at the commit history from quite a long time ago. IF you insist on trying a newer OpenZFS version, I suggest you'd try using an official OpenZFS release, more information can be found at Releases and ZFS on FreeBSD

I'm curious though about any OpenZFS version 3.x being available.

P.S. be aware of the consequences of running a newer ZFS version and/or using zpool-upgrade(8); you might end up in an unbootable & unimportable pool.

SirDice · Mar 17, 2025

Ah, didn't know the filesystem/openzfs version wasn't maintained. But if you want to try the "newest" version available on FreeBSD, then -CURRENT is your best bet.

Code:

dice@chibacity:~ % zfs --version
zfs-2.3.99-170-FreeBSD_g34205715e
zfs-kmod-2.3.99-170-FreeBSD_g34205715e
dice@chibacity:~ % uname -a
FreeBSD chibacity.dicelan.home 15.0-CURRENT FreeBSD 15.0-CURRENT #13 main-n275464-89e3c2d27ab4: Sat Feb 15 12:46:03 CET 2025     root@chibacity.dicelan.home:/usr/obj/usr/src/amd64.amd64/sys/GENERIC-NODEBUG amd64

This looks to be the beta of 2.4. It's a month old though, I should probably update it.

paulw · Feb 26, 2026

My knowledge of zfs is still very basic, so I'm unsure about the role of the cachefile or the significance of the cachefile pool property being set or unset, but any thoughts on the following?

Code:

paul@dell-FreeBSD-portable-15.0-STABLE ~ $ uname -a
FreeBSD dell-FreeBSD-portable 15.0-STABLE FreeBSD 15.0-STABLE stable/15-n282467-9b75d6ec6929 GENERIC amd64

paul@dell-FreeBSD-portable-15.0-STABLE ~ $ doas zdb -C tank # name of the pool on this machine
zdb: can't open 'tank': File exists

paul@dell-FreeBSD-portable-15.0-STABLE ~ $ zfs --version
zfs-2.4.0-1-FreeBSD_g743334913
zfs-kmod-2.4.0-1-FreeBSD_g743334913

The cachefile property is unset:

paul@dell-FreeBSD-portable-15.0-STABLE ~ $ zpool get cachefile tank
NAME  PROPERTY   VALUE      SOURCE
tank  cachefile  -          default

paul@dell-FreeBSD-portable-15.0-STABLE ~ $ ls -la /boot/zfs/zpool.cache
-rw-r--r-- 1 root wheel 1440 May  9  2025 /boot/zfs/zpool.cache

paul@dell-FreeBSD-portable-15.0-STABLE ~ $ doas zpool set cachefile=/boot/zfs/zpool.cache tank

The cachefile property is now set:

paul@dell-FreeBSD-portable-15.0-STABLE ~ $ zpool get cachefile tank
NAME  PROPERTY   VALUE                  SOURCE
tank  cachefile  /boot/zfs/zpool.cache  local

paul@dell-FreeBSD-portable-15.0-STABLE ~ $ zdb -C tank

MOS Configuration:
        version: 5000
        name: 'tank'
        state: 0
        txg: 2514780
        pool_guid: 13421227167663778534
        errata: 0
        min_alloc: 4096
        max_alloc: 4096
        hostname: ''
        com.delphix:has_per_vdev_zaps
        vdev_children: 1
        vdev_tree:
            type: 'root'
            id: 0
            guid: 13421227167663778534
            create_txg: 4
            com.klarasystems:vdev_zap_root: 129
            children[0]:
                type: 'disk'
                id: 0
                guid: 17858242144203088954
                path: '/dev/da0p2'
                whole_disk: 1
                metaslab_array: 256
                metaslab_shift: 31
                ashift: 12
                asize: 240051027968
                min_alloc: 4096
                is_log: 0
                DTL: 1572
                create_txg: 4
                com.delphix:vdev_zap_leaf: 130
                com.delphix:vdev_zap_top: 131
        features_for_read:
            com.delphix:hole_birth
            com.delphix:embedded_data
            com.klarasystems:vdev_zaps_v2

paul@dell-FreeBSD-portable-15.0-STABLE ~ $

After reboot (same BE), however, the cachefile property is no longer set:

paul@dell-FreeBSD-portable-15.0-STABLE ~ $ zpool get cachefile tank
NAME  PROPERTY   VALUE      SOURCE
tank  cachefile  -          default

Is this something to be concerned about?

mer · Feb 26, 2026

My understanding:
/boot/zfs/zpool.cache is basically "description of pools currently active on the system and their providers". When you boot the system, the kernel checks that file to help figure out what to import.
The cachefile property is used to "move" the location of the file so by setting it to the default location it probably didn't change it.
Documentation also says "There is little to no benefit moving the cachefile away from the default location"

So if the system boots, don't muck cachefile property

paulw · Feb 26, 2026

mer said:
My understanding:
/boot/zfs/zpool.cache is basically "description of pools currently active on the system and their providers". When you boot the system, the kernel checks that file to help figure out what to import.
The cachefile property is used to "move" the location of the file so by setting it to the default location it probably didn't change it.
Documentation also says "There is little to no benefit moving the cachefile away from the default location"

So if the system boots, don't muck cachefile property

Hi, thanks for the clarification. So without explicitly setting the (default) cachefile property, I think my zdb command should have been - using the example of a pool called zroot on a different machine:

Code:

paul@zoo-FreeBSD-portable:-16.0-CURRENT ~ $ zdb -U /boot/zfs/zpool.cache -C zroot

MOS Configuration:
        version: 5000
        name: 'zroot'
        state: 0
        txg: 491394
        pool_guid: 15466266285943336771
        errata: 0
        min_alloc: 4096
        max_alloc: 4096
        hostname: ''
        com.delphix:has_per_vdev_zaps
        vdev_children: 1
        vdev_tree:
            type: 'root'
            id: 0
            guid: 15466266285943336771
            create_txg: 4
            com.klarasystems:vdev_zap_root: 129
            children[0]:
                type: 'disk'
                id: 0
                guid: 2775925773313825210
                path: '/dev/da0p3'
                whole_disk: 1
                metaslab_array: 132
                metaslab_shift: 31
                ashift: 12
                asize: 255781765120
                min_alloc: 4096
                is_log: 0
                DTL: 445
                create_txg: 4
                com.delphix:vdev_zap_leaf: 130
                com.delphix:vdev_zap_top: 131
        features_for_read:
            com.delphix:hole_birth
            com.delphix:embedded_data
            com.klarasystems:vdev_zaps_v2

and this works, otherwise it's looking for /etc/zfs/zpool.cache.

mer · Feb 26, 2026

I've never used anything with zdb command but man page does state that unless specified /etc/zfs/zpool.cache is the default.
Why? I don't know, perhaps that was a default for Solaris (it's probably coming from OpenZFS), maybe something that should be changed for FreeBSD?

paulw · Feb 26, 2026

mer said:
I've never used anything with zdb command but man page does state that unless specified /etc/zfs/zpool.cache is the default.
Why? I don't know, perhaps that was a default for Solaris (it's probably coming from OpenZFS), maybe something that should be changed for FreeBSD?

Yeah I saw that on the man page too, but there is no /etc/zfs/zpool.cache hence the need for the correct "-U" switch for the zdb command to work as expected and the actual default in fact seems to be /boot/zfs/zpool.cache.

Erichans · Feb 26, 2026

paulw said:
mer said:

I've never used anything with zdb command but man page does state that unless specified /etc/zfs/zpool.cache is the default.
Why? I don't know, perhaps that was a default for Solaris (it's probably coming from OpenZFS), maybe something that should be changed for FreeBSD?

Click to expand...

Yeah I saw that on the man page too, but there is no /etc/zfs/zpool.cache hence the need for the correct "-U" switch for the zdb command to work as expected and the actual default in fact seems to be /boot/zfs/zpool.cache.

The FreeBSD loader wants it there. As mer suggests, I think the text of zdb(8):

Code:

       -C, --config
	       Display information about the configuration.  If	specified with
	       no other	options, instead display information about  the	 cache
	       file (/etc/zfs/zpool.cache).  To	specify	the cache file to dis-
	       play, see -U.
   [...]
       -U, --cachefile=cachefile
	       Use a cache file	other than /etc/zfs/zpool.cache.

should be adapted according to its FreeBSD context, Boot Process - wiki/System_Administration :

On a traditional POSIX system, the boot process is as follows:
[...]
ZFS makes the following changes to the boot process:

1. When the rootfs is on ZFS, the pool must be imported before the kernel can mount it. The bootloader on Illumos and FreeBSD will pass the pool informaton to the kernel for it to import the root pool and mount the rootfs. On Linux, an initramfs must be used until bootloader support for creating the initramfs dynamically is written.
2. Regardless of whether there is a root pool, imported pools must appear. This is done by reading the list of imported pools from the zpool.cache file, which is at /etc/zfs/zpool.cache on most platforms. It is at /boot/zfs/zpool.cache on FreeBSD. This is stored as a XDR-encoded nvlist and is readable by executing the `zdb` command without arguments.
3. [...]

This seems to be an example where the OpenZFS documentation has better FreeBSD information than FreeBSD itself ...

ZFS How to determine which version of zfs I'm running

Ofloo

gotnull

cmoerz

Ofloo

Ofloo

Ofloo

mer

CTineo

SirDice

Administrator

T-Daemon

Tag zfs-2.2.2 · openzfs/zfs@494aaae

T-Daemon

Erichans

SirDice

Administrator

paulw

mer

paulw

mer

paulw

Erichans