Upgrading SmartOS when installed in your harddisk


Installing SmartOS in your harddisk is a not supported configuration. Be careful and try to understand what are you doing.

SmartOS is designed to boot from USB, DVD or PXE. Nothing is installed in the harddisk, only your configuration and data. Upgrading the SmartOS hypervisor is, therefore, trivial and risk free and rollback safe.

In Installing/booting SmartOS in/from a harddisk without physical access I describe a procedure to install SmartOS in your harddisk when you have no physical access to your server. This is very important to me because I want to run SmartOS on hosted servers that I have never actually seen in real life.

To upgrade SmartOS in this configuration you can do this:

  1. Write down the release of SmartOS that you are using. For instance, you can run this in the global zone:

    # uname -a
    SunOS xXx 5.11 joyent_20160915T211220Z i86pc i386 i86pc
  2. Visit SmartOS Changelog. Joyent publishes an SmartOS update every two weeks. Evaluate the changes from your version.


    Some versions are marked as toxic. You SHOULD NOT use those releases.

  3. You could download the last release but I rather prefer to download a month old version to be sure I will not run a toxic release.

    You have two choices:

    1. You can download and install the ISO image:

      # cd /tmp
      # wget --no-check-certificate https://us-east.manta.joyent.com/Joyent_Dev/public/SmartOS/smartos-latest.iso
      # mount -F hsfs smartos-latest.iso /mnt
      # zfs create arranque/os/20161013
      # cp -a /mnt/platform/ /arranque/os/20161013/
      # vi /arranque/boot/grub/menu.lst

      Here we download the last SmartOS ISO image release, mount it and copy the platform directory to a new ZFS dataset in the arranque ZPOOL.

      Finally, we edit /arranque/boot/grub/menu.lst to make the new version the default boot version.


      arranque is the spanish translation of boot.


      Note that we are downloading the SmartOS release with no authentication. This is a bad practice, but SmartOS global zone doesn't have a Certificate Authority repository installed.

      The right approach would be:

      1. Download the image twice: in the SmartOS global zone and in your laptop. In the laptop you don't disable authentication. If everything goes well, you are sure the version downloaded in your laptop is legitimate.
      2. Now we need to be sure both downloads are the same file. The simplest way is to compare hashes of both files.
    2. You can download the platform directory directly:

      # wget --no-check-certificate https://us-east.manta.joyent.com/Joyent_Dev/public/SmartOS/platform-latest.tgz
      # tar xvfz platform-latest.tgz
      Decompressing 'platform-latest.tgz' with '/usr/bin/gzcat'...
      x platform-20161013T025521Z, 0 bytes, 0 tape blocks
      x platform-20161013T025521Z/root.password, 17 bytes, 1 tape blocks
      x platform-20161013T025521Z/i86pc, 0 bytes, 0 tape blocks
      x platform-20161013T025521Z/i86pc/amd64, 0 bytes, 0 tape blocks
      x platform-20161013T025521Z/i86pc/amd64/boot_archive, 278528000 bytes, 544000 tape blocks
      x platform-20161013T025521Z/i86pc/amd64/boot_archive.manifest, 1214588 bytes, 2373 tape blocks
      x platform-20161013T025521Z/i86pc/amd64/boot_archive.hash, 41 bytes, 1 tape blocks
      x platform-20161013T025521Z/i86pc/amd64/boot_archive.gitstatus, 1230 bytes, 3 tape blocks
      x platform-20161013T025521Z/i86pc/kernel, 0 bytes, 0 tape blocks
      x platform-20161013T025521Z/i86pc/kernel/amd64, 0 bytes, 0 tape blocks
      x platform-20161013T025521Z/i86pc/kernel/amd64/unix, 2051344 bytes, 4007 tape blocks

      The rest of the process and the security considerations are similar to the first procedure. This second procedure has the advantage that release ID is in the name of the extraction directory, so it is more difficult to make a mistake.

You have made a mistake!

If you have made a mistake and the machine doesn't boot (for instance, you made a mistake while editing /arranque/boot/grub/menu.lst), you could do this:

  1. Boot the remote server in "rescue" mode. Use FreeBSD recent release option.

    We do this because recent FreeBSD releases support ZFS and my hosting company supports FreeBSD as a "rescue" environment.

  2. Connect by SSH to that "rescue" environment and modify /arranque/boot/grub/menu.lst to boot the old working SmartOS hypervisor:

    # zpool import arranque
    # vi arranque/boot/grub/menu.lst
    # zpool export arranque
  3. Reboot.

    You are back!.

  4. Solve whatever mistake you have done and try again.


    Maybe you can solve the issue directly in the "rescue" enviroment in point 2. For instance, a typo in /arranque/boot/grub/menu.lst.

Your boot ZPOOL is full

If you followed steps in Installing/booting SmartOS in/from a harddisk without physical access, your arranque ZPOOL is a gigabyte in size. With current SmartOS release sizes, you can keep three independent versions. My advice is to keep at least two releases: the known old working version and the new version you want to boot from now. So you can go back if you find any kind of issue.

If your arranque ZPOOL is full, you need to delete something. Usually the oldest SmartOS you don't use anymore:

# vi /arranque/boot/grub/menu.lst
# zfs destroy arranque/os/20160915

We edit /arranque/boot/grub/menu.lst to delete booting from that SmartOS release.

Ok. When should I upgrade my SmartOS Hypervisor?

Joyent publishes a new SmartOS release every two weeks. Installing the bleeding edge is risky because some releases are faulty. Joyent marks such releases with a toxic tag. Avoid them. Since such toxic releases could not be recognized as such when published, my approach is to install at least a month old release, not the last release.

What about security?

SmartOS is a hypervisor. It doesn't run user processes, production code. That is something you run inside Solaris containers. In the global zone of a SmartOS instance you only have NTP, SSH, a NAT/firewall and maybe a handful of VNC instances showing KVM Solaris containers accesible from the network. You don't run a database or a webserver in the SmartOS global zone.

You don't usually have security issues in SmartOS hypervisor.

What I personally do is to check new SmartOS releases every two weeks and see if there is a security fix, a fix of an issuing I am experiencing or a new feature I am interested in. When that happens, upgrading is a priority. When it is not the case, upgrading is not needed and I rather prefer to avoid the effort and the downtime.

Even in that case, I usually upgrade the SmartOS release I am running once or twice per year, just because general improvements and spring cleaning.

Note that upgrading SmartOS is something you can undo simply editing the text file /arranque/boot/grub/menu.lst. Risk free. The only downside is the downtime while the server reboots.