Sunday, July 1, 2012

Keeping Your OpenBSD System In Trim: A Works For Me Guide

Keeping your OpenBSD systems in trim is dead easy. Occasional reboots are inevitable, but then that's where our famous redundancy features really shine, right? Read on for notes on upgrading your system.

My upgrades always start with the same couple of commands:

$ cd ~/upgrade
$ ls -l
$ ncftp eu-openbsd
ncftp ...penBSD/snapshots/amd64 > dir

The first two commands of this sequence show me the date of the latest snapshot I downloaded, and the next two give me the date on what is on the OpenBSD European mirror site.

The ncftp bookmark eu-openbsd in this case expands to

which is appropriate for a North European like myself with an AMD64 based system on hand. If you're not in Europe, it's likely you're better of with some other choice of mirror. Check the Getting Releases page on the OpenBSD site for a mirror near you. And of course, do pick the correct architecture for your system.

If the files on the mirror server are newer than the ones I have locally, I'll download them with

ncftp ...penBSD/snapshots/amd64 > get *

If there are no updates, well, that means I'll just check back later.

And of course, if you do not have the ncftp package installed, this command will work on any OpenBSD box with a full base system installed:

$ ftp -ia`uname -m`/{index.txt,*tgz,bsd*,INS*}

(thanks, Pedro Caetano!)

One of the things that makes doing OpenBSD upgrades so amazingly easy is the sysmerge(8) program.  Much inspired by FreeBSD's classic mergemaster(8), this program is, as we shall see by executing the following commands,

$ which sysmerge
$ file `which sysmerge`
/usr/sbin/sysmerge: Korn shell script text executable

actually a shell script that makes extensive use of sdiff(1) to highlight the differences between your installed version of a configuration file and the one from the source tree or your install sets, and offers to merge (hence the name) your current customizations into the newer version files and install them on the spot if you like.

Do take a peek with at what the script does:

$ less /usr/sbin/sysmerge

possibly complemented by looking up the sdiff(1) man page if you want.

Or, if you just want to get on with the upgrading, you can do what I tend to do (in a slight deviation from orthodoxy) and -- making sure to check that your $PWD (present working directory) is the directory where you just downloaded the fresh install sets -- run this command:

$ sudo sysmerge -s etc52.tgz -x xetc52.tgz

which says to sysmerge, take as your source the files in the etc52.tgz and xetc52.tgz sets and perform the merge.

Note: (update 2014-11-27) - In recent snapshots (post OpenBSD 5.6), the etc and xetc sets are gone, merged into the base and xbase sets respectively. It's also recommended to run sysmerge with no arguments after you've rebooted into your freshly upgraded system.

This of course reveals that at the time of writing, the system where I'm doing the merge is already running OpenBSD 5.2-beta snapshots, if you use these notes as a reference for some other version, please do insert the file names as they exist on your system.

If you run regular upgrades like I tend to, with snapshots only days or at most a few weeks apart, the differences sysmerge(8) detects are likely few and trivial (but a word of caution: it usually pays to check the Following -current page from time to time). During the last few upgrades of my laptop, for example, the only merge I needed to do was to OK cranking the CVS id and carrying over my choice of smarthost as specified in /etc/mail/

If you do longer jumps, such as between releases, you will almost certainly find more differences, and in rare cases the changes in the configuration file baselines will be large enough that you will need to take some time out to edit the files by hand. In those cases, studying the upgrade notes relevant to your versions (and all intermediate ones if you do a long jump -- go to and choose the Upgrade Guide link at the top of the left column) will be well worth your time.

With a successful sysmerge(8) run completed, my next step is to copy the fresh bsd.rd to the root directory of my boot disk:

$ sudo cp bsd.rd /

With the bsd.rd in place, the next step is to reboot your system. Either choose your window manager's reboot option or simply from a shell prompt type

$ sudo reboot

When the boot> prompt appears, type b bsd.rd and press Enter.

The familiar bsd.rd boot messages appear (much like the ones illustrated in my earlier installation piece, The Goodness Of Men And Machinery), and the first question you need to answer is:

(I)nstall, (U)pgrade or (S)hell?

Since we're upgrading, we type u (upper or lower case doesn't matter) and press Enter.

The next question up is the choice of keyboard layout:

Choose your keyboard layout ('?' or 'L' for list)

Here I type no for my Norwegian keyboard layout, if you want a different one you can get a list of available choices by typing L instead, and pressing Enter.

Once you've chosen your keyboard layout, the upgrade script prompts you to specify where your root file system is located. I've never seen the upgrader guess wrong, so more likely than not you'll just press Enter here.

The upgrader performs a full file system check on the designated root file system, and proceeds to configure any network interfaces it finds configuration files for in the designated root file systems etc directory. You will see the output of DHCP negotiations or similar.

When the network configuration is done, the upgrader prompts you to decide whether you want to perform a full file system check on the other partitions it finds.  The default choice here is no, so if you press enter here, the upgrade script simply runs a fsck -p on each of the file system listed in the system's fstab. You'll see the output for each one of these relatively lightweight checks.

Next, the upgrade script asks where to find the install sets:

Location of sets? (cd disk ftp http or 'done') [cd]

Here, since I already downloaded the install set files to a local directory, the natural choice is disk. The upgrade script has already mounted all partitions from the system's fstab under /mnt/, so the files I downloaded to /home/peter/upgrade are now available under /mnt/home/peter/upgrade, and that's what I type in response to the prompt for where the sets are to be found.

Unless you have prepared a site.tgz for your site there is normally no reason to add or subtract sets from the default list, so pressing Enter will do nicely. The sets are copied and extracted, and when the extraction is done, you confirm that the upgrade is [done], and when the # shell prompt appears, type

# reboot

to let the system boot into the upgraded operating system.

Watch the system boot, log in and then, in case the updated sysmerge(8) program includes some new magic, re-run the sysmerge command using the etc and xetc sets:

$ cd ~/upgrade
$ sudo sysmerge -s etc52.tgz -x xetc52.tgz

(Again, as noted earlier, on post-5.6 snapshots, running sysmerge with no arguments is the recommended action)

That's it! There is a chance that there have been updates to packages you have installed (such as ncftp in my case), so I tend to do a package upgrade pretty soon after rebooting into a freshly upgraded system. The basic update command is pkg_add -u, but I tend to want more verbose output and prompts and generally choose this variant:

$ sudo pkg_add -vui

This command will work significantly better if you have set your the environment variable PKG_PATH to something sensible such as the proper release and architecture packages directory on your most local mirror site.

For upgrading from one snapshot to the next, there is really not much more to the process. If you're upgrading from one release to the next, it makes sense to check the Errata page for any patches you need to apply to the release you're running.

An if you've read this far and found this interesting or useful, please head over to the OpenBSD sites Orders page and buy a few items such as CD sets, T-shirts, posters and books, or follow the instructions on the Donations page to make a donation to the project.


  1. Good article, do packages get security updates within the same release?

  2. A small typo, it's

    sudo pkg_add -vui

    1. Fixed, thanks!

      I can't imagine how I managed to make that error, but I guess it happens every now and then.

  3. Thank you for this nice article!
    Please let me drop my suggestion to use base ftp to download the necessary files instead of ncftp:
    ftp -ia{index.txt,*tgz,bsd*,INS*}

    1. Thanks! I amended the text slightly (and made the one-liner even more portable).

  4. I agree with Pedro. I didn't have ncftp installed, and your howto article would be more fullproof if it could be run on any OpenBSD installation by writing it to use ftp instead of ncftp. Either way, I got the gist, and thank you for this article! :)

  5. Why do you bother starting the process with sysmerge if your going to run it again after installing the install sets?

    1. Running your installed sysmerge before running the upgrade will catch any differences between the *etc.tgz sets and the installed files, so your configuration at fresh reboot will most likely be good.

      However, there's a chance (how big depends on how far you are jumping) that the new sysmerge will include information that the older version did not have. For most snapshot-to-snapshot jumps, the second sysmerge run doesn't make any changes.

  6. So if I understand it correctly, the main benefit of running sysmerge before and after the update is one less reboot (assuming the second sysmerge didn't make any significant changes.)

  7. Peter,
    This was great. It's a little different with OpenBSD 5.5, but as usual the man pages are helpful. Your article helped me "connect the dots." Thanks for pointing out ncftp.

  8. Perhaps add an instruction to check before doing the upgrade ?


Note: Comments are moderated. On-topic messages will be liberated from the holding queue at semi-random (hopefully short) intervals.

I invite comment on all aspects of the material I publish and I read all submitted comments. I occasionally respond in comments, but please do not assume that your comment will compel me to produce a public or immediate response.

Please note that comments consisting of only a single word or only a URL with no indication why that link is useful in the context will be immediately recycled so those poor electrons get another shot at a meaningful existence.

If your suggestions are useful enough to make me write on a specific topic, I will do my best to give credit where credit is due.