Building OpenBSD-stable requires building and installing a new kernel, building and installing a new userland, and building and installing the new Xenocara.
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.)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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!