Custom kernels

So far, everything we've done has been with the standard GENERIC kernel distributed with FreeBSD. You may find it an advantage to install a custom kernel:

• As we saw in "Chapter 2" , GENERIC doesn't support everything that FreeBSD knows about. For example, if you want to install a Yoyodyne frobulator, you'll need to install special support for it^{1 In fact, the developer working on the Yoyodyne has defected to the Free Software Foundation. See the GNU General Public License for further details} .
• It will take less time to boot because it does not have to spend time probing for hardware that you do not have.
• A custom kernel often uses less memory. The kernel is the one system component that must always be present in memory, so unused code ties up memory that would otherwise be available to the virtual memory system. On a system with limited RAM, you can save some memory by building a custom kernel, but don't overestimate the savings: a minimal kernel might save 500 kB over the GENERIC kernel supplied with the system.
• In addition, there are several kernel options that you can tune to fit your needs.
• Finally, on page 622 we'll look at things to think about if you want to run the -CURRENT version of FreeBSD.

In older releases of BSD, you needed to build a new kernel for just about anything you wanted to change, even things as simple as a different IRQ for a device. FreeBSD has evolved quite a bit since then, and it's becoming increasingly less necessary to build a custom kernel. You will certainly need to do so if you want to enable kernel-wide options, such as extra consistency checking, but in many cases you have more flexible alternatives:

• If you just need to add device support, you may be able to load a Kernel Loadable Module, or kld. See page 620 for more information on klds.
• If you want to change ISA parameters such as I/O address, IRQ or DMA settings, you no longer need to build a new kernel: the kernel configuration file no longer knows about such parameters. Instead, they're in the file /boot/device.hints, that we'll look at below.
• A number of kernel options have been replaced by the sysctl interface. For example, the GENERIC kernel does not perform packet routing by default. In older releases of FreeBSD, you had to build a new kernel with the option GATEWAY. Nowadays you can turn this feature on and off at will with a sysctl command. We'll look at sysctls on page

Configuring a kernel has changed a lot since the early days of FreeBSD, but it's not done yet. The information in this chapter represents a snapshot in the evolution of building kernels. The goal of these changes is to make it unnecessary to build a kernel at all except to upgrade to a new release.

Building a new kernel

FreeBSD is distributed in source, and building a kernel primarily involves compiling the source files needed for the kernel. To build a kernel, you perform the following steps:

• Install the system source, if you haven't already done so. We looked at that in "Chapter 31" .
• Define your kernel configuration in a kernel configuration file. This file defines parameters to use during the build process. We'll look at how to do this starting on page .
• Change to the directory /usr/src and run make kernel. This builds and installs the kernel and all modules. We'll look at it in more detail on page 617, where we'll also see alternatives that give more control over the process.

Configuring I/O devices

A lot of the configuration file relates to the I/O devices that you may connect to your machine. In older releases of FreeBSD, it was often necessary to specify some of the IRQ, DMA channel, board memory, and I/O addresses for the devices you configure, particularly for ISA boards. Since Release 5 of FreeBSD, this is no longer the case. Instead, you modify the file boot/device.hints, which we looked at on page 575.

The kernel installation does not install /boot/device.hints automatically. If it doesn't exist, copy it from the configuration directory:

# cp -p /usr/src/sys/i386/conf/GENERIC.h±nts /boot/device.hints

The kernel build directory

The kernel sources are kept in the directory /usr/src/sys. The symbolic link /sys also points to this directory. There are a number of subdirectories of /usr/src/sys that represent different parts of the kernel, but for our purposes, the most important of them are the architecture dependent directories such as /usr/src/sys/i386/conf (for the i386 architecture), /usr/src/sys/alpha/conf (for the Alpha architecture), or /usr/src/sys/sparc64/conf (for the SPARC64 architecture) where you edit your custom kernel configuration. In addition, the old style kernel build described below builds the kernel in the directory /usr/src/sys/i386/compile, /usr/src/sys/alpha/compile or /usr/src/sys/sparc64/compile respectively. Notice the logical organization of the directory tree: each supported device, file system, and option has its own subdirectory. In the rest of this chapter, we'll look at the i386 architecture. Most of this applies to other architectures as well.

If your system doesn't have the directory /usr/src/sys, the kernel source has not been installed. If you have a CD-ROM, the sources are on the first CD-ROM in the directory /src. To install from the CD-ROM, perform the following steps:

# mkdir -p /usr/src/sys
# ln -s /usr/src/sys /sys
# cd /
# cat /cdrom/src/ssys.[a-h]* | tar xzvf -

The symbolic link /sys for /usr/src/sys is not strictly necessary, but it's a good idea: some software uses it, and otherwise you may end up with two different copies of the sources.

By definition, the files on CD-ROM are out of date. See "Chapter 31" for details of how to get the current, up-to-date sources.

Next, move to the directory i386/conf and copy the GENERIC configuration file to the name you want to give your kernel. For example:

# cd /usr/src/sys/i386/conf
# cp GENERIC FREEBIE

Traditionally, this name is in all capital letters and, if you are maintaining multiple FreeBSD machines with different hardware, it's a good idea to name it after your machine's hostname. In this example we call it FREEBIE.

Now, edit FREEBIE with your favourite text editor. Change the comment lines at the top to reflect your configuration or the changes you've made to differentiate it from GENERIC:

#
# FREEBIE -- My personal configuration file
#
# For more information on this file, please read the handbook section on
# Kernel Configuration Files:
#
# http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig-config.html
#
# The handbook is also available locally in /usr/share/doc/handbook
# ifyou've installed the doc distribution, otherwise always see the
# FreeBSD World Wide Web server (http://www.FreeBSD.org/) for the
# latest information. 
#
# Anexhaustive list of options and more detailed explanations of the
# device lines is also present in the ../../conf/NOTES and NOTES files.
# Ifyou are in doubt as to the purpose or necessity of a line, check first
# inNOTES.
#
# $FreeBSD: src/sys/i386/conf/FREEBIE,v 1.369 2002/10/19 16:54:07 rwatson Exp $
machine    "i386"
cpu        "I486_CPU"
cpu       "I586_CPU"
cpu       "I686_CPU"
ident      FREEBIE
maxusers   0