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.
cd to /usr/src:
# cd /usr/src
Compile the new kernel by specifying the name of the custom kernel configuration file:
# make buildkernel KERNCONF=MYKERNEL
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 ntfsThis variable specifies the list of modules to build instead the default of building of all of them.
WITHOUT_MODULES = linux acpi sound ntfsThis 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.