[FAQ Index] [To Section 4 - Installation Guide] [To Section 6 - Networking]

5 - Building the System from Source

Table of Contents

• 5.1 - OpenBSD's Flavors
• 5.2 - Why should I build my system from source?
• 5.3 - Building OpenBSD from source
  • 5.3.1 - Overview
  • 5.3.2 - Install or upgrade to closest available binary
  • 5.3.3 - Fetching the appropriate source code
  • 5.3.4 - Building the kernel
  • 5.3.5 - Building userland
• 5.4 - Building a release
• 5.5 - Building X
• 5.6 - Why do I need a custom kernel?
• 5.7 - Building a custom kernel
• 5.8 - Boot-time configuration
• 5.9 - Using config(8) to change your kernel
• 5.10 - Getting more verbose output during boot
• 5.11 - Common problems, tips and questions when compiling and building
  • 5.11.1 - The build stopped with a "Signal 11" error
  • 5.11.2 - "make build" fails with "cannot open output file snake: is a directory"
  • 5.11.3 - My IPv6-less system doesn't work!
  • 5.11.4 - Oops! I forgot to make the /usr/obj directory first!
  • 5.11.5 - Put /usr/obj on its own partition
  • 5.11.6 - How do I not build parts of the tree?
  • 5.11.7 - Where can I learn more about the build process?
  • 5.11.8 - I didn't see any snapshots on the FTP site. Where did they go?
  • 5.11.9 - How do I bootstrap a newer version of the compiler (gcc)?
  • 5.11.10 - What is the best way to update /etc, /var, and /dev?
  • 5.11.11 - Is there an easy way to make all the file hierarchy changes?
  • 5.11.12 - Can I cross-compile? Why not?

5.1 - OpenBSD's Flavors

• -release: The version of OpenBSD shipped every six months on CD.
• -stable: Release, plus patches considered critical to security and reliability.
• -current: Where new development work is presently being done, and eventually, it will turn into the next release.

,------o-----------o----X 3.9 Stable | . . | . ,------o---------o----X 4.0 Stable | . | . . | . | . ,----o----------o--> 4.1 Stable | . | . | . . | . | . | . ,-----o--> 4.2 Stable | . | . | . | . | . | . | . | . -->3.9Rel----->4.0Rel----->4.1Rel----->4.2Rel----> Current Time --->

-Current is where active development work is done, and eventually, it will turn into the next -release of OpenBSD. Every six months, when a new version of OpenBSD is released, -current is tagged, and becomes -release: a frozen point in the history of the source tree. Each -release is never changed; it is what is on the CDs and FTP servers.

-Stable is based on -release, and is a branch from the main development path of OpenBSD. When very important fixes are made to -current, they are "back ported" (merged) into the -stable branches; because of this, -stable is also known as the "patch branch." In the above illustration, the vertical dotted lines denote bug fixes being incorporated into the -stable branches. You will also note that in the above example, the 3.9-stable branch came to an end with 4.1-release, and the 4.0-stable branch came to an end with 4.2-release -- old releases are typically supported up to two releases back. It takes resources and time to support older versions, while we might like to provide ongoing support for old releases, we would rather focus on new features. The -stable branch is, by design, very easy to build from -release of the same version (i.e., going from 4.2-release to 4.2-stable).

The -stable branch is -release plus patches found on the errata page. The operation of -stable is the same as the -release it is based on. If the man pages have to change, it probably won't go into -stable. In other words, new device support and new features will NOT be added to -stable.

It is worth pointing out that the name "-stable" is not intended to imply that -current is unreliable. Rather, -current is changing and evolving, whereas the operation and APIs of -stable are not going to change, so you shouldn't have to relearn your system or change any configuration files, or have any problem adding additional applications to your system.

In fact, as our hope is to continually improve OpenBSD, the goal is that -current should be more reliable, more secure, and of course, have greater features than -stable. Put bluntly, the "best" version of OpenBSD is -current.

Warning: -current is a moving target. It changes minute by minute, and may well change several times in the time it takes to retrieve the source code. While the developers work hard to ensure that the system always compiles and that there are no major bugs, it is entirely possible to get the -current source and have it fail to compile, whereas five minutes later everything will be just fine. There are also flag days and major system changes that the developers navigate with one-time tools, which mean that source-based updating is not possible. If you are not prepared to deal with this, stay away from -current.

Most users should be running either -stable or -release. That being said, many people do run -current on production systems, and it is important that some people do so to identify bugs and test new features. However, if you don't know how to properly describe, diagnose and deal with a problem, don't tell yourself (or anyone else) that you are "helping the project" by running -current. "It didn't work!" is not a useful bug report. "The recent changes to the pciide driver broke compatibility with my Slugchip-based IDE interface, dmesg of working and broken systems follow..." might be a useful report.

There are times when "normal" users may wish to live on the cutting edge and run -current. The most common reason is that the user has a device which is not supported by -release (and thus, not -stable), or wishes to use a new feature of the -current. In this case, the choice may be either -current or not using the device, and -current may be the lesser evil. However, one should not expect hand-holding from the developers.

Snapshots

It is sometimes asked if there is any way to get a copy of exactly the code used to build a snapshot. The answer is no. First, there is no significant benefit to this. Second, the snapshots are built as desired, as time permits, and as resources become available. On fast platforms, several snapshots may be released in one day. On slower platforms, it may take a week or more to build a snapshot. Providing tags or markers in the source tree for each snapshot would be quite impractical. Third, snapshots often contain experimental code that isn't yet committed to the tree.

Upgrade vs. Update

Upgrading is the process of installing a newer version of OpenBSD, with new functionality. For example, going from v4.1 to v4.2, or going from the June 12th snapshot to the June 20th snapshot. When upgrading, you will typically have to consult either Following -current or the Upgrade guide (when changing releases) to make the changes required to run the upgraded version of OpenBSD.
Updating is the process of applying patches to a system to improve the operation WITHOUT changing the basic functionality or binary compatibility. This is typically done by following the source patching process or by following the stable process. When you "update" your system, it goes from a -release to a -stable (or patched -release) of the same release version, for example, 4.2-release to 4.2-stable. You may then later update it to a newer -stable of the same release version. The update process is typically very painless, as no /etc files or other system configurations need to be changed.

So, you may install a system (for example, 4.1-release) from CD, then update it to 4.1-stable a few times, then upgrade it to 4.2-release from CD, and update that a few times before upgrading it again to the next release.

Keeping Things in Sync

One should also understand that the upgrade process is supported in only one direction: from older to newer, and from -stable to -current. You can not run 4.2-current (or a snapshot), then decide you are living too dangerously, and step back to 4.2-stable. You are on your own if you choose any path other than the supported option of reloading your system from scratch, do not expect assistance from the OpenBSD development team.

Yes, this does mean you should think long and hard before committing yourself to using -current.

5.2 - Why do I need to compile the system from source?

Some reasons why NOT to build from source:

• Compiling your own system as a way of upgrading it is not supported.
• You will NOT get better system performance by compiling your own system.
• Changing compiler options is more likely to break your system than to improve it.

• Test or develop new features.
• Compiling the system puts a lot of stress on the computer, it can be a way to make sure the system you just put together or acquired is actually in pretty good operational condition.
• You wish to follow the stable branch.
• You wish to make a highly customized version of OpenBSD for some special application.

The OpenBSD team puts out new snapshots based on -current code on a very regular basis for all platforms. It is likely this will be all you need for running -current.

The most common reason to build from source is to follow the -stable branch, where building from source is the only supported option.

5.3 - Building OpenBSD from source

5.3.1 - Overview of the building process

• Upgrading to the closest available binary.
• Fetching the appropriate source code.
• Building the new kernel and booting from it.
• Building "userland" ("make build").

• Building a "release".
• Building X.

5.3.2 - Install or Upgrade to closest available binary

It is recommended that you install the binary by using the "Upgrade" option of the install media. If that is not possible, you can also unpack the binaries as described here. Regardless, you must do the entire upgrade process, including creating any users or other /etc directory changes needed.

5.3.3 - Fetching the appropriate source code

After deciding which AnonCVS server you wish to use, you must "checkout" the source tree, after that, you then maintain the tree by running "updates", to pull updated files to your local tree.

The CVS(1) command has many options, some of them are required to checkout and update a useful tree. Other commands can cause a broken tree. Following and understanding directions here is important.

Following -current

In this case, we will assume we are using a public AnonCVS server, anoncvs@anoncvs.example.org:/cvs. We will also assume you are using sh(1) as your command shell, if you are using a different shell, you will have to adjust some of these commands.

To checkout a -current CVS src tree, you can use the following: # cd /usr # export CVSROOT=anoncvs@anoncvs.example.org:/cvs # cvs -d$CVSROOT checkout -P src

Once you have a tree, you can update it at a later time: # cd /usr/src # export CVSROOT=anoncvs@anoncvs.example.org:/cvs # cvs -d$CVSROOT up -Pd

If you wish to check out an alternative "branch" of the tree, such as the -stable branch, you will use the "-r" modifier to your checkout: # cd /usr # export CVSROOT=anoncvs@anoncvs.example.org:/cvs # cvs -d$CVSROOT checkout -rOPENBSD_4_2 -P src This will pull the src files from the OPENBSD_4_2 branch, which is also known as the "Patch branch" or "-stable". You would update the code similarly: # cd /usr/src # export CVSROOT=anoncvs@anoncvs.example.org:/cvs # cvs -d$CVSROOT up -rOPENBSD_4_2 -Pd Actually, CVS is nice enough to stick a "Tag" in the checked out file system, so you don't have to remember the "-rOPENBSD_4_2" part of the command line, it will remember this until you explicitly clear them or set a new tag by using the "-A" option to "update". However, it is probably better to provide too much info in your CVS command lines than too little.

While only the "src" tree has been shown so far, you will do the same steps for "xenocara" and "ports". As all parts of OpenBSD must be kept in sync, all trees you use should be checked out and updated at the same time. You can combine the checkouts into one line (-stable shown): # export CVSROOT=anoncvs@anoncvs.example.org:/cvs # cd /usr # cvs -d$CVSROOT checkout -rOPENBSD_4_2 -P src ports # cd /usr/src # cvs -d$CVSROOT checkout -rOPENBSD_4_2 -P xenocara However, updates must be done directory-by-directory.

At this point, whether you followed -stable or -current you should have a usable source tree. Be very careful which tree you grab -- it is easy to try to compile -current when aiming for -stable.

Pre-loading the tree: src.tar.gz, sys.tar.gz

To extract the source tree from the CD to /usr/src (assuming the CD is mounted on /mnt): # cd /usr/src; tar xzf /mnt/src.tar.gz # tar xzf /mnt/xenocara.tar.gz # cd /usr; tar xzf /mnt/ports.tar.gz The source files available for download from the FTP servers are separated into two files to minimize the download time for those wishing to work with only one part of the tree. The two files are sys.tar.gz, which contains the files used to create the kernel, and src.tar.gz which contains all the other "userland" utilities except the ports tree and the X11 sources. In general, however, you will usually want both of them installed. Assuming the downloaded files, src.tar.gz and sys.tar.gz, are in /usr: # cd /usr/src # tar xzf ../sys.tar.gz # tar xzf ../src.tar.gz # tar xzf ../xenocara.tar.gz # cd /usr # tar xzf ports.tar.gz

Not all people will wish to unpack all the file sets, but as the system must be kept in sync, you will generally need to set up all parts of the tree.

Common CVS tips

Much the same with the -d option on the 'update' command -- it creates new directories that may have been added to the tree since your initial checkout. To get a successful update, you must use the -Pd options.

Experienced CVS users may wonder why the CVSROOT was specified and used in this example, as cvs(1) will record the CVS server's location in the checked out tree. This is correct, however there are enough times where one may need to override the default anoncvs server, many people recommend always specifying the repository explicitly. It is also worth noting that while the CVSROOT environment variable can be used directly by cvs(1), it is used only if nothing else overrides it (i.e., cvs(1) would have an error without it), whereas specifying it in the cvs(1) command line overrides all other values.

It is often useful to use a .cvsrc in your home directory to specify defaults for some of these options. An example .cvsrc file: $ more ~/.cvsrc cvs -q -danoncvs@anoncvs.example.org:/cvs diff -up update -Pd checkout -P This file would cause cvs(1) to use the anoncvs@anoncvs.example.org:/cvs server, suppress usually unneeded output ("-q" is "quiet") for all operations, a "cvs up" command defaults to using the -Pd, a "cvs diff" defaults to providing "unified diffs" due to the "-u", and a "cvs checkout" will use the "-P" option. While this is convenient, if you forget this file exists, or try to run commands you got used to on a machine without this file, you will have problems.

As the source trees consist of large numbers of mostly small files, turning on soft updates for the partition the source tree is on will often give significantly better performance.

5.3.4 - Building the kernel

Obviously, the kernel is a VERY hardware dependent portion of the system. The source for the kernel is in the /usr/src/sys directory. Some parts of the OpenBSD kernel code are used on all platforms, others are very specific to one processor or one architecture. If you look in the /usr/src/sys/arch/ directory, you may see some things that look a little confusing -- for example, there are mac68k, m68k and mvme68k directories. In this case, the mvme68k and mac68k systems both use the same processor, but the machines they are based on are very different, and thus require a very different kernel (there is much more to a computer's design than its processor!). However, parts of the kernel are common, those parts are kept in the m68k directory. If you are simply building a kernel, the base architecture directories like m68k are not anything for you to worry about, you will be working exclusively with the "compound architecture" directories, such as mvme68k.

Kernels are built based on kernel configuration files, which are located in the /usr/src/sys/arch/<your platform>/conf directory. Building the kernel consists of using the config(8) program to create and populate a kernel compile directory, which will end up in /usr/src/sys/arch/<your platform>/compile/<KernelName>. For this example, we will assume you are using the i386 platform:

# cd /usr/src/sys/arch/i386/conf # config GENERIC # cd ../compile/GENERIC # make clean && make depend && make [...lots of output...] # make install

At this point, reboot your machine to activate this new kernel. Note that the new kernel should be running before the next step, though if you have followed the above advice about upgrading to the most recent available snapshot, it may not matter as much. Sometimes, however, APIs change, and the old kernel will be unable to run new applications, but the new kernel will generally support the old ones.

Variation on above process: Read-only source tree

$ cd /somewhere $ cp /usr/src/sys/arch/i386/conf/GENERIC . $ config -s /usr/src/sys -b . GENERIC $ make clean && make depend && make ... lots of output ...

5.3.5 - Building the userland

• Clear your /usr/obj directory and rebuild symbolic links:

  # rm -rf /usr/obj/* # cd /usr/src # make obj

  Note that the use of the /usr/obj directory is mandatory. Failing to do this step before building the rest of the tree will likely leave your src tree in bad shape.

• Make sure all the appropriate directories are created.

  # cd /usr/src/etc && env DESTDIR=/ make distrib-dirs

• Build the system:

  # cd /usr/src # make build

  This compiles and installs all the "userland" utilities in the appropriate order. This is a fairly time consuming step -- a very fast machine may be able to complete it in well under an hour, a very slow machine may take many days. When this step is complete, you have newly compiled binaries in place on your system.

• If building -current: Update /dev and /etc, with the changes listed in current.html. If following -stable after a proper upgrade process or a install of the proper starting binary, this step is not needed or desired.

5.4 - Building a Release

What is a "release", and why would I want to make one?

The release process uses the binaries created in the /usr/obj directory in the building process above, so you must successfully complete the build first, and nothing must disturb the /usr/obj directory. A time where this might be a problem is if you use a memory disk as your /usr/obj for a little extra performance in the build process, you would not want to reboot the computer between the "build" and "release" steps!

The release process requires two work directories, which we will call DESTDIR and RELEASEDIR. All the files that are part of a "clean" OpenBSD install will be copied to their proper place within the DESTDIR. They will then be tar(1)ed up and placed in the RELEASEDIR. At the end of the process, RELEASEDIR will hold the completed OpenBSD release. The release process will also use the /mnt location, so this should not be used by anything while the release process is running. For the purpose of example, we will use the DESTDIR of /usr/dest and the RELEASEDIR of /usr/rel.

The release process involves a couple utilities which are not in the base OpenBSD system, crunch and crunchgen(1), which are used to create a single executable file made up of many individual binaries. The name this single executable file is invoked by determines which component binary is run. This is how a number of individual program files are squeezed into the ramdisk kernel that exists on boot floppies and other boot media. These utilities must be built before the release process is started. They only need to be built and installed once, but as people often forget this step, and these programs build quickly, some people opt to just build crunch and crunchgen every time as part of the script they use to make a release.

You must have root privileges to make a release.

Doing a release

# cd /usr/src/distrib/crunch && make obj depend all install

# export DESTDIR=/usr/dest # export RELEASEDIR=/usr/rel

# test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}.old && rm -rf ${DESTDIR}.old & # mkdir -p ${DESTDIR} ${RELEASEDIR}

We now make the release itself:

# cd /usr/src/etc # make release

# cd /usr/src/distrib/sets # sh checkflist

The authoritative instructions on making a release are in release(8).

Note: if you wish to distribute the resultant files by HTTP for use by the upgrade or install scripts, you will need to add an "index.txt" file, which contains the list of all the files in your newly created release.

# /bin/ls -1 >index.txt

5.5 - Building X (4.2 Xenocara)

Starting with X.org v7, X switched to "modular build" system, splitting the x.org source tree into more than three hundred more-or-less independent packages.

To simplify life for OpenBSD users, a "meta-build" called Xenocara was developed. This system "converts" X back into one big tree to be built in one process. As an added bonus, this build process is much more similar to the build process used by the rest of OpenBSD than the previous versions were.

The official instructions for building X exist in your machine's /usr/src/xenocara/README file and in release(8).

Getting source code

$ cd /usr/src $ cvs -qdanoncvs@anoncvs.example.org:/cvs checkout -P xenocara

Building Xenocara

# cd /usr/src/xenocara # make bootstrap # make obj # make build

Making a release

For this example, we will use a DESTDIR and RELEASEDIR of /usr/dest and /usr/rel, respectively. This must be done after the above build process.

# export DESTDIR=/usr/dest # export RELEASEDIR=/usr/rel # test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \ rm -rf ${DESTDIR}- & # mkdir -p ${DESTDIR} ${RELEASEDIR} # make release

5.6 - Why do I need a custom kernel?

Actually, you probably don't.

A custom kernel is a kernel built with a configuration file other than the provided GENERIC configuration file. A custom kernel can be based on -release, -stable or -current code, just as a GENERIC kernel can be. While compiling your own GENERIC kernel is supported by the OpenBSD team, compiling your own custom kernel is not.

The standard OpenBSD kernel configuration (GENERIC) is designed to be suitable for most people. More people have broken their system by trying to tweak their kernel than have improved system operation. There are some people that believe that you must customize your kernel and system for optimum performance, but this is not true for OpenBSD. Only the most advanced and knowledgeable users with the most demanding applications need to worry about a customized kernel or system.

Some reasons you might want or need to build a custom kernel:

• You really know what you are doing, and want to shoe-horn OpenBSD onto a computer with a small amount of RAM by removing device drivers you don't need.
• You really know what you are doing, and wish to remove default options or add options which may not have been enabled by default (and have good reason to do so).
• You really know what you are doing, and wish to enable experimental options.
• You really know what you are doing, and have a special need that is not met by GENERIC, and aren't going to ask why it doesn't work if something goes wrong.

Some reasons why you should not build a custom kernel:

• You do not need to, normally.
• You will not get a faster system.
• You are likely to make a less reliable machine.
• You will not get any support from developers.
• You will be expected to reproduce any problem with a GENERIC kernel before developers take any problem report seriously.
• Users and developers will laugh at you when you break your system.
• Custom compiler options usually do a better job of exposing compiler problems than improving system performance.

Removing device drivers may speed the boot process on your system, but can complicate recovery should you have a hardware problem, and is very often done wrong. Removing device drivers will not make your system run faster by any noticeable amount, though can produce a smaller kernel. Removing debugging and error checking can result in a measurable performance gain, but will make it impossible to troubleshoot a system if something goes wrong.

Again, developers will usually ignore bug reports dealing with custom kernels, unless the problem can be reproduced in a GENERIC kernel as well. You have been warned.

5.7 - Building a custom kernel

OpenBSD kernel generation is controlled by configuration files, which are located in the /usr/src/sys/arch/<arch>/conf/ directory by default. All architectures have a file, GENERIC, which is used to generate the standard OpenBSD kernel for that platform. There may also be other configuration files which are used to create kernels with different focuses, for example, for minimal RAM, diskless workstations, etc.

The configuration file is processed by config(8), which creates and populates a compilation directory in ../compile, on a typical installation, that would be in /usr/src/sys/arch/<arch>/compile/. config(8) also creates a Makefile, and other files required to successfully build the kernel.

Kernel Configuration Options are options that you add to your kernel configuration that place certain features into your kernel. This allows you to have exactly the support you want, without having support for unneeded devices. There are a multitude of options that allow you to customize your kernel. Here we will go over only some of them, those that are most commonly used. Check the options(4) man page for a complete list of options, and as these change from time to time, you should make sure you use a man page for the same version of OpenBSD you are building. You can also check the example configuration files that are available for your architecture.

Do not add, remove, or change options in your kernel unless you actually have a reason to do so! Do not edit the GENERIC configuration file!! The only kernel configuration which is supported by the OpenBSD team is the GENERIC kernel, the combination of the options in /usr/src/sys/arch/<arch>/conf/GENERIC and /usr/src/sys/conf/GENERIC as shipped by the OpenBSD team (i.e., NOT edited). Reporting a problem on a customized kernel will almost always result in you being told to try to reproduce the problem with a GENERIC kernel. Not all options are compatible with each other, and many options are required for the system to work. There is no guarantee that just because you manage to get a custom kernel compiled that it will actually run. There is no guarantee that a kernel that can be "config(8)ed" can be built.

You can see the platform-specific configuration files here:

• alpha Kernel Configuration Files
• i386 Kernel Configuration Files
• macppc Kernel Configuration Files
• sparc Kernel Configuration Files
• sparc64 Kernel Configuration Files
• vax Kernel Configuration Files
• hppa Kernel Configuration Files
• Other Arch's

Look closely at these files and you will notice a line near the top similar to: include "../../../conf/GENERIC" This means that it is referencing another configuration file, one that stores platform-independent options. When creating your kernel configuration, be sure to look through sys/conf/GENERIC.

Kernel configuration options should be placed in your kernel configuration file in the format of:

option      name

option      name=value

option DEBUG

Sometimes, you may wish to disable an option that is already defined, typically in the "src/sys/conf/GENERIC" file. While you could modify a copy of that file, a better choice would be to use the rmoption statement. For example, if you really wanted to disable the in-kernel debugger (not recommended!), you would add a line such as: rmoption DDB in your kernel configuration file. option DDB is defined in src/sys/conf/GENERIC, but the above rmoption line deactivates it.

Once again, please see options(4) for more information about the specifics of these options. Also note that many of the options also have their own manual pages -- always read everything available about an option before adding or removing it from your kernel.

Building a custom kernel

include "arch/i386/conf/GENERIC" boca0 at isa? port 0x100 irq 10 # BOCA 8-port serial cards pccom* at boca? slave ?

Another way to generate a custom kernel is to make a copy of the standard GENERIC, giving it another name, then editing it as needed. The disadvantage to this is later updates to the GENERIC configuration file have to be merged into your copy, or you have to remake your configuration file.

In either event, after making your custom kernel configuration file, use config(8) and make the kernel as documented above.

Full instructions for creating your own custom kernel are in the afterboot(8) man page.

5.8 - Boot-Time Configuration

Sometimes when booting your system you might notice that the kernel finds your device but maybe at the wrong IRQ. And maybe you need to use this device right away. Well, without rebuilding the kernel you can use OpenBSD's boot time kernel configuration. This will only correct your problem for one time. If you reboot, you will have to repeat this procedure. So, this is only meant as a temporary fix, and you should correct the problem using config(8). Your kernel does however need option BOOT_CONFIG in the kernel, which GENERIC does have.

Most of this document can be found in the man page boot_config(8).

To boot into the User Kernel Config, or UKC, use the -c option at boot time.

boot> boot hd0a:/bsd -c

Here is a list of common commands in the UKC.

• add device - Add a device through copying another
• change devno | device - Modify one or more devices
• disable devno | device - Disable one or more devices
• enable devno | device - Enable one or more devices
• find devno | device - Find one or more devices
• help - Short summary of these commands
• list - List ALL known devices
• exit/quit - Continue Booting
• show [attr [val]] - Show devices with an attribute and optional with a specified value

Once you have your kernel configured, use quit or exit and continue booting. After doing so, you should make the change permanent in your kernel image, as described in Using config(8) to change your kernel.

5.9 - Using config(8) to change your kernel

The -e and -u options with config(8) can be extremely helpful and save wasted time compiling your kernel. The -e flag allows you to enter the UKC or User Kernel Config on a running system. These changes will then take place on your next reboot. The -u flag tests to see if any changes were made to the running kernel during boot, meaning you used boot -c to enter the UKC while booting your system.

The following example shows the disabling of the ep* devices in the kernel. For safety's sake you must use the -o option which writes the changes out to the file specified. For example : config -e -o bsd.new /bsd will write the changes to bsd.new. The example doesn't use the -o option, therefore changes are just ignored, and not written back to the kernel binary. For more information pertaining to error and warning messages read the config(8) man page.

$ sudo config -e /bsd OpenBSD 4.2 (GENERIC) #375: Tue Aug 28 10:38:44 MDT 2007 deraadt@i386.openbsd.org:/usr/src/sys/arch/i386/compile/GENERIC warning: no output file specified Enter 'help' for information ukc> ? help Command help list add dev Add a device base 8|10|16 Base on large numbers change devno|dev Change device disable attr val|devno|dev Disable device enable attr val|devno|dev Enable device find devno|dev Find device list List configuration lines count # of lines per page show [attr [val]] Show attribute exit Exit, without saving changes quit Quit, saving current changes timezone [mins [dst]] Show/change timezone nmbclust [number] Show/change NMBCLUSTERS cachepct [number] Show/change BUFCACHEPERCENT nkmempg [number] Show/change NKMEMPAGES shmseg [number] Show/change SHMSEG shmmaxpgs [number] Show/change SHMMAXPGS ukc> list 0 audio* at sb0|sb*|gus0|pas0|sp0|ess*|wss0|wss*|ym*|eap*|eso*|sv*|neo*|cmpci* |clcs*|clct*|auich*|autri*|auvia*|fms*|uaudio*|maestro*|esa*|yds*|emu* flags 0x0 1 midi* at sb0|sb*|opl*|opl*|opl*|opl*|ym*|mpu*|autri* flags 0x0 2 nsphy* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|vr* |ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep*|e p*|ep* phy -1 flags 0x0 3 nsphyter* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*| vr*|ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep *|ep*|ep* phy -1 flags 0x0 4 qsphy* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|vr* |ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep*|e p*|ep* phy -1 flags 0x0 5 inphy* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|vr* |ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep*|e p*|ep* phy -1 flags 0x0 6 iophy* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|vr* |ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep*|e p*|ep* phy -1 flags 0x0 7 eephy* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|vr* |ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep*|e p*|ep* phy -1 flags 0x0 8 exphy* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|vr* |ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep*|e p*|ep* phy -1 flags 0x0 [...snip...] ukc> disable ep 67 ep0 disabled 68 ep* disabled 69 ep* disabled 155 ep0 disabled 156 ep0 disabled 157 ep* disabled 158 ep* disabled 210 ep* disabled ukc> quit not forced

In the above example, all ep* devices are disabled in the kernel and will not be probed. In some situations where you have used the UKC during boot, via boot -c, you will need these changes to be written out permanently. To do this you need to use the -u option. In the following example, the computer was booted into the UKC and the wi(4) device was disabled. Since changes made with boot -c are NOT permanent, these changes must be written out. This example writes the changes made from boot -c into a new kernel binary bsd.new.

$ sudo config -e -u -o bsd.new /bsd OpenBSD 4.2 (GENERIC) #375: Tue Aug 28 10:38:44 MDT 2007 deraadt@i386.openbsd.org:/usr/src/sys/arch/i386/compile/GENERIC Processing history... 105 wi* disabled 106 wi* disabled Enter 'help' for information ukc> quit

5.10 - Getting more verbose output during boot

UKC> verbose autoconf verbose enabled UKC> quit

Now you will be given extremely verbose output upon boot.

5.11 - Common problems, tips and questions when compiling and building

Most problems are usually one of the following:

• Failing to start from the appropriate binary, including attempting to upgrade from source or assuming a week old snapshot is "close enough".
• Checking out the wrong branch of the tree.
• Not following the process.
• Trying to customize or "optimize" your system.

5.11.1 - The build stopped with a "Signal 11" error

Building OpenBSD and other programs from source is a task which pushes hardware harder than most others, making intensive use of CPU, disk and memory. As a result, if you have hardware which has a problem, the most likely time for that problem to appear is during a build. Signal 11 failures are typically caused by hardware problems, very often memory problems, but can also be CPU, main board, or heat issues. Your system may actually be very stable otherwise, but unable to compile programs.

You will probably find it best to repair or replace the components that are causing trouble, as problems may show themselves in other ways in the future. If you have hardware which you really wish to use and causes you no other problem, simply install a snapshot or a release.

For much more information, see the Sig11 FAQ.

5.11.2 - "make build" fails with "cannot open output file snake: is a directory"

• You did not fetch or update your CVS tree properly. When doing a CVS checkout operation, you must use the "-P" option, when you update your source tree with CVS, you must use "-Pd" options to cvs(1), as documented above. These options make sure new directories are added and removed from the tree as OpenBSD evolves.
• You did not properly create the obj directory before your build. Building the tree without a /usr/obj directory is not supported.

5.11.3 - My IPv6-less system doesn't work!

5.11.4 - Oops! I forgot to make the /usr/obj directory first!

5.11.5 - Tip: Put /usr/obj on its own partition

5.11.6 - How do I not build parts of the tree?

Note: it is possible to make a broken system this way. The results of this option are not supported by the OpenBSD project.

5.11.7 - Where can I learn more about the build process?

• release(8)
• afterboot(8)
• mk.conf(5)
• /usr/src/Makefile
• Patch Branches (-stable)
• (for X) /usr/X11R6/README on your installed system

5.11.8 - I didn't see any snapshots on the FTP site. Where did they go?

Snapshots may be removed as they become old (or no longer relevant) or near the time of a new -release.

5.11.9 - How do I bootstrap a newer version of the compiler (gcc)?

OpenBSD now supports two compilers in-tree, gcc v3.3.5 used by most platforms, but also gcc v2.95.3 used by a few platforms which haven't been converted yet, or may never be converted due to lack of gcc3 support or poor gcc3 performance.

The two compilers are in different parts of the tree:

• gcc3: /usr/src/gnu/usr.bin/gcc
• gcc2: /usr/src/gnu/egcs/gcc

Because upgrading a compiler is a bit of a chicken-and-egg problem, changes to the in-tree compiler require a little extra attention. You have to build the compiler twice -- the first build produces a compiler that generates new code but runs with code generated by the old compiler, the second build makes it a completely new compiler. In general, you'll want to perform the following procedure: If your platform uses gcc 2.95.3: # rm -r /usr/obj/gnu/egcs/gcc/* # cd /usr/src/gnu/egcs/gcc - or - If your platform uses gcc 3.3.5: # rm -r /usr/obj/gnu/usr.bin/gcc/* # cd /usr/src/gnu/usr.bin/gcc Common build procedure for v3.3.5 or v2.95.3 # make -f Makefile.bsd-wrapper clean # make -f Makefile.bsd-wrapper obj # make -f Makefile.bsd-wrapper depend # make -f Makefile.bsd-wrapper # make -f Makefile.bsd-wrapper install # make -f Makefile.bsd-wrapper clean # make -f Makefile.bsd-wrapper depend # make -f Makefile.bsd-wrapper # make -f Makefile.bsd-wrapper install

And then run a normal make build.

5.11.10 - What is the best way to update /etc, /var, and /dev?

As a policy, software in the OpenBSD tree does not modify files in /etc automatically. This means it is always up to the administrator to make the necessary modifications there. Upgrades are no exception. To update files in these directories, first determine what changes have occurred to the base (distribution) files, and then manually reapply these changes.

For example, to see the files in the tree that have changed most recently, do a: # cd /usr/src/etc # ls -lt |more

To see all the changes in /etc between arbitrary versions of OpenBSD, you can use CVS. For example, to see the changes between 4.1 and 4.2 do a: # cd /usr/src/etc # cvs diff -u -rOPENBSD_4_1 -rOPENBSD_4_2 To see the changes between 4.2 and -current ("HEAD"), use: # cd /usr/src/etc # cvs diff -u -rOPENBSD_4_2 -rHEAD The /dev/MAKEDEV script is not updated automatically as part of the make build process, however it is installed as as part of a binary upgrade. As a general rule, it is a good idea to copy (if needed) and run this script from your source tree when performing an upgrade: # cd /dev # cp /usr/src/etc/etc.`machine`/MAKEDEV ./ # ./MAKEDEV all

Once you have identified the changes, reapply them to your local tree, preserving any local configuration you may have done.

Typical /etc changes to watch out for between releases include:

• Additions to /etc/protocols and /etc/services
• New sysctls (see /etc/sysctl.conf)
• Changes to the default cron jobs. See /etc/daily, /etc/weekly, /etc/monthly, and /etc/security
• All rc scripts, including netstart
• Device changes, see above
• File hierarchy changes in /etc/mtree, see below
• New users (/etc/passwd) and groups (/etc/group)

5.11.11 - Is there an easy way to make all the file hierarchy changes?

From time to time, files or directories are added to, or removed from the file hierarchy. Also, ownership information for portions of the filesystem may change. An easy way to ensure that your file hierarchy is up-to-date is to use the mtree(8) utility.

First, fetch the latest source, then do the following: # cd /usr/src/etc/mtree # install -c -o root -g wheel -m 600 special /etc/mtree # install -c -o root -g wheel -m 444 4.4BSD.dist /etc/mtree # mtree -qdef /etc/mtree/4.4BSD.dist -p / -u

Your file hierarchy should now be up to date.

5.11.12 - Can I cross-compile? Why not?

When the developers bring up support for a new platform, one of the first big tests is a native-build. Building the system from source puts considerable load on the OS and machine, and does a very good job of testing how well the system really works. For this reason, OpenBSD does all the build process on the platform the build is being used for, also known as "native building". Without native building, it is much more difficult to be sure that the various platforms are actually running reliably, and not just booting.

[FAQ Index] [To Section 4 - Installation Guide] [To Section 6 - Networking]