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.

For an automated version of the procedure below, you can use the platform-upgrade script.

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 MD5 sum shown above corresponds to the 'latest' build at the time of this writing: 20140111T020931Z
The above links are out of date. Please see this document for the correct link.

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.

The first partition of the USB key device (c1t0d0) contains the pcfs fileystem we're looking for. Mount it:

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 edit the GRUB boot command:

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 /20130307T214308Z/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 /20130307T214308Z/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.

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
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.