Building OpenBSD-stable
Building OpenBSD-stable requires building and installing a new kernel, building and installing a new userland, and building and installing the new Xenocara.
Upgrading the Kernel
Building an upgraded kernel is like building a custom kernel, as discussed in Chapter 19. Basically, the process boils down to this:
# cd /usr/src/sys/arch/platform/conf/ # config GENERIC # cd ../compile/GENERIC # make clean && make # make install
(If I planned to build OpenBSD regularly on this machine, I would script this.)
Note
Chapter 19 is full of warnings about difficulties compiling a custom kernel. These don’t apply to building the GENERIC kernel on -stable. Remember that -stable includes only security fixes and obviously correct small changes. ABI, API, configuration, and syntax changes are absolutely forbidden. If this kernel build fails, you probably corrupted your source tree somehow. Remove everything in /usr/src and start over.
After building and installing the new kernel, reboot. You must run the new kernel to build the new userland.
Building the Userland
To build and install everything outside the kernel, remove any old builds and re-create the object directories. Also, make sure that the installed OpenBSD system has all of the necessary directories. Skipping this step will make the build fail and corrupt your source tree.
# rm -rf /usr/obj/* # cd /usr/src # make obj # cd /usr/src/etc # env DESTDIR=/ make distrib-dirs
Now you can build and install the userland.
# cd /usr/src # make build
Building userland can take several days on an antique system, but should take only an hour or two on more modern hardware. When the process finishes, you should have the new userland installed on the local system.
Note
Installing -stable simplifies the userland part of the upgrade. There’s no need to merge any new /etc/ files with sysmerge (but there’s no harm in running sysmerge either, just to check that your configuration is indeed valid), or to re-create your device nodes, as they won’t change. OpenBSD-stable contains very minor changes from the release on which it’s based.
Building Xenocara
The X Window System might or might not change during -stable. If your CVS update shows no changes in -stable, you don’t need to rebuild it, but if any of the files in /usr/xenocara have changed, you’re better off rebuilding X. The build process is completely routine for Xenocara-stable.
# cd /usr/xenocara # rm -rf /usr/xobj/* # make bootstrap # make obj # make build
This builds and installs the new X on your system.
Building a Release
This is all very nice if you want to upgrade only one machine. But what if you have several machines to upgrade to your custom OpenBSD build? You don’t want to go building -stable on your firewalls or your web server.
If you need to upgrade multiple machines, build your OpenBSD on one machine, and install that build on multiple machines by building your own release. This will take less time than you needed to build your upgrade and use under a gigabyte of disk space.
A release is what the OpenBSD Project puts on the mirror sites for you to install. It’s a few kernels, tarballs containing the userland files, the index file, and so on. Using these files, you can upgrade your other hosts just as you would perform the official media upgrade discussed earlier this chapter. Building a release is the easiest way to upgrade several OpenBSD hosts to identical versions.
Before you can build a release, you must build both the base OpenBSD system and Xenocara. You could skip Xenocara if you don’t want any X on any of your hosts, but a surprising number of third-party programs need the X libraries. It’s easier to build X and not install it on selected hosts than to go back and rebuild the whole release because you didn’t build Xenocara the first time.
The release process installs OpenBSD in a temporary root directory and then bundles that installation into the release tarballs and related files. Next, it repeats the process with the X software. It assumes that you have the OpenBSD source code in /usr/src and a completed build in /usr/obj, as well as the Xenocara source in /usr/xenocara and a completed build in /usr/xobj. You can change the build process to get around these requirements, as documented in release(8), but you should accept the defaults.
You’ll need to define three directories: one to store your release, one for your temporary OpenBSD root directory, and one for your temporary Xenocara root directory. You can reuse the temporary root directories, but I keep them for reference. I use /home/releasedir as my release directory, /home/destdir as my temporary OpenBSD root, and /home/xdestdir as the Xenocara temporary root.
Warning
You can use any partition with sufficient free space, except for /mnt because the release process uses this partition. Similarly, building a release builds ISO and floppy images using the first vnode device, /dev/vnd0. If you have any disk images mounted using that device (see Chapter 9), the release process will fail. If you must mount a disk image while building a release, use a vnode device other than /dev/vnd0.
The release process has three steps: bundling the base system, bundling Xenocara, and indexing the results.
Bundling the Base System
OpenBSD’s build system includes all of the glue that you need to build a release. First, do a make build of your new OpenBSD so that you’re running the same version you want to build a release for. Next, define the temporary OpenBSD root and the release directory in your environment as $DESTDIR and $RELEASEDIR, respectively.
Note
Verify that the temporary OpenBSD root and the release directories are empty before you start. While the release process can overwrite files from an old build, the directories might have obsolete files that you don’t want included in the new release.
# echo $DESTDIR /home/destdir # echo $RELEASEDIR /home/releasedir
Once you have this ready, building the release involves only a few commands.
# cd /usr/src/etc && make release # cd /usr/src/distrib/sets && sh checkflist
Take a look in your release directory. You should see the following items:
-
Three kernels (bsd, bsd.mp, and bsd.rd)
-
Three floppy boot images if you’re building for i386, or one if it’s for amd64 (other architectures vary)
-
Two ISO images
-
Five file sets for the OpenBSD base system
These files are functionally identical to those distributed by the OpenBSD project, except they’re based on your custom build.
Once you’ve finished building releases, be sure to remove the $RELEASEDIR and $DESTDIR variables from your environment because they can mess up other software builds. You can’t successfully build Xenocara with them still set.
Bundling Xenocara
As with bundling the base system, you must first complete a Xenocara build. Confirm that your system has the same version of Xenocara installed that you want included in your release, and then set the RELEASEDIR and DESTDIR environment variables. RELEASEDIR should be identical to that used to bundle the base system, but DESTDIR should differ.
Note
You could reuse DESTDIR, but that will erase everything from your temporary base system installation. Leave those files around until you’re sure you have a solid release.
# echo $DESTDIR /home/xdestdir # echo $RELEASEDIR /home/releasedir
Now go into the Xenocara source and bundle the release.
# cd /usr/xenocara # make release
Xenocara isn’t much smaller than the base system. It takes a while to bundle up, so this is a good time to go to lunch. When you get back, you should find five new files in your release directory, all tarballs beginning with x.
Before you quit for the day, remove RELEASEDIR and DESTDIR from your environment.
Indexing the Release
Copy your release to your local FTP or web server, and create an index of the contents. (Only HTTP installs and upgrades need an index file.) The OpenBSD installer and upgrade software will use this index during the installation.
# /bin/ls -l > index.txt
Make the web or FTP site accessible from the machines you want to upgrade.
Using the Release
Upgrade or install using this release just as you would use an official release. Copy bsd.rd to a machine to be upgraded, and then boot into that kernel. When the installer asks where to get the file sets, give the location of your release. Extract and reboot!