Upgrading from r151006 to r151008


Please upgrade to at least r151014, per here


Important: You must be running r151006 in order to upgrade to r151008. Upgrading from previous releases is not supported.

Pre-Upgrade Preparation

Starting with r151008, packages shipped by OmniOS will be cryptographically signed. In order to be able to install these new packages there are two r151006 package updates that must be applied before attempting an upgrade:

# pkg update package/pkg@0.5.11,5.11-0.151006:20130731T192303Z web/ca-bundle@5.11,5.11-0.151006:20130718T173831Z

The ca-bundle package delivers the OmniTI CA certificate that pkg(1) will use to verify the signing certificate for r151008 packages, and the updated pkg knows where to find this CA certificate.

If you already have these package updates, the above command will indicate that no update is necessary.

Additionally there are a couple other packaging issues that can cause dependency problems during the upgrade. Corrected packages for r151006 have been published, and must be applied to the global zone and all non-global zones prior to upgrading to r151008.

incorporation/jeos/omnios-userland might be missing on your system. If so, the 151006 version of it should be installed in your current BE and any non-global zones before attempting an upgrade:

$ pkg list incorporation/jeos/omnios-userland >/dev/null 2>&1 || pkg install incorporation/jeos/omnios-userland@11,5.11-0.151006

runtime/perl/manual is part of the default install and is always present. All users will need this update:

# pkg update runtime/perl/manual@5.16.1,5.11-0.151006

runtime/perl-64 is an optional package and only needs to be updated if it is installed:

# pkg list runtime/perl-64 >/dev/null 2>&1 && pkg update runtime/perl-64@5.16.1,5.11-0.151006

Note Current BE Name

Make a note of the name of your current boot environment (BE) in case you need to roll back.

$ /usr/sbin/beadm list

It may look something like this:

BE              Active Mountpoint Space Policy Created
omnios          NR     /          1.37G static 2012-09-26 18:26
omnios-backup-1 -      -          211K  static 2012-10-01 14:16
omnios-backup-2 -      -          110K  static 2012-10-18 19:55
omnios-backup-3 -      -          205K  static 2012-10-18 20:02

The current BE is the one marked ‘NR’ (active Now, active on Reboot.)

Perform the Upgrade

If you have non-global native (ipkg) zones, they must be shutdown and detached at this time. Once the global zone is updated and rebooted, the zones will be upgraded as they are re-attached to the system. This is not necessary for s10-branded zones or KVM guests.

After shutting down the zones gracefully (zlogin <zonename>; shutdown -i5 -g0 -y):

# /usr/sbin/zoneadm -z <zonename> detach

It would also be a good idea to take a ZFS snapshot of the zone root in

case it’s needed for rollback (such as if there are issues with the zone upgrade.)

# /usr/sbin/zfs snapshot -r <zoneroot>@r151006

where is the name of the ZFS dataset whose mountpoint corresponds to the value of *zonepath* in the zone's configuration. There are child datasets under this one, so we use the `-r` option to recursively snapshot all.

Update the global zone. The --be-name argument is optional, but it’s nice to use a name that’s more meaningful than “omnios-N”. Add a -nv after the update sub-command to do a dry run if you’re unsure of what will happen.

# /usr/bin/pkg update --be-name=omnios-r151008 entire@11,5.11-0.151008

This will create a new BE and install r151008 packages into it. When it is complete, reboot your system. The new BE will now be the default option in GRUB. If your hardware supports it, you may get into the new BE via fast reboot, in which case you won’t see a GRUB menu.

Once booted into your new r151008 BE, if you don’t have non-global zones, you’re done.

If you have non-global native (ipkg) zones, attach each one with the option, which will upgrade the zone’s core packages to match the global zone.

# /usr/sbin/zoneadm -z <zonename> attach -u

Assuming the attach succeeds, the zone may be booted as usual:

# /usr/sbin/zoneadm -z <zonename> boot

Rolling Back

ZFS Upgrade

OmniOS r151008 includes new zpool feature flags. Post-upgrade you will see a message like this in zpool status:

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.

If you want to be able to roll back to your previous environment, DO NOT upgrade your zpools yet. The upgrade is one-way and irreversible.

If, for some reason, you need to roll back to r151006, simply activate the previous BE and reboot.

# /usr/sbin/beadm activate <be-name>
# /usr/sbin/reboot

Where is the name of the previous BE that you noted at the beginning.

If you have native zones but had not yet attempted to attach them, they remain unchanged from the previous BE and may be re-attached once booted into the previous BE. Simply omit the from the attach example above. Note that even if you tried to attach but the attachment failed completely (perhaps due to a packaging issue), then the zone data remains unchanged and you can still safely re-attach it in the previous BE.

If you are rolling back because there was a problem with the zone attach in which the zone was partially updated, then you will need to roll back each of the zone root datasets that you snapshotted after detachment. There is no recursive rollback, so we have to roll back each of the datasets one at a time.

/usr/sbin/zfs rollback <zoneroot>@r151006
/usr/sbin/zfs rollback <zoneroot>/ROOT@r151006
/usr/sbin/zfs rollback <zoneroot>/ROOT/zbe@r151006