5.0 - Kernel configuration

5.1 - Why would I want to create my own custom kernel?

Several reasons, although this practice is generally geared towards knowledgeable users who have a good overall understanding of the system.

Under most circumstances you will NOT need to compile your own kernel. The GENERIC kernel will usually be all that you need. In fact, there are several reasons why you do not want to create your own kernel. The main reason is that it is very easy to make changes to the kernel configuration which look logical, but do not work. This is your danger sign. If something does not appear to work properly, please try the GENERIC kernel before sending in a bug report.

5.2 - Kernel Configuration Options

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 multitudes 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 more complete list of options. You can also check the example configuration files that are available for your architecture.

Not all kernel options have been tested for compatibility with all other options. Don't put an option in your kernel unless you actually have a reason to do so! The one kernel configuration which gets the most testing is the GENERIC kernel. This is usually a combination of the options in /usr/src/sys/arch/<your arch>/conf/GENERIC and /usr/src/sys/conf/GENERIC.

Look closely at these files and you will notice a line like:
include "../../../conf/GENERIC"
This means that it is referencing yet another configuration file. This file stores non arch-dependent options. So when creating your Kernel Config be sure to look through /sys/conf/GENERIC and see what you want. There ARE options in there that are NEEDED.

All of the options listed below should be placed in your kernel configuration file in the format of:
option OPTION
for example. To place option debug in the kernel, add a line like this:
option DEBUG
Options in the OpenBSD kernel are translated into compiler preprocessor options, therefore an option like DEBUG would have the source compiled with option -DDEBUG. Which is equivalent to doing a #define DEBUG throughout the kernel.

OpenBSD has a great many compatibility options which allow you to use binaries from other OS's. Not all are availibly on every architechture, so be sure to read the man pages for each option to see if your arch is supported.

It is always helpful to be able to debug problems with the kernel. But many choose not to put these options in their kernel because these options add considerable size to the kernel. They are however extremely helpful in a case where a bug might be present. This well help the developers discover the source of your problems much quicker. Here is a list of popular debugging options that can be added to your kernel.

Filesystem Options.

Misc. Options

Networking Options
Also check the Networking FAQ or the Networking Performance Tuning FAQ.

PCVT Options (only valid on i386 architecture)

SCSI Subsystem Options

5.3 - Building your own kernel

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

To compile your kernel from the cdrom you need to first have the source code available. You just need the kernel source to be able to compile the kernel, and this source code is available on the cd. Here is how to copy the sources from the cd. This example assumes that CD1 is mounted on /mnt.

Now to create your custom kernel it is easiest to start with the GENERIC kernel. This is located at /usr/src/sys/arch/${arch}/conf/GENERIC, where ${arch} is your architecture. There are other sample configurations available in that directory as well. Here are two examples for compiling your kernel. The first example is compiling your kernel on a read-only source tree. The second on a writeable source tree.

To compile a kernel inside a writeable source tree do the following:

Where $ARCH is the architecture you are using (e.g. i386). You can also do a make depend to make the dependencies for the next time you compile your kernel.

To move your kernel into place.

To revert to your old kernel at boot you need to just

and your old kernel will be loaded instead of /bsd.

Sometimes when you build a new kernel you will be required to install new bootblocks. To do so, read faq14.8 on OpenBSD's Bootloader. Which will give you an overview on using OpenBSD's Bootloader

5.4 - 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 by fixing and recompiling your kernel. 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, at boot time us the -c option.

Or whichever kernel it is you want to boot. Doing this will bring up a UKC prompt. From here you can issue commands directly to the kernel specifying devices you want to change or disable or even enable.

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 get your device configured, use quit or exit and continue booting. After doing so you should correct your Kernel configuration and Compile a new kernel. Refer to Building your own kernel for help.

5.5 - Getting more verbose output during boot

Getting more verbose output can be very helpful when trying to debug problems when booting. If you have a problem wherein your boot floppy won't boot and need to get more information, simply reboot. When you get to the "boot>" prompt, boot with boot -c. This will bring you into the UKC>, then do:

Now you will be given extremely verbose output upon boot.

5.6 - Using config(8) to change your kernel

With 2.6 came the introduction of the -e and -u options with config(8). These options 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 from 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.

In the above example, all ep* devices are removed from 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.

[Back to Main Index] [To Section 4.0 - Installation Guide] [To Section 6.0 - Networking]

[back] www@openbsd.org
$OpenBSD: faq5.html,v 1.46 2001/01/27 22:19:47 ericj Exp $