Configuring the FreeBSD Kernel

Updated and restructured by Jim Mock. Originally contributed by Jake Hamby.

8.1 Synopsis

The kernel is the core of the FreeBSD operating system. It is responsible for managing memory, enforcing security controls, networking, disk access, and much more. While more and more of FreeBSD becomes dynamically configurable it is still occasionally necessary to reconfigure and recompile your kernel.

After reading this chapter, you will know:

• Why you might need to build a custom kernel.

• How to write a kernel configuration file, or alter an existing configuration file.

• How to use the kernel configuration file to create and build a new kernel.

• How to install the new kernel.

• How to troubleshoot if things go wrong.

All of the commands listed within this chapter by way of example should be executed asrootin order to succeed.

8.2 Why Build a Custom Kernel?

Traditionally, FreeBSD has had what is called a “monolithic” kernel. This means that the kernel was one large program, supported a fixed list of devices, and if you wanted to change the kernel’s behavior then you had to compile a new kernel, and then reboot your computer with the new kernel.

Today, FreeBSD is rapidly moving to a model where much of the kernel’s functionality is contained in modules which can be dynamically loaded and unloaded from the kernel as necessary. This allows the kernel to adapt to new hardware suddenly becoming available (such as PCMCIA cards in a laptop), or for new functionality to be brought into the kernel that was not necessary when the kernel was originally compiled. This is known as a modular kernel.

Despite this, it is still necessary to carry out some static kernel configuration. In some cases this is because the functionality is so tied to the kernel that it can not be made dynamically loadable. In others it may simply be because no one has yet taken the time to write a dynamic loadable kernel module for that functionality.

Building a custom kernel is one of the most important rites of passage nearly every BSD user must endure. This process, while time consuming, will provide many benefits to your FreeBSD system. Unlike theGENERICkernel, which must support a wide range of hardware, a custom kernel only contains support for your PC’s hardware. This has a number of benefits, such as:

• Faster boot time. Since the kernel will only probe the hardware you have on your system, the time it takes your system to boot can decrease dramatically.

• Lower memory usage. A custom kernel often uses less memory than theGENERICkernel, which is important because the kernel must always be present in real memory. For this reason, a custom kernel is especially useful on a system with a small amount of RAM.

• Additional hardware support. A custom kernel allows you to add in support for devices which are not present in theGENERICkernel, such as sound cards.

8.3 Finding the System Hardware

Written by Tom Rhodes.

Before venturing into kernel configuration, it would be wise to get an inventory of the machine’s hardware. In cases where FreeBSD is not the primary operating system, the inventory list may easily be created by viewing the current operating system configuration. For example, Microsoft’s Device Manager normally contains important information about installed devices. The Device Manager is located in the control panel.

Note: Some versions of Microsoft Windows have a System icon which will display a screen where Device Manager may be accessed.

If another operating system does not exist on the machine, the administrator must find this information out manually.

One method is using the dmesg(8) utility and the man(1) commands. Most device drivers on FreeBSD have a manual page, listing supported hardware, and during the boot probe, found hardware will be listed. For example, the

following lines indicate that thepsmdriver found a mouse:

psm0: <PS/2 Mouse> irq 12 on atkbdc0 psm0: [GIANT-LOCKED]

psm0: [ITHREAD]

psm0: model Generic PS/2 mouse, device ID 0

This driver will need to be included in the custom kernel configuration file or loaded using loader.conf(5).

On occasion, the data fromdmesgwill only show system messages instead of the boot probe output. In these situations, the output may be obtained by viewing the/var/run/dmesg.bootfile.

Another method of finding hardware is by using the pciconf(8) utility which provides more verbose output. For example:

ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00 vendor = ’Atheros Communications Inc.’

device = ’AR5212 Atheros AR5212 802.11abg wireless’

class = network subclass = ethernet

This bit of output, obtained usingpciconf -lvshows that theathdriver located a wireless Ethernet device. Using man athwill return the ath(4) manual page.

The-kflag, when passed to man(1) can also be used to provide useful information. From the above, one can issue:

# man -k Atheros

To get a list of manual pages which contain that particular word:

ath(4) - Atheros IEEE 802.11 wireless network driver ath_hal(4) - Atheros Hardware Access Layer (HAL)

Armed with a hardware inventory list, the process of building a custom kernel should appear less daunting.

8.4 Kernel Drivers, Subsystems, and Modules

Before building a custom kernel, consider the reasons for doing so. If there is a need for specific hardware support, it may already exist as a module.

Kernel modules exist in the/boot/kerneldirectory and may be dynamically loaded into the running kernel using kldload(8). Most, if not all kernel drivers have a specific module and manual page. For example, the last section noted theathwireless Ethernet driver. This device has the following information in its manual page:

Alternatively, to load the driver as a module at boot time, place the following line in loader.conf(5):

if_ath_load="YES"

As instructed, adding theif_ath_load="YES"line to the/boot/loader.conffile will enable loading this module dynamically at boot time.

In some cases; however, there is no associated module. This is mostly true for certain subsystems and very important drivers, for instance, the fast file system (FFS) is a required option in the kernel. As is network support (INET).

Unfortunately the only way to tell if a driver is required is to check for the module itself.

Warning: It is considerably easy to remove built in support for a device or option and have a broken kernel. For example, if the ata(4) driver is pulled from the kernel configuration file, a system using ATA disk drivers may not boot without the line added toloader.conf. When in doubt, check for the module and then just leave support in the kernel.

8.5 Building and Installing a Custom Kernel

First, let us take a quick tour of the kernel build directory. All directories mentioned will be relative to the main /usr/src/sysdirectory, which is also accessible through the path name/sys. There are a number of

subdirectories here representing different parts of the kernel, but the most important for our purposes arearch/conf, where you will edit your custom kernel configuration, andcompile, which is the staging area where your kernel will be built.archrepresents one ofi386,alpha,amd64,ia64,powerpc,sparc64, orpc98(an alternative

development branch of PC hardware, popular in Japan). Everything inside a particular architecture’s directory deals with that architecture only; the rest of the code is machine independent code common to all platforms to which FreeBSD could potentially be ported. Notice the logical organization of the directory structure, with each supported device, file system, and option in its own subdirectory.

This chapter assumes that you are using the i386 architecture in the examples. If this is not the case for your situation, make appropriate adjustments to the path names for your system’s architecture.

Note: If there is not a/usr/src/sysdirectory on your system, then the kernel source has not been installed.

The easiest way to do this is by runningsysinstallasroot, choosing Configure, then Distributions, then src,

# mount /cdrom

# mkdir -p /usr/src/sys

# ln -s /usr/src/sys /sys

# cat /cdrom/src/ssys.[ad]* | tar xzvf

# cat /cdrom/src/sbase.[ad]* | tar xzvf

-Next, move to thearch/confdirectory and copy theGENERICconfiguration file to the name you want to give your kernel. For example:

# cd /usr/src/sys/i386/conf

# cp GENERIC MYKERNEL

Traditionally, this name is in all capital letters and, if you are maintaining multiple FreeBSD machines with different hardware, it is a good idea to name it after your machine’s hostname. We will call itMYKERNELfor the purpose of this example.

Tip: Storing your kernel configuration file directly under/usr/srccan be a bad idea. If you are experiencing problems it can be tempting to just delete/usr/srcand start again. After doing this, it usually only takes a few seconds for you to realize that you have deleted your custom kernel configuration file. Also, do not editGENERIC directly, as it may get overwritten the next time you update your source tree, and your kernel modifications will be lost.

You might want to keep your kernel configuration file elsewhere, and then create a symbolic link to the file in the

i386directory.

Now, editMYKERNELwith your favorite text editor. If you are just starting out, the only editor available will probably be vi, which is too complex to explain here, but is covered well in many books in the bibliography. However, FreeBSD does offer an easier editor called ee which, if you are a beginner, should be your editor of choice. Feel free to change the comment lines at the top to reflect your configuration or the changes you have made to differentiate it fromGENERIC.

If you have built a kernel under SunOS or some other BSD operating system, much of this file will be very familiar to you. If you are coming from some other operating system such as DOS, on the other hand, theGENERIC configuration file might seem overwhelming to you, so follow the descriptions in the Configuration File section slowly and carefully.

Note: If you sync your source tree with the latest sources of the FreeBSD project, be sure to always check the file/usr/src/UPDATINGbefore you perform any update steps. This file describes any important issues or areas requiring special attention within the updated source code./usr/src/UPDATINGalways matches your version of the FreeBSD source, and is therefore more up to date with new information than this handbook.