Upgrading Base Software

The OpenBSD base system includes everything that is in one of the distribution sets you originally installed. The base system does not include add-on packages, nor any software you installed by hand. This is the very heart of the system upgrade. In this section, we're going to discuss upgrading to a release of OpenBSD from a CD-ROM or over the network; however, the exact same process applies to upgrading to a snapshot. Much of this information also applies to building and upgrading the system from source code, but building from source is a far more complicated and risky process and is covered in its own section.

The Upgrading Mini-FAQ

Basic system features change as OpenBSD evolves. This wouldn't be a big problem, 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 system suffers from a variety of errors. If you're building the new system from source, you may find that these problems prevent the build from completing. All of the problems should be solvable by anyone who should be building the system from source, but it's nice to have them documented in a single place. The Upgrading Mini-FAQ (http://www.OpenBSD.org/faq/upgrade-minifaq.html, or linked off the main FAQ page) documents these problems to make upgrades easier.

The Mini-FAQ is divided into chunks describing the changes necessary to upgrade from a particular release. For example, to upgrade from 3.1 to 3.2 check under "Upgrading from 3.1." There it gives several programs that must be built and installed before you can begin an upgrade from source, and several users and groups that must be added before you begin any sort of upgrade.

Before you start to upgrade your system, take a look at the Upgrading Mini-FAQ. Some of the changes only apply if you are upgrading via source code, while other types of upgrades require you to make different changes. Generally speaking, the instructions that apply for the build clearly say something along the lines of "to install this library, run these shell commands." Other upgrade requirements are typical systems administration duties: adding users and groups, adding entries to /etc/ files, or changing permissions on directories.

Upgrade instructions fall into these general categories.

New Users and Groups

Add any new users or groups before beginning the upgrade. Updated programs will expect to be owned by these new users and groups, and if the user isn't there the programs will behave in unexpected ways or will flat-out refuse to install.

Install Programs

When bootstrap tools such as gcc(1) and perl(1) are upgraded, the new system generally expects to be built with the upgraded tool. If you are upgrading from source code, you must install these bootstrap tools before beginning to compile the new version of OpenBSD. The Upgrading Mini-FAQ notes which programs must be upgraded and how to build and install them.

Uninstall Programs

Sometimes programs are removed from the base OpenBSD distribution. For example, in OpenBSD 3.2 the at(1) program was merged into cron(1), so the Mini-FAQ recommends changing /etc/crontab and removing the binaries and man pages when upgrading from 3.1. These changes can be taken after the upgrade.

System Configuration

You might have other general system configuration changes to make, such as entries in various /etc files. These changes might be required either before or after updating the installed programs. In general, read the Mini-FAQ and follow what it recommends. Your programs may not run as expected if you do not make these changes, so be sure to follow them!

Customized Upgrades

The upgrade process supports the same custom siteXX.tgz file discussed in Chapter 3. What's more, it also supports running custom post-upgrade scripts as part of the upgrade process. When the rest of the upgrade process finishes, the upgrade program checks for a script "upgrade.site" in the root directory. If it finds this script, it executes it as the last step of the upgrade.

You can create /upgrade.site on the system before starting the upgrade, which makes it much simpler to use than the equivalent install.site functionality discussed in Chapter 3.

Installing Updated Base Software

Once you complete the necessary pre-upgrade steps as described in the Upgrading Mini-FAQ, you can install the updated userland and kernel. The very simplest way to do any of this is from a CD-ROM or network server. (You can also install the updated system from a locally compiled source tree, but that's part of the upgrade from source process, which we cover separately.) Whichever method you choose, the process bears a great deal of resemblance to the initial installation process.

Prepare boot media for the version of OpenBSD you want to upgrade to; if you're running OpenBSD 3.4, and you want to upgrade to 3.5, you need an OpenBSD 3.5 boot floppy or CD-ROM. Do not attempt to use a boot disk from the wrong version of OpenBSD, or you will be exceptionally unhappy with the botch of a system you'll end up with. Boot off this new boot media. You will see the usual OpenBSD boot messages scroll past, concluding with the original prompt you saw at the beginning of the install.

 erase ^?, werase ^W, kill ^U, intr ^C, status ^T (I)nstall, (U)pgrade or (S)hell? u 

This time, we want to upgrade. Enter "u". You'll see the same welcome-to-the-install message we saw in Chapter 3, with the word "upgrade" substituted for "install." Many of the instructions displayed at the beginning of the upgrade program are absolutely the same as those from the install program, so I'll just refer you back to Chapter 3 for questions on what they mean.

 Specify terminal type: [vt220] 1 Do you wish to select a keyboard encoding table? [n] 2 IS YOUR DATA BACKED UP? As with anything that modifies disk contents, this program can cause SIGNIFICANT data loss. 3 NOTE: once your system has been upgraded, you must manually merge any changes to files in the 'etc' set into the files already on your system. 4 Proceed with upgrade? [n] y 5 

We discuss the 1 terminal type and the 2 keyboard encoding table in Chapter 3. You can almost certainly accept the defaults for both of these.

I warned you about backups, and 3 now the installer has warned you. Is your data backed up? If you're not certain, stop now and check!

The 4 warning about your /etc/ files is fairly small, for what is generally considered the most difficult part of the upgrade process; we'll cover that in "Merging /etc" later this chapter.

If you're ready, 5 enter "y" to continue with the upgrade.

 Available disks are: sd0 sd1 wd0. Which one is the root disk? (or done) [done] wd0 1 Root filesystem? [wd0a] 2 

By 1 "root disk," the upgrade program means "which disk has your root partition on it?" If you followed standard installation practice, the upgrade program should be able to 2 guess which partition on your disk is your root partition. If you did put your root partition somewhere other than the "a" partition, enter the device name for your root partition. OpenBSD will perform basic file system checks on the root partition and, if all is well, proceed.

 Enable network using configuration stored on root filesystem? [y] 

You only need to enable the network if you plan to upgrade your base system via FTP, HTTP, or some other network protocol. If you enable the network you'll see several screens of network configuration information flow by as OpenBSD reads the system configuration and the installer prints out everything it finds as it sets up the system.

 Do you want to do more, manual, network configuration? [n] 

You'll get a chance to alter the network configuration manually if something doesn't look right, but if this system was on the network previously the setup should be correct as is.

The upgrade program now inspects /etc/fstab (see Chapter 14) and identifies the file systems that the root partition knows about. The installer will display /etc/fstab, and you'll see a series of warnings and notices about disk partition usage during the upgrade. Read those messages carefully. In general, only your OpenBSD partitions will be mounted read-write. Known partitions of other types, such as FAT32 and ext2fs, will be mounted read-only. NFS partitions and partitions labeled "noauto" will not be mounted. The program will give you a chance to edit a temporary copy of the file system table before proceeding, allowing you to not mount a partition you don't want to touch or make any other changes you like. You should be able to just take the default and continue.

 Edit the fstab with ed? [n] 

The installer performs basic fsck(8) checks on all the file systems and mounts them. Now you can tell the upgrade program where to find the upgraded you want to install. The process should look very familiar from Chapter 3.

 Sets can be located on a (m)ounted filesystem; a (c)drom, (d)isk or (t)ape device; or a (f)tp, (n)fs or (h)ttp server. Where are the upgrade sets you want to use? (m, c, f, etc.) 

The next several dialogs are exactly identical to the install process. You can pick a FTP or HTTP server, or just install from CD-ROM. You'll be asked for directory information, and a username and password if necessary. You'll then be asked about which sets you want to upgrade. You must reinstall all of the sets you installed previously!

Once you have chosen all of your distribution sets, the system will ask you if you're ready to proceed. Up until this point, you have done nothing irreversible; you can interrupt the process and reboot into an untouched system. Once you enter "y" here, however, you're committed.

 Ready to upgrade sets? [y] 

The upgrade program extracts all of the distribution sets you chose and over-writes the corresponding programs on the system.

 What timezone are you in? ('?' for list) [EST] You have selected timezone 'EST'. 

While the installer remembers which time zone you had previously chosen, you might want to change it. The upgrade program rebuilds a variety of system settings, such as device nodes and bootblocks, and finally spits out a completion message that closely resembles the "successful installation" message. Just as you do on an install, enter "halt" to unmount your disks cleanly.

You could now restart your system and be running on an updated userland and kernel. Do not do it yet, though — you still have to deal with the /etc/ changes your upgrade caused.