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 thezfs
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, thezpool 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 thezpool set -o version=
version command to upgrade a bootable zpool. Instead, you must use thezpool 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'szfs
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.