How to Add Custom Kernel Options to `GENERIC` on FreeBSD

FreeBSD is a powerful and flexible Unix-like operating system widely used for servers, embedded systems, and networking devices. One of its key strengths is the ability to modify and optimize the kernel to meet specific needs. By customizing the GENERIC kernel configuration, users can add or modify options to improve performance, enhance security, or enable support for specific hardware and features.

This guide provides a step-by-step approach to adding custom kernel options to the GENERIC kernel in FreeBSD.

1. Understanding the FreeBSD Kernel Configuration

The FreeBSD kernel configuration is managed through configuration files stored in /usr/src/sys/ARCH/conf/, where ARCH represents the system’s architecture (e.g., amd64, i386). The default kernel configuration file, called GENERIC, includes the standard options required for most FreeBSD installations.

Customizing the GENERIC kernel involves either modifying the existing file or creating a custom configuration file based on GENERIC.

2. Preparing the System for Kernel Compilation

Before making any modifications, ensure that the FreeBSD source code is installed on the system. If it is not present, fetch it using:

# svnlite checkout https://svn.FreeBSD.org/base/releng/XX.X /usr/src

Replace XX.X with the specific FreeBSD version (e.g., 13.2).

Alternatively, if using Git (for newer versions of FreeBSD):

# git clone --branch releng/XX.X https://git.FreeBSD.org/src.git /usr/src

Once the source code is available, navigate to the correct directory:

# cd /usr/src/sys/ARCH/conf

3. Creating a Custom Kernel Configuration

Instead of modifying the GENERIC kernel file directly, it is recommended to create a custom configuration file. To do this, copy GENERIC to a new file (e.g., MYKERNEL):

# cp GENERIC MYKERNEL

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

# vi MYKERNEL

4. Adding Custom Kernel Options

a) Enabling Additional Hardware Support

To add support for specific hardware, find the relevant driver in /usr/src/sys/conf/files and add the appropriate line to MYKERNEL. For example, to include a custom network driver:

device    mynetwork

b) Modifying System Limits

To increase the maximum number of open files, add:

options   MAXFILES=65536

c) Enabling Debugging Features

For debugging purposes, include:

options   KDB
options   DDB
options   GDB

d) Removing Unnecessary Features

To optimize performance, remove unnecessary options by adding nooption or nodevice. For example, to disable IPv6:

nooptions  INET6

After making the necessary changes, save and exit the file.

5. Compiling and Installing the Custom Kernel

a) Building the Kernel

To compile the new kernel, run:

# cd /usr/src
# make buildkernel KERNCONF=MYKERNEL

This process may take some time, depending on the system’s performance.

b) Installing the Kernel

Once the build completes successfully, install the kernel using:

# make installkernel KERNCONF=MYKERNEL

The new kernel will be installed in /boot/kernel.

6. Rebooting and Verifying the Custom Kernel

After installation, reboot the system to load the new kernel:

# reboot

To verify that the custom kernel is running, use:

# uname -v

This should display MYKERNEL in the output.

7. Handling Kernel Boot Failures

If the system fails to boot, FreeBSD provides a fallback mechanism:

1. Reboot the machine and enter the boot menu.

2. Select Escape to loader prompt.

3. Load the GENERIC kernel manually:

   boot /boot/kernel.old/kernel
   

4. Once the system boots, revert to the GENERIC kernel by running:

   # mv /boot/kernel /boot/kernel.bad
   # mv /boot/kernel.old /boot/kernel
   

5. Reboot and troubleshoot the custom kernel configuration.

8. Keeping the Kernel Updated

To keep the custom kernel updated with FreeBSD releases, merge changes from GENERIC periodically. Compare differences with:

# diff GENERIC MYKERNEL

Apply necessary updates to ensure compatibility with future FreeBSD versions.

Conclusion

Customizing the FreeBSD kernel provides significant benefits in terms of performance, security, and hardware compatibility. By following the steps outlined above, users can safely modify the GENERIC kernel, add custom options, and maintain a stable system. Regular updates and careful testing are key to ensuring long-term stability and performance improvements.

With these techniques, FreeBSD users can tailor their systems to meet specific requirements while leveraging the robustness and flexibility of the operating system.