How to Compile a Kernel with Debugging Symbols on FreeBSD

Introduction

FreeBSD is a powerful Unix-like operating system used for servers, embedded systems, and desktop environments. When troubleshooting kernel-related issues, developers and system administrators often need to compile a kernel with debugging symbols. This allows them to analyze crashes, track down bugs, and use tools like kgdb for post-mortem debugging.

This guide provides step-by-step instructions for compiling a FreeBSD kernel with debugging symbols enabled.

Prerequisites

Before proceeding, ensure you have:

• A FreeBSD system (preferably running a supported release such as FreeBSD 13.x or later)
• Root privileges or access to sudo
• Adequate disk space (compiling a kernel with debugging symbols requires significant storage)
• Basic knowledge of FreeBSD system administration

Step 1: Update the FreeBSD Source Tree

To build a kernel, you need the FreeBSD source tree. If you haven’t installed it yet, follow these steps:

sudo mkdir -p /usr/src
sudo git clone --branch stable/13 https://git.FreeBSD.org/src.git /usr/src

If you already have the source tree, update it with:

cd /usr/src
sudo git pull

Ensure you’re on the correct branch for your FreeBSD version. If unsure, check the currently running version:

freebsd-version -k

Step 2: Configure the Kernel

Navigate to the kernel configuration directory:

cd /usr/src/sys/amd64/conf  # Replace amd64 with your architecture if different

Copy the default kernel configuration file:

sudo cp GENERIC MYKERNEL

Edit the MYKERNEL file using a text editor like vi or nano:

sudo vi MYKERNEL

To enable debugging symbols, ensure the following lines are present or uncommented:

makeoptions DEBUG=-g
options        DDB                      # Enable the kernel debugger
options        GDB                      # Enable remote GDB debugging
options        KDB                      # Kernel Debugger Framework
options        KDB_TRACE                 # Print stack traces on panic

Save and exit the editor.

Step 3: Build the Kernel

Before compiling, clean previous build artifacts (optional but recommended):

cd /usr/src
sudo make clean

Now, compile the kernel with debugging symbols:

sudo make -j$(sysctl -n hw.ncpu) buildkernel KERNCONF=MYKERNEL

This command uses the number of available CPU cores for faster compilation.

The process may take a significant amount of time, depending on your hardware.

Step 4: Install the Kernel

Once the build completes successfully, install the newly compiled kernel:

sudo make installkernel KERNCONF=MYKERNEL

Reboot your system to load the new kernel:

sudo reboot

After rebooting, verify the installed kernel:

uname -v

It should indicate the use of MYKERNEL.

Step 5: Verify Debugging Symbols

To confirm that debugging symbols are included, check the installed kernel binary:

file /boot/kernel/kernel

The output should show not stripped, meaning symbols are present.

For further validation, use gdb:

gdb /boot/kernel/kernel.debug

If gdb loads the symbols successfully, the setup is correct.

Step 6: Enable Kernel Debugging

If you encounter a kernel panic, FreeBSD can generate core dumps for analysis. Ensure crash dumps are enabled:

echo 'dumpdev="AUTO"' | sudo tee -a /etc/rc.conf

To load the debugger manually, use:

gdb -k /boot/kernel/kernel.debug /var/crash/vmcore.X

Replace X with the actual crash dump number.

Step 7: Troubleshooting

Kernel Does Not Boot

If the new kernel fails to boot, restart into single-user mode and boot the previous kernel:

boot -s

Then, select the previous working kernel:

unload
load /boot/kernel.old/kernel
boot

Once in the system, revert to the previous kernel permanently:

sudo mv /boot/kernel /boot/kernel.broken
sudo mv /boot/kernel.old /boot/kernel

Reboot to confirm the change:

sudo reboot

Debugging Symbols Not Found

Ensure you compiled the kernel with makeoptions DEBUG=-g. If symbols are missing, try rebuilding:

sudo make clean
sudo make buildkernel KERNCONF=MYKERNEL
sudo make installkernel KERNCONF=MYKERNEL
sudo reboot

Conclusion

Compiling a FreeBSD kernel with debugging symbols is a crucial step for debugging system crashes and kernel development. By following this guide, you ensure that your system has the necessary tools for kernel debugging, making it easier to diagnose and resolve issues efficiently. Always back up critical data before making major system changes, and test kernels in a safe environment before deploying them in production.

For additional resources, consult the official FreeBSD Handbook or developer documentation.