Preparations for Building Your Own OpenBSD
Building OpenBSD takes up about 4GB of disk, 2GB in /usr/src and 2GB in /usr/obj. OpenBSD creates these directories as separate partitions by default, but if you designed your own disk-partition scheme, make sure you have enough space.
You must build on your target platform. Don’t try to cross-compile by, for example, building VAX binaries on an amd64 box. OpenBSD developers use cross-compiling to bring up a new hardware platform, but once the platform is up and running, all development happens on the native hardware. Code produced by cross-compiling might not be identical to code produced by the compiler running on the native platform.
Preparing the Base Operating System
Your first step is to prepare the base operating system. You can build OpenBSD on only an OpenBSD installation similar to what you’re trying to build, which means you need to install the closest binary set to your target platform on your build machine. If you’re trying to build OpenBSD 5.4-stable, start by installing 5.4-release on your build machine. If you’re trying to build the latest OpenBSD-current, upgrade your build machine to the newest snapshot first.
Why start from the closest available binary release? For one, that’s how the OpenBSD developers do it; the code is meant to be built from a very recent OpenBSD. Although the system changes only slowly, those changes can add up. OpenBSD-stable is built only on the OpenBSD release it’s based on, or on a -stable release following that base release.
Also, OpenBSD-current occasionally has “flag days,” where a critical system change makes building the source code difficult. These might be compiler or linker upgrades, library or kernel changes, or just about anything else. While the OpenBSD team documents what you need to do to get over these humps, those documents are more like notes for people who know what they’re doing than user-friendly instructions.
These flag days are announced on the OpenBSD mailing lists. You can try to follow those notes and build OpenBSD over these barriers, but when you get sick of beating your head against a flag-day change, upgrade to a snapshot to get over the hump. (Many OpenBSD developers also use snapshots to get over flag-day changes; inability to compile OpenBSD through a flag day is not a threat to your manhood or womanhood.)
Getting Source Code
Now get the OpenBSD source code. If you have already installed these files, and you need to upgrade to a more recent version, see Updating Source Code.
For those installing the source code for the first time, the OpenBSD project provides recent code snapshots in four compressed tar files: the userland (src.tar.gz), kernel (sys.tar.gz), X Windows (xenocara.tar.gz), and ports (ports.tar.gz). All must be kept synchronized, which means that you cannot use a -current ports tree atop a -stable userland and kernel. Get the file that’s closest to what you want to build.
If you’re building -stable, you can grab all four files from the release directory of the binary you installed. For example, if you’re building OpenBSD 5.4-stable, you’ll find src.tar.gz, sys.tar.gz, xenocara.tar.gz, and ports.tar.gz on your CD or on an OpenBSD mirror under /pub/OpenBSD/5.4/.
If you’re building -current, you’re better off starting with a newer snapshot of the source code. On the OpenBSD mirror sites, under /pub/OpenBSD, you’ll find recent copies of src.tar.gz and sys.tar.gz. Grab the most recent ones of those. You still need the xenocara.tar.gz and ports.tar.gz files from the most recent OpenBSD release, as those files are not updated as frequently.
Verify that the directories /usr/src, /usr/obj, /usr/xenocara, /usr/xobj, and /usr/ports are empty. Then extract src.tar.gz and sys.tar.gz under /usr/src, and Xenocara and ports directly under /usr. Here, I’ve copied all the tarballs to my home directory:
# cd /usr/src # tar -xzpf $HOME/src.tar.gz # tar -xzpf $HOME/sys.tar.gz # cd /usr # tar -xzpf $HOME/ports.tar.gz # tar -xzpf $HOME/xenocara.tar.gz
This gives you a known good base to start from. If you’re looking to build your own OpenBSD, you probably don’t want to build a version that’s available for installation now; you want to build a version that’s not available for installation. This means you want to update the source code to either -current or -stable.
Updating Source Code
OpenBSD uses Concurrent Versions System (CVS) for source code management. CVS is an older, somewhat traditional version control system. While many projects have moved from CVS to newer, shinier, and perhaps more glamorous systems, CVS meets the OpenBSD Project’s needs.
OpenBSD has a single central source-code repository: the master CVS server. Only developers and mirror sites have access to this server. When a developer wants to make new OpenBSD code available, he commits the changes to this central repository, and other developers can see his changes at this point.
The master CVS server tracks all changes ever made to the OpenBSD source, as well as who made those changes. Mirror sites capture these changes and make them available to the users in a matter of hours. As a user, you can use CVS to update your local source code to the latest version from a mirror site.
Source Code Repositories and Tags
OpenBSD’s source code is divided into repositories, or collections of code for particular subsystems. You need to download and synchronize only the collections that you want to use.
The OpenBSD CVS repository includes four collections: src (userland and kernel source), ports (the ports collection), xenocara (X Windows), www (the website), and the obsolete X11 and XF4 X Windows collections. While X11 and XF4 are still kept for historical purposes, you should never need to use that code. The www repository is of interest to the website editors and contributors. In order to build a recent OpenBSD, you must update your src, ports, and xenocara collections to the latest versions of your chosen branch.
A tag is a label for a particular version of a repository. OpenBSD uses tags to differentiate between -stable, -release, and -current. For example, the source code of every single OpenBSD release ever made includes the file /usr/src/etc/master.passwd. But the version of master.passwd shipped with OpenBSD 2.0 differs wildly from that shipped with OpenBSD 5.3! CVS uses tags to differentiate the various versions of this and every other file. By using tags, you can ask CVS for the version of any file that shipped with any OpenBSD release.
The tag for any -stable version of OpenBSD is the string OPENBSD and the version number, separated by underscores. For example, the tag for OpenBSD 5.4 is OpenBSD_5_4. Note the two underscores: there is no OPENBSD_54 or OPENBSD5_4. If you use a tag that does not exist, rather than updating your local source code files, you’ll delete them. (While you should download the source code for a release, rather than updating to it via CVS, an OpenBSD release appends the string _BASE to the tag, as in OPENBSD-5_4_BASE.) That said, OpenBSD-current is special in that it has no tag and it includes the latest version of all source code in all repositories.
All of the repositories are designed to be updated synchronously. If, for example, you update the source code repository to -current and leave your ports and Xenocara at their -release or -stable versions, your system will behave unpredictably. As with learning to juggle chainsaws, you’re welcome to try it, but don’t whine.
CVS Mirrors
You can use anonymous CVS to update your source code to the latest version. Start by choosing a convenient anonymous CVS server from the list at http://www.OpenBSD.org/anoncvs.html. There are mirrors all over the world, but choose one on your continent for better performance. (I use anoncvs13.usa.openbsd.org [44] in my examples.)
Tracking OpenBSD-current is slightly different than tracking OpenBSD-stable. We’ll start with -stable, and then see how -current differs.
Updating to -stable
The first time you update your source code, you must specify the anonymous CVS server on the command line.
# cd /usr # cvs -qd anonymous@server:/cvs get -rOPENBSD_tag -P src
CVS is very picky about the order of its command-line arguments, and many flags are position-dependent. Don’t change the order of arguments unless you know what you’re doing.
Substitute your preferred server and the release tag you want to get into this command. For example, to update my OpenBSD 5.1 source tree to the latest stable version from anoncvs13.openbsd.org, I would run the following:
# cd /usr # cvs -qd [email protected]:/cvs get -rOPENBSD_5_1 -P src The authenticity of host 'anoncvs13.usa.openbsd.org (192.0.2.217)' can't be established. 1 ECDSA key fingerprint is d3:b2:b5:68:87:3b:f6:93:21:fd:28:ea:cc:b6:e1:13. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'anoncvs1.usa.openbsd.org,149.20.54.217' (ECDSA) to the list of known hosts.
Because OpenBSD runs CVS over SSH the first time you run cvs, it asks you to verify the CVS mirror’s host key. Compare the 1 key fingerprint given by your client to the fingerprint listed on the CVS mirror list. If they match, you’re talking to the actual CVS server. If the fingerprints don’t match, something is wrong, which could be a problem at the server, a skipped website update, or an actual security problem at the mirror. If the key fingerprints don’t match, choose a different CVS mirror. (SSH will cache this key, and future updates won’t ask you to verify the key unless it changes.)
There’s a pause when CVS starts comparing the source code on your disk to the source code on the server, and just about when you think that something has gone wrong, you’ll probably see actual source code updates, like this:
U bin/systrace/intercept-translate.c U lib/libssl/src/crypto/mem.c U lib/libssl/src/crypto/asn1/a_d2i_fp.c U lib/libssl/src/crypto/buffer/buffer.c U sys/conf/newvers.sh U sys/netinet6/ip6_output.c U usr.sbin/nsd/query.c
This is complete CVS update output for updating OpenBSD 5.1 release to -stable. In all, there were seven changes. When the OpenBSD guys say “minimal changes in -stable,” they mean it.
Repeat this for /usr/ports and /usr/xenocara.
# cd /usr # cvs -qd [email protected]:/cvs get -rOPENBSD_5_1 -P ports # cvs -qd [email protected]:/cvs get -rOPENBSD_5_1 -P xenocara
A source tree records the last server updated from, and on subsequent updates, you can drop the server from the command line. The source tree also knows which repository within the server it’s supposed to update from, so you don’t need to specify it.
# cd /usr/src # cvs -q up -rOPENBSD_5_1 -Pd
Run this same command any time you want the latest -stable source code.
Updating to -current
The process for updating your source code to -current is much the same as updating to -stable, but the command line differs slightly. The first time you update your source tree, you must specify the server name.
# cd /usr # cvs -qd anonymous@server:/cvs get -P src
This cvs command gives you the latest -current source code. For example, if I want to update my source code from anoncvs13.openbsd.org, I run this:
# cd /usr # cvs -qd [email protected]:/cvs get -P src
You should get the SSH key fingerprint verification message, and see the same type of messages that you would get updating to -stable.
The first time you run CVS to update a specific set of source code, cvs records which server the source code came from. For subsequent updates to the latest -current source code, you can skip the server name and shorten the command, as follows:
# cd /usr/src # cvs -q up -Pd
Now you need to build the new source code into program code.
You build -stable and -current in the same way, but -current has more potential issues, so we’ll start by building -stable.