OpenBSD’s release schedule for many years has been on a regular cadence of every 5-8 months. Consequently, the upgrade process is well thought out and fairly consistent, and exercised regularly. It’s delightfully simple and very staightforward–if you’re using “normal” hardware. I’m using it as a network appliance/router/firewall on an EdgeRouter 4, with an octeon processer and very little storage.

Collect the Tools

OpenBSD upgrades are designed to be run in-place, and within each release cycle. It’s been simplified over time to consist primary of running the “sysupgrade” command and then waiting for the automated processes to complete. Again, this is very easy and simple for “normal” hardware. For a headless system without adequate storage for the upgrade sets, additional steps are required. They will make use of the following:

  • USB Thumbdrive, 4GB
  • USB/Serial cable, with RJ45 connector
  • A second system to use as a serial terminal, WITH SCREEN ALREADY INSTALLED!!

Run the Process

First, add the thumbdrive and mount it. If it’s not already initialized, run the following:

 disklabel sd1
 newfs_ffs sd1c
 mount /dev/sd1c /home/_sysupgrade

Add an entry for this mount to /etc/fstab. That’ll be important later. NOTE: use the disklabel UID for the disk, not the simple name.

Next, run sysupgrade. The first phase of downloading and verification will probably take 7-15 minutes. Then the system will reboot into the upgrade kernel, and you’ll need the serial cable. Probably.

Watch for Gotchas

Disk enumeration is sometime inconsistent. If there’s no USB storage, the internal MMC enumerates as sd0. If there is, then the internal MMC will probably show up as sd1. This will confuse the OpenBSD bootloader, and will result in a something of a hanging loop. Or looping hang. Or something. You’ll need to manually kick it out of this cycle.

Connect the to the serial console

I have a RJ45-serial-console-to-usb cable. One end goes into the “console” port on the edgerouter, and the other end goes into my laptop. The port settings were set during the initial OpenBSD install a few years ago, so connecting via the usb cable consists of

 screen /dev/ttyUSB0 115200

Update the parameters passed to the bsd bootlader by uboot

This took a while to sort out. The edgerouter has uboot, with a linux-centric perspective. During the initial install, I set the requisite parameters and then forgot them all. They’re in the OpenBSD Octeon Install Guide, but slightly different. In my case, I had to pass a parameter from uboot to the bsd bootloader to specify that the kernel lived on sd1, instead of the normal sd0. In the uboot console:

fatload mmc 0 ${loadaddr} boot
bootoctlinux rootdev=dev/sd1

This pointed the kernel to the right volumes to proceed with the sysupgrade process. I think this had to be done twice during the upgrade.

Once the bsd.upgrade kernel loads, it’s automatic. The file copies are very slow though, so assume 15-25 minutes for this part.

Finish and Cleanup

At some point, there will probably be a notification on the screen that your system is upgraded and everything is peachy. At that point, unmount /home/_sysupgrade and remove its entry from /etc/fstab. Then continue on with package upgrades, which can take zero to many minutes:

 pkg_add -u

Remove the USB Storage and reboot. If it comes up cleanly, you’re done! [^*]

Repeat in six months

It’ll be fun. Seriously.

[^*] except for any daemons that are started/stopped via crontab. You’ll need to check those.