Many open source operating systems encourage sysadmins to build custom kernels. Mailing lists for these operating systems are full of suggestions on rebuilding, tweaking, and modifying the kernel. Those user communities will walk new users through rebuilding the kernel.

OpenBSD developers take a different approach to rebuilding the kernel. They ship a default kernel, called GENERIC, which you will almost never need to rebuild.

Building a kernel from source doesn’t prove that you’re an alpha geek, and rebuilding the kernel is never a recommended way to solve a problem. The people who build custom kernels are either kernel developers or ignorant newbies. The OpenBSD Project members feel no particular obligation to help users with customized kernels. If your custom kernel crashes, destroys your filesystem, or starts making threatening calls to the local constabulary, they won’t care. Why? Adding, moving, or changing one kernel option might seem trivial, but each option might represent tens of thousands of lines of source code that you’ve just casually gutted.

That said, the OpenBSD Project is much friendlier than closed source operating systems, in that it provides the source code for the kernel, and gives you the tools and instructions needed to build it. The territory might be dangerous, with rattlesnakes and bears and the occasional bottomless pit, but they give you a map and a flashlight. If you can carve out some new territory for yourself, good for you! If you get eaten by coyotes, well, that’s pretty much what happens.

When working with kernels, keep in mind that some platforms have multiple GENERIC kernels. For example, the i386 platform has the standard GENERIC kernel, but it provides GENERIC.MP for multiprocessor machines, and it supports both versions. By the same token, the SGI platform has several GENERIC kernels—one for each supported hardware variety. These kernels are all GENERIC, and all supported.

People build custom kernels for various reasons. For example, if you’re a kernel developer, or aspire to be one, you will need to build customized kernels to test new features and new code.

Some people who play with kernels are interested in using experimental features. For example, OpenBSD supports the newly developed but not well-tested multipath SCSI, which is not supported by GENERIC. Not many people have the hardware to use multipath SCSI, but those who do have the hardware, along with programming skills, are encouraged to help improve this feature. (When running experimental features, be sure that you understand that experimental is the Siamese twin of unstable.)

Rarely, remediating a security flaw will require a patch to the kernel source code. But rather than build your own, get the patch from OpenBSD’s stable branch or a snapshot (discussed in Chapter 20).

Finally, some people will build custom kernels to save RAM on a machine with very low memory. Removing features from the kernel reduces its size.

When building a custom kernel, you are likely to run into trouble. For one, the interdependencies between kernel modules are quite complex and not thoroughly documented. The developers generally assume that people building custom kernels will read kernel source code and man pages. You are expected to read error messages and sort them out yourself.

OpenBSD’s cross-platform design slightly complicates kernel configuration. Some devices run on some architectures, but they fail to run or behave weirdly on others. If you include the wrong device in your kernel or tell the kernel a card is attached to the wrong bus, you’ll be building a busted kernel. Be sure that you understand how your hardware actually fits together.

When mucking around in the source tree, you can corrupt the source code in various ways, such as by applying a patch incorrectly, scrambling a file, or forgetting that you edited a file that is now causing you grief. To test your source code, compile GENERIC. If GENERIC won’t compile, you’ve either mucked up the source code or your system has some deeper problem.

Building a custom kernel usually means including or removing kernel options and features from the configuration file. If you’re trying to use fancy compiler flags, however, stop. Custom compiler options are great for exposing compiler bugs, but the OpenBSD team members make no effort to have their code comply with the demands from these compiler options. Many of these options and higher optimizations break if you’re not running very specific operating systems on very specific architectures. The kernel code assumes that you are using the specified compiler options; if you change them, you’ll get nothing but pain.

If you’ve checked everything, and you still can’t get your kernel to build, you might don your flameproof suit and ask for help on [email protected]. State up front that you’re trying to build a custom kernel, and include the following information:

Someone might take pity and try to help you.

Custom kernels can have any number of problems, such as the following:

If you have customized your kernel narrowly—say, by adding only the multipath SCSI driver to the GENERIC kernel—the developers working on that feature will probably be interested in your bug reports on that feature.

If you can reproduce that problem when the same system boots with the GENERIC kernel, the OpenBSD team is definitely interested. Report your problem as occurring on the GENERIC kernel, and include debugging output only from GENERIC, not from your custom kernel. If you manage to identify, debug, and create a patch for a problem with a custom kernel, send your patch and a problem description to the mailing list. Your problem may be due to running on a custom kernel, but you may also have found a bug that could be triggered in GENERIC.

But most important, if you have a problem running a custom kernel, reboot with GENERIC and get on with your day.