How To Customize and Recompile Your Kernel on FreeBSD 10.1

How To Customize and Recompile Your Kernel on FreeBSD 10.1


The FreeBSD operating system utilizes the GENERIC kernel by default. This is a default configuration used to support a large variety of hardware out of the box. However, there are many different reasons for compiling a custom kernel, which include security, enhanced functionality, or better performance.

FreeBSD utilizes two branches of code for its operating system: stable and current. Stable is the current code release that is production ready. Current is the latest code release from the development team and has some of the latest bleeding edge features but is more prone to bugs and system instability. This guide will utilize the stable branch.

In this tutorial, we will recompile a FreeBSD kernel with a custom configuration.

Note: As of July 1, 2022, DigitalOcean no longer supports the creation of new FreeBSD Droplets through the Control Panel or API. However, you can still spin up FreeBSD Droplets using a custom image. Learn how to import a custom image to DigitalOcean by following our product documentation.


To follow this tutorial, all you will need is:

  • One FreeBSD 10.1 server.

If you’re new to FreeBSD, you can check out the Getting Started with FreeBSD series of tutorials.

Step 1 — Obtaining the Source Code

In this step, we will pull the OS source code.

FreeBSD, like many other flavors of UNIX, provides the source code for its operating system for public download and modification. In order to recompile the kernel, first you will need to pull this source code from FreeBSD’s version control system.

The FreeBSD foundation utilizes Subversion for its code repositories, so let’s first install Subversion’s binary port.

sudo pkg install subversion  

The default shell for FreeBSD is tcsh, which utilizes an internal hash table for commands in $PATH. After subversion installs, you should rehash the directory tables.


Finally, check out a copy of the latest stable branch to the /usr/src directory.

sudo svn co https://svn0.us-east.FreeBSD.org/base/stable/10 /usr/src

You may be prompted to accept a server certificate. Enter p to accept it after checking that the fingerprint matches the one toward the bottom of this page.

Step 2 — Creating Your Custom Configuration

In this step, we will customize our new kernel configuration.

The standard naming convention for kernel configuration files is the name of the kernel in all caps. This tutorial’s configuration will be called EXAMPLE. Kernel configuration files live inside the /usr/src/sys/architecture/conf directory.

Change to the configuration directory.

cd /usr/src/sys/amd64/conf

Create and open the EXAMPLE file for editing using ee or your favorite text editor.

sudo ee EXAMPLE

You can find the example configuration located here. Copy and paste the contents into EXAMPLE, then save and close the file.

Specifically, the GENERIC kernel configuration has support enabled for a lot of different hardware; EXAMPLE has all legacy and unneeded devices removed, leaving only the required device drivers needed to run a server. There is also support enabled for the packet filter firewall (pf), traffic shaping (altq), file system encryption (geom_eli), and IP security (IPsec).

However, you can read more about the configuration options in the FreeBSD documentation and experiment on your own!

Step 3 — Building and Installing Your New Kernel

In this step, we will begin the kernel recompilation.

Change back to the /usr/src directory and issue a make buildkernel utilizing your new configuration file.

cd /usr/src
sudo make buildkernel KERNCONF=EXAMPLE

This can take some time depending on the amount of resources you utilize for your server. The average time on a 1 GB server is about 90 minutes.

Once your kernel recompilation has finished, it is time to begin the install.

sudo make installkernel KERNCONF=EXAMPLE

When that completes, reboot your system.

sudo shutdown -r now

Your server should now begin to shut down its currently running services, sync its disks, and reboot into your new kernel.

Once your server reboots, you can check that your new kernel config is being used with the following command:

sysctl kern.conftxt | grep ident

The output should be:

ident    EXAMPLE


Congratulations! You have successfully reconfigured and recompiled your kernel.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors

Default avatar

staff technical writer

hi! i write do.co/docs now, but i used to be the senior tech editor publishing tutorials here in the community.

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

I’m also thinking in the EXAMPLE kernel config, there seems to be a few things that I find unusual in the context of a VPS, such as the splash device which provides splash screen and screen saver support. Is this some sort of weird dependency issue that requires this module to be compiled in?

The Handbook has a full chapter about custom kernels, the link you posted above refers to the old 3.4 version. Also, to stay on the safe side and not nuke your droplet, the KODIR make variable is useful as per this forum discussion. It basically allows you to boot back into the latest known-to-work kernel in case something goes wrong.

Thanks! My droplet boots even faster now.

Few suggestions:

  1. explain what stable branch means in terms of FreeBSD.
  2. Use svnlite to grab sources, it’s in base system and doesn’t require tons of dependencies
  3. Maybe, use net/svnup which makes it even easier than svnlite and has zero external dependencies.

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel