FreeBSD 7.0 has already been released. If you are a real hacker, the best way to jump in and learn it is hacking together an introductory kernel module. In this article I’ll implement a very basic module that prints a message when it is loaded, and another when it is unloaded. I’ll also cover the mechanics of compiling our module using standard tools and rebuilding the stock FreeBSD kernel. Let’s do it!

Getting Started

There are some prerequisites for this article. I assume you have a little bit of C programming knowledge, though nothing too fancy. If I reference a pointer or a structure, I expect you to understand those concepts without much explanation. I also expect you to be familiar with UNIX-like operating systems and know your way around basic shell usage.

The first thing to do is make sure the development environment you’ll be working in includes everything and is configured properly. I’m going to assume you already have FreeBSD installed and running. If you don’t, and would like some guidance, you can read my article: Secure emails servers with FreeBSD. I’ll be doing a few things differently; so, I would recommend just using it as a resource for the installation, which is identical in both scenarios.

You will also need to make sure the sudo utility is installed and configured for your main user account. This is required to run as “root” the utilities kldload and kldunload. The FreeBSD port for sudo is in /usr/ports/security/sudo.

cd /usr/port/security/sudo
make install && make clean

Now su to root and run the visudo utility. Visudo uses the EDITOR environment variable to determine which text editor to use. If you don’t like the default one, override it with setenv EDITOR vim if you are using the default CSH, or export EDITOR=vim if you are using bash. Then simply re-run visudo.

su 
visudo 

The visudo utility does basic sanity checking on the syntax and makes sure no two people edit the sudoers file at the same time.

# Look for this line, copy it and change the "root" user to your main users name.
root    ALL=(ALL) SETENV: ALL
yourabi ALL=(ALL) SETENV: ALL

Your first kernel

As I mentioned in my recent article Review of FreeBSD 7.0, the ULE scheduler brings a new level of performance and multi-processor scalability to FreeBSD. Though it is now considered stable and ready for prime-time, it will not be enabled by default until the 7.1 release. A good litmus test of your setup will be compiling a custom kernel with the ULE scheduler enabled.

If you are on an x86 based machine, the kernel is located in the /usr/src/sys/i386 directory. For amd64 machines, simply replace i386 with amd64, which becomes /usr/src/sys/amd64. The kernel configuration file is located in a directory called conf. Enter that directory and create your own custom kernel configuration file by copying the “generic” default configuration to one of our own naming.

cd /usr/src/sys/amd64/conf 
cp GENERIC CUSTOM

Now it’s time to enable the new ULE scheduler. The new ULE scheduler brings improved performance and scalability compared to the legacy scheduler and also serves as a good demonstration of building and installing a custom kernel.

Open the “CUSTOM” file with your text editor of choice and find the line enabling the legacy 44BSD scheduler and replace it with ULE. In the stock kernel configuration file this should be around line 30 (at the time of this writing).

options     SCHED_4BSD  # 4BSD scheduler 
 # BECOMES #
options     SCHED_ULE   # ULE scheduler

Now build your new kernel and reboot so it takes effect. FreeBSD has an elegant, simple build system using the standard “make” utility. Simply change directories to the source tree and invoke the make file with the “buildkernel” and “installkernel” targets. If you call them without any parameters, the GENERIC (default) kernel will be built and installed. Since you want your custom kernel, pass in the KERNCONF flag with the name of the target kernel. In this case, it will be the name that you just copied the generic kernel to: CUSTOM.

cd /usr/src
make buildkernel KERNCONF="CUSTOM"
make installkernel KERNCONF="CUSTOM"
reboot

Congratulations! As the system boots up, it will run the new custom kernel with the ULE scheduler enabled. You have now verified that you are able to compile and install a kernel, so it’s time to take on your next task: writing a simple kernel module.

When running FreeBSD in VMWare make sure to lower the kernels timer frequency

Note: If you are running FreeBSD in VMWare there is one very important performance tweak to make to your system to follow this article. The kernel’s timer frequency needs to be lowered from ‘1000’ to ‘100’ ticks per second. Edit /boot/loader.conf with your favorite editor and add the following line.

echo kern.hz=100 >> /boot/loader.conf

Kernel Hello World

As you may have noticed, FreeBSD makes efficient use of the make utility for building and installing kernels (and the rest of the operating system). What you may not know yet, but will come as no surprise, is that the FreeBSD developers have also developed make files to ease part of the difficulty of kernel module development.