Configuration Files

OpenBSD divides the configuration process into machine-dependent and machine-independent sections.

Machine-Independent Configuration

The machine-independent configuration files can be found in the directory /usr/src/sys/conf. If you are interested in reading kernel source code, this is a decent place to start. If all you want to do is build a kernel, you're mostly interested in the GENERIC file. This file contains the kernel configuration information that is identical on each of the hardware platforms OpenBSD runs on. Every kernel built on OpenBSD, by default, contains this file. Any change made to the machine-independent section of the system occurs in every OpenBSD kernel.

The machine-independent configuration file won't contain device drivers; devices are tied to particular hardware. It also won't contain any special building instructions, because they vary from hardware to hardware. It won't contain hardcoded system limits, data structure sizes, and so on; those vary from hardware to hardware. As you can imagine, an OpenBSD system running on a 15-year-old VAX has considerably fewer system resources than a modern Pentium IV-based i386 system! So, what's left? Options and pseudo-devices. For example, every OpenBSD kernel must support a file system or it won't be able to write anything to disk.

 option       FFS          # UFS 

The kernel doesn't know, yet, what sort of hardware this file system will be on, but it knows how to make a file system. Similarly, every OpenBSD system supports the integrated packet filter (see Chapter 15), networking (Chapter 9), and so on.

Machine-Dependent Configuration

Machine-dependent kernel source lies somewhere under the directory /usr/src/ sys/arch. This directory contains a directory for each hardware platform OpenBSD supports. It also contains some "work in progress" architectures, which are not yet fully supported. While this book focuses on the i386 platform, or the "standard PC," the process of kernel building is the same across all hardware platforms. The kernel configuration directory is in the conf subdirectory of the platform directory; in our case, we want to look at /usr/src/sys/arch/i386/conf.

Traditionally, a kernel configuration file is in all capital letters. Here you'll see the GENERIC kernel, as well as a few special-purpose configuration files. The RAMDISK, RAMDISKB, and RAMDISKC files are the kernel configurations for the installation floppy disk images A, B, and C, respectively. The DISKLESS file is a sample configuration for diskless OpenBSD workstations. For the moment, let's look at the GENERIC kernel config file.

The very first entry in this file identifies the type of hardware you're using.

 machine      i386 

The configuration program uses this check your configuration, so it can notify you of any mistakes. It won't allow you to include Sun-specific hardware on an i386, for example. Different hardware also has a variety of different low-level characteristics, such as the number of bits in different types of C data structures, and the kernel needs to know about them.

Another early entry in this file is a special configuration instruction.

 include "../../../conf/GENERIC" 

When you configure the kernel, the configuration tool will automatically grab the machine-independent configuration. This means that you don't have to worry about all of the very basic stuff, such as file systems and network stacks; the building process will automatically include them.

These configuration files contain the information specific to the hardware, such as device drivers and hardware-dependent options.

Take a moment and skim the hardware-dependent configuration file. There are a few hundred lines here! How can you possibly wade through all of this? Like so many other things in UNIX, it's not hard once you know what you're doing.

Your Kernel Configuration File

To build your own kernel, you need a configuration file. Do not just edit the GENERIC kernel file; that's a system file, and it will be overwritten when you upgrade or reinstall. Once you've spent some time tweaking your kernel, the last thing you want to do is destroy the record of how you assembled it! Traditionally, custom kernels are named after the machine they're built for, and the filenames are all in capital letters. For example, my computer named "openbsdtest" has a kernel configuration of OPENBSDTEST.

You also need to decide whether you want to have a single configuration file or maintain the split between machine-dependent and machine-independent files. When you build your first kernel, I recommend keeping the split. You will have enough trouble trying to build a usable kernel without messing with the required items in the machine-independent section. Most of what is in the machine-independent configuration is absolutely required to build a normally working OpenBSD system. In either case, it's simplest to start with the GENERIC configuration.

If you want to keep the split, just copy the machine-dependent GENERIC configuration to a file of the name you want in the same directory.

 # cp GENERIC OPENBSDTEST 

If you want to have one configuration file containing both machine-independent and machine-dependent information, just combine the files in the machinedependent configuration directory. (This file will be machine-dependent, after all!) Then edit this file to remove the line that includes the machine-independent configuration file.

You might be tempted to use the material in Appendix A to create your own kernel configuration. You're certainly free to do that, if you are either a Kernel Lord or an irremediable "doofus." Anyone who has been there before would highly recommend you start with the GENERIC configuration and edit that. The interdependencies are complicated enough that building a configuration from scratch is almost certainly doomed to fail.

Now that you have a kernel configuration of your own, let's see what we can do with it.