The OpenBSD Upgrade Process
An OpenBSD upgrade has three distinct phases: installing the newer versions of the operating system files, updating the local configuration, and updating obsolete add-on software packages. Each is a separate part that requires independent handling.
An upgrade requires installation media. The best upgrade media is the new release CD or an Internet mirror. You can also upgrade OpenBSD by building and installing the source code directly on the machine to be upgraded, but doing so is more difficult and risky than upgrading from the official release. Much of the information for upgrading from a network or CD applies to upgrading via source code.
Note
OpenBSD supports upgrading only one major release at a time. You cannot upgrade directly from, say, 5.3 to 5.5; you must upgrade from 5.3 to 5.4, and then to 5.5. The more releases you need to upgrade through, the more reason to reinstall. You would spend more time serially upgrading three or four releases than you would reinstalling.
Before upgrading, back up any data you actually care about. The upgrade process extracts new files over the existing operating system, and could overwrite something important. The installer generally works, but human beings are fallible. Back up!
Following the Upgrade Guide
As OpenBSD evolves, basic system features change. This wouldn’t be a big issue, except when interdependent changes create a chicken-and-egg or bootstrap problem. If you just blindly run the upgrade process and don’t handle any other required changes, you’ll find that your new system fails in unpredictable ways.[42] If you’re building the system from source, these problems might prevent the build from completing.
All of these potential problems should be solvable by anyone building the system from source, but it’s nice to have them documented. Conveniently, OpenBSD provides an Upgrade Guide for each release, documenting the steps needed to take a system from one release to the next.
The Upgrade Guide is divided into chunks by the type of upgrade you are performing. The simplest upgrade is for people using official OpenBSD files, such as a network or CD upgrade. If you’re building from source, the instructions quickly grow in complexity. Follow the instructions in the order in which they appear. Most upgrade prerequisites are typical system administration tasks. The following are the most common requirements.
Note
Instructions in the Upgrade Guide supersede anything I say in this chapter. I could just sprinkle the words “unless specified otherwise in the Upgrade Guide” in every paragraph for the rest of this section, but then my editor would slap me. The OpenBSD documentation is the final word in OpenBSD system administration, including the upgrade process.
Install Programs
Especially when you are building from source, bootstrap tools such as gcc(1) and perl(1) might need to be built with the upgraded tool. When upgrading from source, you might need to install these bootstrap tools before beginning to compile the new version of OpenBSD. The Upgrade Guide notes these requirements.
If your attempt to build OpenBSD from source fails, reread the Upgrade Guide before troubleshooting. Starting from the closest available binary release or snapshot will probably solve your problem.
Remove Programs and Files
OpenBSD removes programs from the base system when they become obsolete or dangerous, or when their functions are integrated into other programs. When you upgrade, you must manually remove these programs. This is necessary because old software left on an upgraded system can pose a security risk. Also, some files and directories might become superfluous in a new OpenBSD version. You can remove these programs, files, or directories once the upgrade is complete.
Prepare Package Upgrades
When you upgrade OpenBSD, you must upgrade the installed packages as well, because you can’t reliably run packages built for old versions of OpenBSD on newer versions. (Doing so might work, but there’s no guarantee.) The Upgrade Guide includes notes on upgrading specific installed packages, and you should take some of those actions before beginning the upgrade.
For example, the Upgrade Guide for the newest OpenBSD version says that the PostgreSQL port had a major version upgrade. You must do a database dump and restore as part of the upgrade. The old version of PostgreSQL might not run well on the new OpenBSD, so perform the database dump before starting the system upgrade.
Your packages might not require any pre-upgrade work, but it’s much easier to check beforehand than to finish the operating system upgrade, and then need to fall back because you didn’t prepare some third-party package.
System Configuration
The preceding tasks are the most common requirements for upgrading, but you might need to change other system files before or after the upgrade process itself. Read the Upgrade Guide, or your programs might not run as expected.
Customizing Upgrades
The upgrade script supports the siteXX.tgz file discussed in Chapter 23. If the file exists in the installation media, you can choose to install it during the upgrade.
You can also run a custom post-upgrade script as part of the upgrade. When the upgrade completes, the script checks for the file /upgrade.site. If the upgrader finds this file, it executes this script as the last step of the upgrade. Copy /upgrade.site to the system before starting the upgrade. Chapter 23 discusses upgrade.site in more detail.