9.5. Building and Installing a Custom Kernel

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

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.

Warning:

It is easy to remove support for a device or option and end up with a broken kernel. For example, if the ata(4) driver is removed from the kernel configuration file, a system using ATA disk drivers may not boot. When in doubt, just leave support in the kernel.

Procedure 9.1. 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.

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.