The Use Case

FreeBSD installs a run-time kernel used during normal day-to-day operations. In the event of repeated kernel panics, there may be a need for a kernel capable of online debugging.

Patching sysinstall

sysinstall(8) lacks support for installing multiple kernel distributions in releases 8.3 or earlier. Patch r240972 was committed to stable/8 enabling support for a DEBUG kernel distribution. The procedure below patches the sources with bits necessary for the remainder of this post.

# cd /usr/src
# svn diff -c 240972 http://svn.freebsd.org/base/stable/8 > sysinstall_patch
# patch -p0 < sysinstall_patch

Replacing the string DEBUG in the patch changes the kernel distribution name.

Preparing The Build

The only prerequisite is having FreeBSD sources available and, optionally, ports. Ports is obtained via cvs or Subversion. Information on FreeBSD source trees are found here.

We assume a FreeBSD release build with two kernels, GENERIC and DEBUG, on the amd64 architecture. To avoid using CVS/SVN as part of the build process, it is helpful to have a local copy of ports and FreeBSD sources. In this example, ports is /usr/ports and the sources are /usr/src.

First we must buildworld:

# cd /usr/src && make buildworld

The Kernel Config

The FreeBSD release build process builds the GENERIC kernel by default. Adding an additional kernel is accomplished by first creating the kernel config file. We will create a kernel config called /usr/src/sys/amd64/conf/DEBUG. The kernel config should appear as follows:

include GENERIC
options KDB_UNATTENDED
options DDB

Compiling The Release

Now compile the release (as root, in bash):

This example builds a DVD image, no floppy images, no documentation, with ports and sources at /usr/ports and /usr/src, respectively. The DEBUG kernel and config file are defined by the KERNELS, KERNCONF, and INSTKERNNAME environment variables. Not all of these are required and operators may choose options not shown here. Information on available environment variables are found in the release(7) manpage. Many of these options can be set in /usr/src/release/Makefile.

The CVSROOT environment variable is non-optional. It is used to download ports and sources. If the environment variables EXTPORTSDIR and EXTSRCDIR are set, `make release` will not consult CVSROOT, despite being non-optional.

Executing/Using The Kernel

From the loader menu

Press 6 at the loader menu to escape to the loader(8) prompt and type:

boot DEBUG

From the running system

The DEBUG kernel is loaded by default when the kernel line in loader.conf appears as follows. Each subsequent boot loads the DEBUG kernel.

kernel=DEBUG

Dropping into the debugger

A kernel panic induces a system reboot unless debug.debugger_on_panic is enabled as follows:

sysctl debug.debugger_on_panic=1

To induce a panic:

sysctl debug.kdb.panic=1