FreeBSD Handbook
Prev | Chapter 9 Configuring the FreeBSD Kernel | Next

# 9.5 Building and Installing a Custom Kernel

> Note: It is required to have the full FreeBSD source tree installed to build the kernel.

The kernel build is located at `/usr/src/sys`. It contains a number of subdirectories representing different parts of the kernel. These include ``arch`/conf`, which contains the kernel configuration file, and `compile`, which is the staging area where the kernel will be built. `arch` contains subdirectories for each supported architecture: `i386`, `amd64`, `ia64`, `powerpc`, `sparc64`, and `pc98`. Everything inside a particular architecture's directory deals with that architecture only and the rest of the code is machine independent code common to all platforms. Notice the logical organization of the directory structure, with each supported device, file system, and option in its own subdirectory.

The examples in this chapter assume the i386 architecture. If the system has a different architecture, change the path names accordingly.

> Note: If `/usr/src/` does not exist or it is empty, source has not been installed. The easiest way to install source is to use svn as described in . One should also create a symlink to `/usr/src/sys/`:

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

Next, cd to ``arch`/conf` and copy the `GENERIC` configuration file to the name of the custom kernel. For example:

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

Traditionally, this name is in all capital letters. When maintaining multiple FreeBSD machines with different hardware, it is a good idea to name it after the machine's hostname. This example uses ``MYKERNEL``.

> Tip: When finished customizing the kernel configuration file, save a backup copy to a location outside of `/usr/src`. Do not edit `GENERIC` directly.

> Alternately, keep the kernel configuration file elsewhere and create a symbolic link to the file in ``i386``.

> For example:

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

Edit ``MYKERNEL`` with a text editor. The default editor is vi, whose usage is covered well in many books in the bibliography. An easier editor for beginners, called ee, is also available. Feel free to change the comment lines at the top to reflect the configuration or the changes made to differentiate it from `GENERIC`.

If the `GENERIC` configuration file seems overwhelming, follow the descriptions in the Configuration File section slowly and carefully.

> Note: After syncing the source tree with the latest sources, always read `/usr/src/UPDATING` before performing any update steps. This file describes any important issues or areas requiring special attention within the updated source code. `/usr/src/UPDATING` always matches the version of the FreeBSD source and contains more up-to-date information than this Handbook.

After saving the edits, compile the source code for the kernel.

Building a Kernel

> Note: It is required to have the full FreeBSD source tree installed to build the kernel.

1. `cd` to `/usr/src`:

       # cd /usr/src

2. Compile the new kernel by specifying the name of the custom kernel configuration file:

       # make buildkernel KERNCONF=MYKERNEL

3. Install the new kernel:

       # make installkernel KERNCONF=MYKERNEL

> Tip: By default, when a custom kernel is compiled, all kernel modules are rebuilt as well. To update a kernel faster or to build only custom modules, edit `/etc/make.conf` before starting to build the kernel:

>     MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs

> This variable specifies the list of modules to build instead the default of building of all of them.

>     WITHOUT_MODULES = linux acpi sound ntfs

> This variable sets up a list of top level modules to exclude from the build process. For other available variables, refer to make.conf(5).

The new kernel will be copied to `/boot/kernel` as `/boot/kernel/kernel` and the old kernel will be moved to `/boot/kernel.old/kernel`. Now, shutdown the system and reboot into the new kernel. If something goes wrong, refer to the troubleshooting instructions and the section which explains how to recover when the new kernel does not boot.

> Note: Other files relating to the boot process, such as the boot loader(8) and configuration, are stored in `/boot`. Third party or custom modules can be placed in `/boot/kernel`, 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.

Prev | Home | Next
Kernel Drivers, Subsystems, and Modules | Up | The Configuration File