Skip to end of metadata
Go to start of metadata

Exercise Caution

As with any operating system upgrade, there's risk involved with this procedure. In the event that you downloaded a bad platform tarball, or your USB key decides to malfunction, you could be left in a state where your host doesn't come back online. You might want to perform the first upgrade locally to test the build.

Download And Verify the Platform Tarball

Either download directly as shown below, or copy the platform tarball from another location onto the machine you want to upgrade.

The URLs and MD5 sum shown above are for example purposes only.  Please see this document for the correct link and expected MD5 sums.

Find and Mount the USB Key

The diskinfo(1M) command displays information about the physical disks (or other storage devices) attached to the system.  We can use this tool to find the disk device that represents the USB key. By default, the tool will display a table of all disks in the system. Let's filter out just the USB disks:

There may be more than one USB storage device attached to your system. In the output above, the USB key is a SanDisk Cruze Glide – note that the RMV column lists this as a removable device. The other disk (listed as non-removable) is a Seagate Portable hard disk. If more disks are listed, you may need to mount the filesystem from each to determine which one is the correct device.

In order to install the new platform image, we need to mount the root filesystem on the USB key.

The format of the SmartOS USB image changed with the 20190411 release from a Legacy GRUB-based USB key to a Loader-based USB key.  For more details see the following Flag Day Message

If the system is currently using a Legacy GRUB-based USB key, then the key uses the MBR partitioning scheme and the first primary partition of the USB key device (c1t0d0) contains the pcfs fileystem we're looking for.  However, if the system is using the newer Loader-based USB key, then the key uses a hybrid GPT+MBR partition scheme and the filesystem we're looking for will be on slice 2.

Legacy GRUB-based USB key example:

Loader-based USB key example:

Verify that you've mounted the correct partition by examining the contents of the mounted filesystem:

This looks to be correct for a bootable SmartOS USB key, so we'll proceed.

Unpack the New Platform

The warnings from 'tar' may be safely ignored.

We now have two 'platform' directories:

Indiana Jones Style Swap

Now all that's left is to start using the new platform directory. We do this as one atomic operation to minimize risk. We'll also save the old platform directory in an accessible location in case we need to boot back into it.

Unmount the USB key and reboot at your convenience:

If Something Goes Wrong

If you find that the new platform will not boot on your hardware, you'll find error messages on the console.

If you see only a 'Starting up ...' and then your machine reboots, it means you've attached to a serial port instead of the text console.

Using IPMI or a remote keyboard/video system, you'll need to instruct the bootloader configuration to boot the previous platform image:

Instructions for Legacy GRUB-based USB keys:

1. The first menu entry is highlighted by default, press 'e' to edit it.
2. Press 'e' again to edit the 'kernel' line.
3. Using Ctrl-A, go to the beginning of the line.
4. Place a slash ('/') and the version string of your previous platform immediately before the string '/platform', e.g. kernel /previous/platform/... in our example above.
5. Hit <RET> (the 'Enter' key) to replace the line with your edits.
6. Using the down arrow, select the next line, beginning with 'module'.
7. Place a slash ('/') and the version string of your previous platform immediately before the string '/platform', e.g. module /previous/platform/... in our example above.
8. Hit <RET> (the 'Enter' key) to replace the line with your edits.
9. Press 'b' to boot into the old platform.

Instead of the procedure above, we could've edited the boot/grub/menu.lst file on the USB key before unmounting it, and offered another menu item to boot into the old platform. In the majority of cases the new platform will boot just fine, so this effort was considered unnecessary.

Instructions for Loader-based USB key:

1. When thr Loader menu is displayed, press ESCAPE to enter the Loader command prompt.

2. Issue the following command to change the default platform to the previous platform image:

3. Boot the platform

If you get an error message from 'krtld', it means you didn't follow the instructions above and decided to rename the 'platform' directory itself; cf. PXE Booting SmartOS#PXEBootingSmartOS-AddingSmartOSImagestoanExistingPXEEnvironment
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.