How to Compile a Minimal Custom Kernel on FreeBSD Operating System

Introduction

FreeBSD is renowned for its flexibility, performance, and security as a server operating system. One of the most powerful customization options it offers is the ability to compile a custom kernel tailored to your specific hardware and requirements. While the GENERIC kernel included with FreeBSD is designed to work on a wide range of hardware configurations, compiling a custom kernel can provide several advantages:

• Reduced memory usage
• Faster boot times
• Improved performance
• Enhanced security through reduced attack surface
• Support for specific hardware or features not enabled in the GENERIC kernel

This guide will walk you through the process of compiling a minimal custom kernel on FreeBSD, from preparing your system to booting into your new kernel. We’ll focus on creating a streamlined kernel that contains only the components necessary for your specific hardware and use case.

Prerequisites

Before beginning this process, ensure you have:

• A working FreeBSD installation (version P or later)
• Root access to the system
• At least 1GB of free disk space
• Basic knowledge of FreeBSD’s file system hierarchy
• A backup of your important data
• A recovery plan in case something goes wrong

Step 1: Update Your System

Always start with an updated system to ensure compatibility and security:

# freebsd-update fetch
# freebsd-update install
# pkg update && pkg upgrade

Step 2: Install the Source Code

If you haven’t already, you’ll need to install the FreeBSD source code:

# pkg install git
# git clone https://git.freebsd.org/src.git /usr/src

Alternatively, you can use Subversion:

# pkg install subversion
# svnlite checkout https://svn.freebsd.org/base/releng/13.2 /usr/src

Replace “13.2” with your FreeBSD version if different.

Step 3: Understand the Current Kernel Configuration

Before creating a custom kernel, examine the GENERIC kernel configuration to understand what you’re starting with:

# cd /usr/src/sys/$(uname -m)/conf
# less GENERIC

This file contains all the components, drivers, and features enabled in the default kernel. Study it carefully to identify what you can remove based on your hardware and requirements.

Step 4: Create a Custom Kernel Configuration

Instead of modifying the GENERIC configuration directly, create a new configuration file for your custom kernel:

# cd /usr/src/sys/$(uname -m)/conf
# cp GENERIC MYKERNEL
# ee MYKERNEL

Replace “MYKERNEL” with a name of your choice (commonly written in uppercase).

Step 5: Customize Your Kernel Configuration

Now comes the most important part: editing your kernel configuration to remove unnecessary components. Here’s where you can significantly reduce the kernel size by removing drivers and features you don’t need.

At the top of your configuration file, you’ll see a line like:

include GENERIC

You can either keep this line and override specific options, or remove it and build your configuration from scratch. For beginners, the first approach is safer.

Here are some common areas to customize:

1. CPU Options

If you know your specific CPU type, you can optimize for it:

# CPU options
options         SCHED_ULE       # ULE scheduler
options         PREEMPTION      # Enable kernel thread preemption
options         INET            # InterNETworking
options         INET6           # IPv6 communications protocols
options         TCP_OFFLOAD     # TCP offload
options         SCTP            # Stream Control Transmission Protocol
options         FFS             # Berkeley Fast Filesystem
options         SOFTUPDATES     # Enable FFS soft updates support
options         UFS_ACL         # Support for access control lists
options         UFS_DIRHASH     # Improve performance on big directories
options         UFS_GJOURNAL    # Enable gjournal-based UFS journaling

2. Remove Unnecessary Device Drivers

Comment out (by adding # at the beginning of the line) any device drivers that your system doesn’t need. For example, if you don’t have SCSI devices:

# SCSI peripherals
#device        scbus           # SCSI bus (required for SCSI)
#device        da              # Direct Access (disks)
#device        cd              # CD
#device        pass            # Passthrough device (direct SCSI access)
#device        ses             # Enclosure Services (SES and SAF-TE)

Similarly, you can remove drivers for hardware you don’t have, such as:

• Wireless network adapters
• Graphics cards you don’t use
• Audio devices if not needed
• USB devices if not used
• FireWire/IEEE1394 if not used
• Parallel/Serial ports if not used

3. File Systems

Remove support for file systems you don’t use:

# uncomment if you need these file systems
#options        MSDOSFS         # MSDOS Filesystem
#options        CD9660          # ISO 9660 Filesystem
#options        PROCFS          # Process filesystem (requires PSEUDOFS)
#options        PSEUDOFS        # Pseudo-filesystem framework
#options        GEOM_PART_GPT   # GUID Partition Tables.
#options        GEOM_RAID       # Soft RAID functionality.

4. Networking Options

If you don’t need certain networking features, you can remove them:

# networking options to consider removing
#options        INET6           # IPv6 (remove if you don't use IPv6)
#options        IPSEC           # IP security
#options        IPSEC_SUPPORT   # Allow kldload of ipsec and tcpmd5
#options        TCP_SIGNATURE   # TCP MD5 Signatures, for BGP routing sessions

5. Debugging and Diagnostic Features

For a production system, you might want to remove some debugging features:

# debugging features you can remove
#options        KDB             # Enable kernel debugger support
#options        KDB_TRACE       # Print a stack trace for a panic
#options        DDB             # Support DDB
#options        GDB             # Support remote GDB

Remember to be cautious when removing components. If you remove essential drivers or features, your system might not boot or function properly.

Step 6: Build and Install Your Custom Kernel

Once you’ve customized your kernel configuration, it’s time to build and install it:

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

These commands will compile your custom kernel and install it. The process might take anywhere from a few minutes to several hours, depending on your system’s performance.

Step 7: Configure Boot Loader (Optional)

By default, FreeBSD will boot using your newly installed kernel. However, it’s wise to configure the boot loader to give you options in case something goes wrong.

Edit /boot/loader.conf:

# ee /boot/loader.conf

Add the following lines:

kernel="MYKERNEL"
kernels="MYKERNEL kernel"

This configuration tells FreeBSD to try booting with your custom kernel first, but if that fails, it will fall back to the GENERIC kernel.

Step 8: Reboot and Test

Now it’s time to test your new kernel:

# reboot

After rebooting, log in and verify that you’re running your custom kernel:

# uname -v

The output should include the name of your custom kernel.

Step 9: Verify Functionality

Test all the critical functions of your system to ensure everything works as expected:

• Network connectivity
• Disk operations
• Any specific hardware or features you need

If you encounter any issues, you can boot back into the GENERIC kernel by selecting it from the boot menu (press any key during boot to access it).

Step 10: Further Optimization (Optional)

After successfully booting into your custom kernel, you might want to further optimize it based on your experience. This is an iterative process:

1. Identify additional components that can be removed
2. Update your kernel configuration
3. Rebuild and reinstall the kernel
4. Test thoroughly

Troubleshooting

Kernel Doesn’t Boot

If your system fails to boot with the custom kernel:

1. At the boot loader menu, select the GENERIC kernel
2. Once booted, review your kernel configuration for errors
3. Common issues include removing essential drivers for your boot disk or network interfaces

Kernel Panics

If you experience kernel panics:

1. Boot with the GENERIC kernel
2. Check /var/log/messages for clues about what caused the panic
3. Adjust your kernel configuration accordingly

Missing Functionality

If certain features don’t work:

1. Identify which kernel components are needed for those features
2. Add them back to your configuration
3. Rebuild and reinstall the kernel

Conclusion

Compiling a minimal custom kernel in FreeBSD is a powerful way to optimize your system for specific hardware and use cases. While the process requires careful consideration and testing, the benefits in terms of performance, boot time, and resource usage can be substantial.

The key to success is understanding your hardware requirements and being methodical in your approach. Always maintain the ability to boot back into a known-working kernel, and make incremental changes rather than removing too many components at once.

With a properly configured custom kernel, your FreeBSD system will be leaner, faster, and precisely tailored to your needs—embodying the flexibility and power that make FreeBSD an excellent choice for servers and specialized applications.

Additional Resources

• FreeBSD Handbook: Configuring the FreeBSD Kernel
• FreeBSD Man Pages: config(8)
• FreeBSD Forums - An excellent place to get help with kernel configuration issues