How to Upgrade OpenBSD and Build a Kernel

Upgrading OpenBSD

Let's see how to upgrade your OpenBSD system. Maybe you are doing this because the latest release just came out. If so, this is pretty simple: back up your data, boot from install media, and select "Upgrade" instead of "Install". But maybe the latest release has been out for a few months. Why would we go through the trouble of building and installing a new kernel or other core system components? Maybe some patches have been released to improve system security or stability. It is pretty easy to build and install a kernel on OpenBSD, easier and simpler in many ways than it is on Linux.

Verify that You Have the Real Operating System

If you purchase OpenBSD media then you have the real operating system. But what if you download it?

From the 5.5 release forward, you have the signify command along with the needed public keys in the /etc/signify directory. The OpenBSD project generates the key pair for the next release ahead of time, so you already have the public key for the next release. Once you have a trusted /etc/signify key collection, upgrade to every release and you can always verify things as you go.

This is better than the Linux kernel signing model! At the Linux kernel archive there is a digital signature file accompanying every kernel source code archive or patch file, but there is no clear mechanism for getting a trustworthy copy of the kernel organization's public key. The kernel.org site has some hand-waving about using a web of trust for PGP keys, then they tell you to track down a kernel developer in person and sign each others' keys. That's accompanied by a link to a Google map which absurdly tags a spot in the middle of the Atlantic Ocean as Cambridge, Massachusetts, one of the outer Aleutian Islands as Austin, Texas, and a spot in the White Sea off the Kola Peninsula as Oldenburg, Denmark. The most help I can provide you regarding the validity of the PGP signing key for the Linux kernel is that I'm convinced that it's key ID 0x6092693E with a fingerprint of:
647F 2865 4894 E3BD 4571 99BE 38DB BDC8 6092 693E
I'm convinced because that key has been used to sign the kernel source code for a number of years with no announcement of the site being hacked or the signing key being bogus.

But the good news with OpenBSD is that we have the security tools and keys in place. So, let's use them! Make sure you also download the file SHA256.sig accompanying the installation archives or source code archives.

If you are preparing to patch a kernel or other parts of the core system (applications, shared libraries, etc), or if you want to build or update any of the ports, go to the appropriate release directory /pub/OpenBSD/X.Y and download files sys.tar.gz (the kernel), src.tar.gz (the rest of the core system), ports.tar.gz (ports), xenocara.tar.gz (X11R6), and also SHA256.sig, the digitally signed list of SHA-2-256 hashes of those archives.

If you are preparing an upgrade to a new release, go to the appropriate architecture-specific directory /pub/OpenBSD/X.Y/arch and download the appropriate bootable image cdXY.iso or installXY.iso, and also SHA256.sig, the digitally signed list of SHA-2-256 hashes of those image files. The file from the release directory /pub/OpenBSD/X.Y looks like this:

untrusted comment: signature from openbsd 5.8 base secret key
RWQNNZXtC/MqP81JgUxPz7/2d027cC49DG9Fq3gMJw52ZPlXy3pljMWTS74FmZ8lsQd2UdPKzzVp2Qp/52NEsct0s5PTDO+gjAo=
SHA256 (ANNOUNCEMENT) = 1c4da371cf3138fafaac641b3c1030f67f4d73d5bcaa93318294007ae1a97304
SHA256 (HARDWARE) = 53eb55118bb57e2e94d3b9898819c959b8e7200537221cbee30c6797bac269f9
SHA256 (PACKAGES) = cbc0964b2af61a8a8ec7b80174abd6d1a924663a03247b9687d76e5a65fef74e
SHA256 (PORTS) = e8db12ce270e89289d71e6d6cc9e42b6f15d01ef305fe35bc2ec788f0b483bff
SHA256 (README) = 6d06b16db5b6fe3b0b33af42b53296512710bbbeebe53509f89968de2fac4d78
SHA256 (cd-src.tar.gz) = 74f1fe9a1ae3220ac6de30bf68e21a316f4bb5d7a465e8e2848977cf05f3b3fa
SHA256 (root.mail) = 0c89c7c9536760208c5ef33dd88cc9d2b1bd8270e26901177e7a39d9980c6c16
SHA256 (ports.tar.gz) = 9e840a89f84caca92be2b8dcbd4369ba1f96a1254473f59ed22da25649f4a9c1
SHA256 (xenocara.tar.gz) = 909244ce6aaa1a088b32dab77079c0a510856e299965e5e39f320972f53732bf
SHA256 (src.tar.gz) = f3aee386ca66479d81a100860d64eb357a68a8c26b1e6edfbe184abd66954985
SHA256 (sys.tar.gz) = 78a4b191af0cd3121691fae05619e3a89938df1e89ff913d3c54aea0af490643

Now we can verify that we got the real software from the real OpenBSD project:

$ signify -C -p /etc/signify/openbsd-XY-base.pub -x SHA256.sig 

The way that this works is that the second line of the SHA256.sig file is a signature for the file itself. If there has been any change (or addition or deletion) to the file, signify exits with the message "signature verification failed."

If the SHA256.sig file is good, you see "Signature Verified" and then one line for each of the listed files with its name and then "OK" or "FAIL". Here's the result of downloading just three archive files and using both a good signature file and one in which I changed one character of the hash for a file that I hadn't even downloaded:

$ signify -C -p /etc/signify/openbsd-XY-base.pub -x SHA256.sig
Signature Verified
ports.tar.gz: OK
src.tar.gz: OK
sys.tar.gz: OK
xenocara.tar.gz: OK
cd-src.tar.gz: FAIL
root.mail: FAIL
HARDWARE: FAIL
PORTS: FAIL
README: FAIL
PACKAGES: FAIL
ANNOUNCEMENT: FAIL

$ diff SHA256.sig SHA256.sig-modified
9c9
< SHA256 (root.mail) = 0c89c7c9536760208c5ef33dd88cc9d2b1bd8270e26901177e7a39d9980c6c16
---
> SHA256 (root.mail) = 0c89c7c9536760208c5ef33dd88cc9d2b1bd8270e26901177e7a39d9980c6c17

$ signify -C -p /etc/signify/openbsd-XY-base.pub -x SHA256.sig-modified
signify: signature verification failed 

Do not proceed until you see "OK" reported for each downloaded file. Of course, if you only downloaded some of the files listed in the SHA256.sig file, you will see "FAIL" for the missing files as in my example. That's fine.

Prepare for the Upgrade

Make sure your data is safely backed up before proceeding.

If you are starting a graphical display manager through /etc/rc.local or another mechanism, disable that temporarily.

Burn the appropriate OpenBSD installation media if you are upgrading to a new release. Boot from that media and select U for "Upgrade", and let it download and install the base operating system.

Finish the Upgrade

Use the sysmerge program to update your configuration files.

If you aren't building a new kernel, skip ahead to the steps needed to upgrade the packages. But if you are going to build a patched kernel...

OpenBSD desktop with Windows XP running inside QEMU.

Install the Source Code

All the building and rebuilding on OpenBSD goes on under the /usr/src/ directory. It is empty when you first install the system. The source for the kernel and the userspace tools go into subdirectories.

Let's say that you downloaded the source code archives to /tmp. Install them:

# gunzip /tmp/*.gz
# cd /usr/src
# tar xvf /tmp/sys.tar
# tar xvf /tmp/src.tar
# cd /usr
# tar xvf /tmp/xenocara.tar

Apply All Patches

Now you need to apply all the patches. They exist for good reasons — to fix problems of stability or security. Apply those patches!

The current patch list will be found at a URL resembling http://www.openbsd.org/errataXY.html, change XY to reflect your release minus the decimal point. Download the archive of all those patches, let's assume you also saved it to /tmp/X.Y.tar.gz. Extract the archive and become root:

$ cd /tmp
$ tar xvfz X.Y.tar.gz
$ su
Password:
# cd X.Y/common
# ls -l 

View each patch file to see its explanation of how to use signify and patch. Just copy and paste that two-line command into place. It will be something like this:

signify -Vep /etc/signify/openbsd-XY59-base.pub -x 011_sshd.patch.sig \
	-m - | (cd /usr/src && patch -p0) 

If the patch is for an application, the patch file comment block will tell you what to do next. Following that is the actual patch content. For example, building and installing the patched code will likely require something like this:

# cd /usr/src/usr.bin/ssh
# make obj
# make depend
# make
# make install 

But if the patch is for the kernel, the patch file will just say "Then build and install a new kernel." Keep reading to see how!

Prepare to Build the Kernel

Change to the appropriate directory, changing amd64 in the following commands as needed to reflect your hardware. OpenBSD runs on a lot of platforms, your choices include:
alpha, amd64, arm, armish, armv7, aviion, beagle, gumstix, hp300, hppa, hppa64, i386, landisk, loongson, luna88k, m68k, m88k, mac68k, macppc, mips64, mvme68k, mvme88k, mvmeppc, octeon, powerpc, sgi, sh, socppc, solbourne, sparc, sparc64, vax, zaurus.

# cd /usr/src/sys/arch/amd64/conf

Examine and Possibly Change the Kernel Configuration

The file GENERIC contains the kernel configuration. It's just a little over 600 lines long, versus the 7,700 or more lines in a recent Linux kernel configuration file.

There are options near the top for support of GPT (GUID Partition Tables, needed for disks larger than 2 TB) and Microsoft's NTFS file system. Simply comment out a line with "#" to disable that option or leave a driver out of the kernel. As an example, I once had to disable (or omit) the apm driver when I was running old OpenBSD on even older hardware.

If you want the change the kernel message colors from the generic white text on a blue background, then first add two lines to:
/usr/src/sys/arch/amd64/conf/GENERIC
I don't care for the default white-on-blue. It looks too much like a Windows crash screen. You can specify the foreground text color (FG) and background color (BG) of console kernel messages:

option WS_KERNEL_FG=WSCOL_BLACK
option WS_KERNEL_BG=WSCOL_BROWN

You don't have many choices. According to:
/usr/src/sys/dev/wscons/wsdisplayvar.h
the only colors are black, red, green, blue, brown (really a dark yellow), magenta, cyan, and white. For what it's worth, white on green is kind of hard to read. Black on brown is as close to Purdue gold and black as it gets.

If you are multibooting with Windows, realize that OpenBSD assumes that the hardware clock is set to UTC while Windows assumes it is set to the local time. You can set the hardware clock to local time and then specify the OpenBSD kernel's offset in minutes. I live in the US-EST time zone, 5 hours or 300 minutes behind UTC, so I could set the hardware clock to US-EST and then do this:

option WS_KERNEL_FG=WSCOL_BLACK
option WS_KERNEL_BG=WSCOL_GREEN
option TIMEZONE=300

However, I don't boot my laptop into Windows very often at all, especially now that I have a Windows virtual machine running under QEMU/KVM on my main Linux desktop. I just set the hardware to UTC, leave out the TIMEZONE option, and tell Windows that it's in UTC.

Build the Kernel

Configure the build with your CONFIG file:

# config GENERIC

Prepare to build, removing any leftover object files and setting up dependencies:

# cd /usr/src/sys/arch/amd64/compile/GENERIC
# make clean
# make depend

Build the kernel:

# make

That will take a few minutes, and should eventually result in a binary named bsd. On my system with a Intel Celeron 900 running at 2.2 GHz, it takes almost 6 minutes.

Install Your New kernel

This just takes one command, and watch what it does:

# make install
cmp -s bsd /bsd || ln -f /bsd /obsd
cp bsd /nbsd
mv /nbsd /bsd

If the new kernel file is different from the currently installed one, some files are shuffled around so that /bsd is the new kernel and /obsd is the previous one. That way, if some inappropriate changes in your kernel configuration file led to a dysfunctional kernel, you can reset the system and ask for the old one.

Reboot and Enjoy!

That should just simply work!

If it didn't, remember that you can ask for the old backup kernel at the boot prompt. And you don't have to remember its name, you can ask with the ls command to the boot prompt. And you don't even have to remember that, h gets you a list of the available boot prompt commands:

Using drive 0, partition 3.
Loading...
probing: pc0 apm mem[632K 3001M 780K 124K 36K a20=on]
disk: hd0+
>> OpenBSD/amd64 BOOT 3.28
boot> h
commands: # boot echo env help ls machine reboot set stty time
machine: boot comaddr diskinfo memory
boot> ls
drwxr-xr-x 0,0  512     .
drwxr-xr-x 0,0  512     ..
drwxr-xr-x 0,0  512     home
drwxr-xr-x 0,0  512     tmp
drwxr-xr-x 0,0  512     usr
drwxr-xr-x 0,0  512     var
-rwxr-xr-x 0,0  9975220 bsd
-rw-r--r-- 0,0  7642500 bsd.rd
drwxr-xr-x 0,0  512     altroot
drwxr-xr-x 0,0  1024    bin
drwxr-xr-x 0,0  19456   dev
drwxr-xr-x 0,0  3584    etc
drwxr-xr-x 0,0  512     mnt
drwx------ 0,0  1024    root
drwxr-xr-x 0,0  1536    sbin
-rw-r--r-- 0,0  578     .cshrc
-rw-r--r-- 0,0  468     .profile
stat(hd0a:/./sys): No such file or directory
-rwxr-xr-x 0,0  9975220 obsd
-rw-r--r-- 0,0  69652   boot
boot> b /obsd

If you have the APM issue that required a kernel configuration change to install and boot in the first place, then see my page about installing OpenBSD on a Dell laptop to refresh your memory as to how to accomplish this.

The alternative would have been to modify the kernel configuration by editing the file /usr/src/sys/arch/amd64/conf/GENERIC before building a kernel that leaves out that driver.

However, if you are really qualified to modify the kernel configuration before building and installing it, I'm not sure why you're reading this page!

Upgrading Packages

You will need to upgrade all the added packages. It is very easy to upgrade the packages you installed from the OpenBSD distribution:

# pkg_add -u

Many of them will print messages about needed manual steps, and most of those will scrolled off the screen. Display those again, and deal with them:

# pkg_info -aM | less

You will want to remove any leftover "orphaned" or "leaf" packages. These are packages that were installed to satisfy dependencies, but which are no longer needed. First, see what an automated run would remove:

# pkg_delete -a -n

If that looks acceptable, one command will clean them up:

# pkg_delete -a

The core of the operating system, what you get with an installation, has been checked very carefully. The much larger collection of packages, basically those components that will be installed under the /usr/local hierarchy, haven't been checked as carefully. However, at least some design and implementation auditing is done and the packages are digitally signed. Things like the KDE Desktop Environment will be buggier than the plain X desktop provided in the core release, but at least you're getting just naturally occuring bugs and not Trojan Horses.

The pkg_add program checks digital signatures and will only install those with a good signature. You can see what's going on by downloading and extracting the gzip-compressed tar file for a package. You will get the collection of files making up the package plus +CONTENTS, +DESC, and possibly others named +*. The +CONTENTS file contains something like the following from the aescrypt package, which has the security parts highlighted:

@comment $OpenBSD: PLIST,v 1.2 2004/09/15 18:35:59 espie Exp $
@name aescrypt-0.7p0
@signer openbsd-58-pkg
@digital-signature signify:2015-08-09T11:42:52Z:RWRlkI2aFHvL/YZnu9YhbPdOyWg8b73HvaFQiCgBrbwWRyWrqYkzxocPvyzgIviAKAbN2o1D/a1UYW6a4vfcgSAHCBGeu8tOYQo=
@comment pkgpath=security/aescrypt cdrom=yes ftp=yes
@arch amd64
+DESC
@sha Sise4CvlTcCZ3vOao4uR26nPXM31XIzXi80Z2M1XeuA=
@size 416
@wantlib c.80.1
@cwd /usr/local
bin/aescrypt
@sha fnHWBdfHf7WLMR33Mk91jxQ/3yqyoX4j/ixJ4ZNEr5c=
@size 36608
@ts 1438963247
bin/aesget
@sha XARARn2qi0R6udvoXJT6Sx/O5Js4Nx/e1/Zfv80p6ws=
@size 36608
@ts 1438963247
share/doc/aescrypt/
share/doc/aescrypt/README.html
@sha CKtEtiNFdKjbZSi3xyaXoT2Btz2yPlFbDmkTkhApDf8=
@size 4792
@ts 1438963247 

The @digital-signature line contains a digital signature for the +CONTENTS file itself. That digital signature must be valid in order to continue. Now we can trust the @sha lines to tell us the Base64-encoded SHA-2-256 hashes of the components +DESC, bin/aescrypt, bin/aesget, and share/doc/aescrypt/README.html. This is pretty well hidden from the administrator, you only see hints of what's going on when you pass -vvv to pkg_add to tell it to be triply verbose! Let's verify what's happened once the package is installed:

# sum -a sha256 -b /usr/local/bin/aescrypt /usr/local/bin/aesget /usr/local/share/doc/aescrypt/README.html 
SHA256 (/usr/local/bin/aescrypt) = fnHWBdfHf7WLMR33Mk91jxQ/3yqyoX4j/ixJ4ZNEr5c=
SHA256 (/usr/local/bin/aesget) = XARARn2qi0R6udvoXJT6Sx/O5Js4Nx/e1/Zfv80p6ws=
SHA256 (/usr/local/share/doc/aescrypt/README.html) = CKtEtiNFdKjbZSi3xyaXoT2Btz2yPlFbDmkTkhApDf8=

  -- or, alternatively --

# for F in /usr/local/bin/aescrypt /usr/local/bin/aesget /usr/local/share/doc/aescrypt/README.html 
> do
>   echo $F $( sopenssl sha256 -binary $F | base64 )
> done
/usr/local/bin/aescrypt fnHWBdfHf7WLMR33Mk91jxQ/3yqyoX4j/ixJ4ZNEr5c=
/usr/local/bin/aesget XARARn2qi0R6udvoXJT6Sx/O5Js4Nx/e1/Zfv80p6ws=
/usr/local/share/doc/aescrypt/README.html CKtEtiNFdKjbZSi3xyaXoT2Btz2yPlFbDmkTkhApDf8=

Notice that the measured SHA-2-256 hashes agree with what was specified in the +CONTENTS file — the pkg_add program wouldn't have installed the package if they hadn't matched those in that digitally-signed list!

Reconfiguring Packages

If you use the KDE display manager kdm, then you may have fixed it to start an SSH agent at login as described here. You will need to do that again if you want to continue using that method. However, maintenance is easier if you use Keychain instead.

If you are using LaTeX and/or TeTeX in a region of the world with a mutant paper size (like the U.S. and Canada), then you need to run texconfig as root and specify your paper size.

If you are using Wireshark or the command-line tshark, remember to change the devices /dev/bpf* to be readable by a group containing those users who should be able to capture packets in that group. The details are here.

If you have installed KDE, you have almost certainly been stuck with the akonadi package, which will lead to many processes running to index who knows what all, causing your CPU and disk to thrash. I do this as root:

# chmod -x /usr/local/bin/akonadi* 

That leaves me much more CPU and disk I/O bandwidth to use on what I want to do.

Rebuilding Other System Binaries

The above recommendation on downloading, installing, and patching the application source code will have some of the work out of the way. At least you will have patched and trusted source code.

What remains is to build and install the binaries based on the patched code. See the patch files for the details, but this generally requires something like the following, where you would skip the patch application if you have already done it:

# cd /usr/src/path/to/patched/source/code
# make
# make install

If this fails with an error message message about "don't know how to make ...", then you need to clean things up before doing the build. Do the following and then restart building that binary. Notice that the pushd and popd leave you wherever you were before applying this fix:

# rm -rf /usr/obj/*
# pushd /usr/src
# make obj
# popd

Rebuilding Other Open-Source Packages

If you built and installed any open-source packages under the old version, you will need to re-build them to match the current set of shared libraries (and this may involve rebuilding some shared libraries you built and installed). See my pages on building Wireshark, OpenCV, OpenVAS, and RainbowCrack on OpenBSD.