How to Upgrade OpenBSD and Build a Kernel
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
command along with the needed public keys in the
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
key collection, upgrade to every release
and you can always verify things as you go.
This is better than the Linux kernel signing model!
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),
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
and download the appropriate bootable image
the digitally signed list of SHA-2-256 hashes
of those image files.
The file from the release directory
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
If there has been any change (or addition or deletion)
to the file,
signify exits with the message
"signature verification failed."
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
SHA256.sig file, you will see "FAIL"
for the missing files as in my example.
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 UpgradeUpgrade
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...
Install the Source Code
All the building and rebuilding on OpenBSD goes on under
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
# 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
to reflect your release minus the decimal point.
Download the archive of all those patches,
let's assume you also saved it to
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
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,
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
GENERIC contains the kernel
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
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:
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.
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=300Virtualization
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 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:
That will take a few minutes, and should eventually
result in a binary named
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
ls command to the boot prompt.
And you don't even have to remember that,
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 /obsdRunning OpenBSD
on old laptops
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
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!I got lost!
Take me back to
the kernel build!
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
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.
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
and possibly others named
+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
@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
This is pretty well hidden from the administrator,
you only see hints of what's going on when you pass
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
file — the
pkg_add program wouldn't
have installed the package if they hadn't matched those
in that digitally-signed list!
If you use the KDE display manager
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
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
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
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.