1. Managing ZFS File Systems in Oracle Solaris 11.4
  2. Managing Oracle Solaris ZFS Storage Pools
  3. Managing ZFS Pools That Contain Boot Environments

Managing ZFS Pools That Contain Boot Environments

Starting with Oracle Solaris 11.4 SRU 30, you can use the zpool command to upgrade the version of ZFS pools (zpools) on your system without affecting the bootability of related boot environments (BEs). Also, you can use the beadm command to activate a BE. These commands compare zpool and zfs module pool versions and notify you when a pool upgrade would make related BEs unbootable and when a BE activation would fail.

  • The zpool upgrade command upgrades a zpool that contains BEs to the specified system pool version. By default, the zpool is upgraded to the highest supportable pool version. However, if the upgrade would leave any related BEs unbootable, the upgrade fails.

    Note:

    You cannot downgrade a zpool to an earlier version. If you attempt to import a zpool that has a version that is greater than the version of the zfs module, the operation fails.

    You can use the zpool upgrade -f command to force a zpool upgrade that would otherwise fail. However, if an active-on-boot BE would become unbootable if you update the zpool version, the zpool upgrade command fails even if you specify the -f option.

    Additionally, the zpool command has a -n option that performs a dry-run of an operation, such as an upgrade. The dry run of the operation reports the actions it would take without taking those actions.

    Note:

    You can no longer use the zpool set -o version= version command to upgrade a bootable zpool. Instead, you must use the zpool upgrade command.

  • The beadm activate command activates a BE as long as the version of the ZFS pool is less than or equal to the pool version of a BE's zfs module, otherwise the BE is unbootable.

Example 5-2 Upgrading Pool Versions of ZPools That Contain Boot Environments

This extended example shows how to use the zpool and beadm commands to upgrade the pool version of the rpool zpool that contains BEs. The example shows what happens when pool versions do not match and render related BEs unbootable and how you can address the situations.

The following command attempts to upgrade the versions of the zpools to the highest workable version, which is same as the system (zfs module) pool version of 47. This command also determines that the rpool pool is Version 44 and thus out of date. 

# zpool upgrade
This system is currently running ZFS pool version 47.

The following pools are out of date, and can be upgraded.  After being
upgraded, these pools will no longer be accessible by older software versions.

VER  POOL
---  ------------
44   rpool

Use 'zpool upgrade -v' for a list of available versions and their associated
features.

The following command attempts to upgrade the rpool pool version from 44 to 47 and determines that the resulting upgrade would make related BEs unbootable. 

# zpool upgrade rpool
This system is currently running ZFS pool version 47.

rpool is on version 44 and will not upgrade without making BEs un-bootable

To determine which BEs would be affected by the pool version upgrade, the following command performs a dry run of the previous command.

The output shows the following list of affected BEs and their pool versions.

# zpool upgrade -n -V 47 rpool
This system is currently running ZFS pool version 47.

Upgrading to version 47 will make these BEs un-bootable
FMRI           Pool Version
-------------- ------------
be://rpool/BE1 44          
be://rpool/BE2 45          
be://rpool/BE3 46          
use "zpool upgrade -f -V 47 rpool" to force the upgrade.

The following command attempts to force the upgrade of rpool to Version 45 and determines that the upgrade would make the be://rpool/BE1 BE unbootable. The command does not perform the upgrade. 

# zpool upgrade -V 45 rpool
This system is currently running ZFS pool version 47.

Upgrading to version 45 will make this BE un-bootable
FMRI           Pool Version
-------------- ------------
be://rpool/BE1 44          
use "zpool upgrade -f -V 45 rpool" to force the upgrade.

The following command forces the upgrade of rpool to Version 45. Because the be://rpool/BE1 BE would remain at Version 44, it becomes unbootable. 

# zpool upgrade -f -V 45 rpool
This system is currently running ZFS pool version 47.

Upgrading to version 45 will make this BE un-bootable
FMRI           Pool Version
-------------- ------------
be://rpool/BE1 44          
Pool 'rpool' upgraded from version 44 to version 45

When a zpool version is greater than the version supported by a BE, that BE is unbootable and can no longer be activated. The beadm list output shows an exclamation mark (!) in the Flags column for unbootable BEs.

The following command attempts to activate BE1 and states that the BE is no longer bootable because of mismatched versions. 

# beadm activate BE1
Unable to activate BE BE1:
BE BE1 supports version 44, pool version is 45

If the BE that is active on next boot becomes unbootable, you cannot force the upgrade the pool version by using the -f option.

The following command successfully activates the BE2 BE: 

# beadm activate BE2

The following command lists information about existing BEs. The -o option enables you to specify the type of BE information to show: its name, pool version, and state flags. See the beadm(8) man page. 

# beadm list -o name,pool_version,flags
BE Name          Pool Version Flags 
---------------- ------------ ----- 
BE1              44           !     
BE2              45           R     
BE3              46           -     
beadm            47           N     
solaris          47           -     
solaris-backup-1 47           -

The following command attempts to upgrade rpool to Version 46, but because this command would make BE2 unbootable, the command does not perform the upgrade. 

# zpool upgrade -V 46 rpool
This system is currently running ZFS pool version 47.

Upgrading to pool version 46 would make the active on boot BE 'BE2' un-bootable

The following command forces the upgrade of rpool to Version 46 and makes BE2 unbootable. 

# zpool upgrade -V 46 -f rpool
This system is currently running ZFS pool version 47.

Upgrading to pool version 46 would make the active on boot BE 'BE2' un-bootable

The following command attempts to upgrade the rpool2 pool to Version 46. Because this command would make the TestBE BE unbootable, the command does not perform the upgrade. 

# zpool upgrade -V 46 rpool2
This system is currently running ZFS pool version 47.

Upgrading to version 46 will make these BEs un-bootable
FMRI             Pool Version
---------------- ------------
TestBE           45
use "zpool upgrade -f -V 46 rpool2" to force the upgrade.

As long as the upgrade of the zpool does not make related BEs unbootable, the zpool is upgraded.

The following command destroys the TestBE BE. Because this BE is active on boot, the active BE, be://rpool/beadm, becomes active on boot. 

# beadm destroy -F TestBE
Warning: BE to be destroyed is the active on boot BE.  Making current active BE, be://rpool/beadm, to be the active on boot BE.

The following command succesfully upgrades rpool2 to Version 46 because the previously unbootable BE, TestBE, no longer exists. 

# zpool upgrade -V 46 rpool2
This system is currently running ZFS pool version 47.

Pool 'rpool2' upgraded from version 45 to version 46

The following command fails to upgrade rpool2 to the highest possible version because upgrading the pool would make other BEs unbootable. 

# zpool upgrade rpool2
This system is currently running ZFS pool version 47.

rpool2 is on version 46 and will not upgrade without making more BEs un-bootable

You can perform a dry-run of the previous command to discover the affected BEs.