Managing ZFS boot environments with beadm and rolling back a failed update

Goal

List, create, activate and destroy ZFS boot environments (BEs) on Oracle Solaris 11.4, and use them to recover a host after a pkg update that turned out badly.

Prerequisites

Root role or an assigned profile with rights to manage boot environments; a ZFS root pool, which BEs require and which is the default and only supported root layout on 11.4.

Steps

1. List what exists: beadm list shows every boot environment, which one is active now, which is active on next boot, and its space usage.
2. Create a BE by hand before a risky manual change: beadm create <new-be-name> clones the currently running BE without touching the running system. Note the two snapshot forms: beadm create <be-name>@<snapshot> only takes a snapshot of an existing BE, while beadm create -e <be-name>@<snapshot> <new-be-name> creates a new BE from such a snapshot.
3. Let pkg create one automatically: as described in the IPS article in this series, pkg update creates and activates a new BE when the update touches packages that require a reboot (any SRU update does), governed by the image's be-policy property; operations that need no reboot change the running BE, at most with a backup BE.
4. Activate a BE so it boots next time: beadm activate <be-name>. This does not reboot the host; the currently running BE keeps running until the next reboot.
5. Reboot to actually switch to the newly activated BE, then confirm with beadm list that it is now the currently active one.
6. If the new BE is broken but still boots: beadm activate <previous-be-name> and reboot again. If it does not boot at all, beadm cannot run inside it: select the previous BE at boot time instead — from the GRUB menu on x86, or with boot -L at the ok prompt on SPARC — then, once booted, run beadm activate <previous-be-name> so later reboots do not return to the broken BE.
7. Clean up once you trust the result: beadm destroy <be-name> removes a boot environment you no longer need, together with all of its snapshots; it asks for confirmation (-F skips the prompt) and cannot remove the BE you are running.

Expected result

After beadm activate and a reboot, beadm list shows the target BE active and the host running the software that BE contains; a destroyed BE no longer appears in the list and its space is reclaimed.

Limits and test basis

Activating a prior BE and rebooting is the supported rollback for a bad pkg update — no manual package reinstallation is needed. Keep at least the previous BE until the new one is verified in production; beadm destroy has no undo beyond restoring from a backup of the pool. Because BEs share the root pool, destroying old ones is also how you reclaim space if pkg update is refused for lack of room. A rollback reverts only the BE's own datasets (root file system and /var); shared datasets such as /export/home or /var/share are not rolled back, so data written there after the update stays. This covers Oracle Solaris 11.4; illumos-based systems that use ZFS boot environments follow the same activate/reboot/rollback pattern, though tool names and options can differ.