9.3 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/sys directory, which is also accessible through /sys. There are a number of subdirectories here representing different parts of the kernel, but the most important, for our purposes, are arch/conf, where you will edit your custom kernel configuration, and compile, which is the staging area where your kernel will be built. arch represents either i386, alpha, or pc98 (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 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. FreeBSD 5.X and up has support for sparc64, and a few other architectures under development.

Note: If there is not a /usr/src/sys directory on your system, then the kernel source has not been installed. The easiest way to do this is by running /stand/sysinstall as root, choosing Configure, then Distributions, then src, then sys. If you have an aversion to sysinstall and you have access to an ``official'' FreeBSD CDROM, then you can also install the source from the command line:
# mount /cdrom
# mkdir -p /usr/src/sys
# ln -s /usr/src/sys /sys
# cat /cdrom/src/ssys.[a-d]* | tar -xzvf -

Next, move to the arch/conf directory 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 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 it MYKERNEL for the purpose of this example.

Tip: Storing your kernel config file directly under /usr/src can be a bad idea. If you are experiencing problems it can be tempting to just delete /usr/src and start again. Five seconds after you do that you realize that you have deleted your custom kernel config file. Do not edit GENERIC 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 config file elsewhere, and then create a symbolic link to the file in the i386 directory.

For example:
# cd /usr/src/sys/i386/conf
# mkdir /root/kernels
# cp GENERIC /root/kernels/MYKERNEL   
# ln -s /root/kernels/MYKERNEL

Note: You must execute these and all of the following commands under the root account or you will get permission denied errors.

Now, edit MYKERNEL with 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 from GENERIC.

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, the GENERIC configuration file might seem overwhelming to you, so follow the descriptions in the Configuration File section slowly and carefully.

Note: Be sure to always check the file /usr/src/UPDATING, before you perform any update steps, in the case you sync your source tree with the latest sources of the FreeBSD project. In this file all important issues with updating FreeBSD are typed out. /usr/src/UPDATING always fits your version of the FreeBSD source, and is therefore more accurate for new information than the handbook.

You must now compile the source code for the kernel. There are two procedures you can use to do this, and the one you will use depends on why you are rebuilding the kernel, and the version of FreeBSD you are running.

If you have installed only the kernel source code, use procedure 1.
If you are running a FreeBSD version prior to 4.0, and you are not upgrading to FreeBSD 4.0 or higher using the make world procedure, use procedure 1.
If you are building a new kernel without updating the source code (perhaps just to add a new option, such as IPFIREWALL) you can use either procedure.
If you are rebuilding the kernel as part of a make world process, use procedure 2.

Procedure 1. Building a Kernel the ``Traditional'' Way

Run config(8) to generate the kernel source code.
```
# /usr/sbin/config MYKERNEL
```
Change into the build directory. This is printed out after running the aforementioned command.
```
# cd ../compile/MYKERNEL
```
For FreeBSD version prior to 5.0, use instead:
```
# cd ../../compile/MYKERNEL
```
Compile the kernel.
```
# make depend
# make
```
Install the new kernel.
```
# make install
```

Procedure 2. Building a Kernel the ``New'' Way

Change to the /usr/src directory.
```
# cd /usr/src
```
Compile the kernel.
```
# make buildkernel KERNCONF=MYKERNEL
```
Install the new kernel.
```
# make installkernel KERNCONF=MYKERNEL
```

Note: In FreeBSD 4.2 and older you must replace KERNCONF= with KERNEL=. 4.2-STABLE that was fetched before Feb 2nd, 2001 does not recognize KERNCONF=.

If you have not upgraded your source tree in any way since the last time you successfully completed a buildworld-installworld cycle (you have not run CVSup, CTM, or used anoncvs), then it is safe to use the config, make depend, make, make install sequence.

The new kernel will be copied to the root directory as /kernel and the old kernel will be moved to /kernel.old. Now, shutdown the system and reboot to use your new kernel. In case something goes wrong, there are some troubleshooting instructions at the end of this chapter. Be sure to read the section which explains how to recover in case your new kernel does not boot.

Note: As of FreeBSD 5.0, kernels are installed along with their modules in /boot/kernel, and old kernels will be backed up in /boot/kernel.old. Other files relating to the boot process, such as the boot loader(8) and configuration are also stored in /boot. Third party or custom modules may be placed in /boot/modules, although users should be aware that keeping modules in sync with the compiled kernel is very important. Modules not intended to run with the compiled kernel may result in instability or incorrectness.

Note: If you have added any new devices (such as sound cards) and you are running FreeBSD 4.X or previous versions, you may have to add some device nodes to your /dev directory before you can use them. For more information, take a look at Making Device Nodes section later on in this chapter.