Custom Kernel

The default kernel installed with the system, also known as GENERIC, is generally a good choice for all-purpose use but sometimes you may want to tweak it a little. For example, if you have a motherboard with flaky ACPI support, you may need to change your kernel configurations to disable APIC so that you can still use the ACPI features. Or you may choose to Disable ACPI altogether. Or perhaps you just want to remove unnecessary kernel drivers to conserve memory on some legacy hardware you're trying to keep useful. Here's how you do it:

Updating Kernel sources

You may want to update kernel sources before starting. Use subversion to do this. It's also a good idea to update the base with the command freebsd-update before compiling the custom kernel.

To use svnup, install, then configure /usr/local/etc/svnup.conf. Based on its settings the command with an example arguments is:

# svnup sources

Copying GENERIC so that you can edit it

First, you'll need to know your system architecture - are you using an i386 (386, 486, athlon, pentium, etc) machine, an ia64 (Intel Itanium 64-bit) machine, an AMD64 (Athlon64 or Opteron) machine...? To get this information, run uname -p.

Once you've got that figured out, cd into the appropriate directory like this: cd /usr/src/sys/[i386/amd64/ia64/architecture]/conf, and ls. You'll see something like this:

ph34r# cd /usr/src/sys/amd64/conf
ph34r# ls
GENERIC         GENERIC.hints   Makefile        gethints.awk    noSMPnoAPIC
ph34r#

See that file named GENERIC? That's the kernel configuration. YOU DO NOT WANT TO EDIT THIS ONE DIRECTLY - for one thing, if you screw up your kernel configuration so badly you need to start over, you'll want GENERIC to refer back to. For another, even if you're a genius and never ever ever screw up, the next time you update your system sources, you could lose your shiny new kernel config! So this is what we'll do instead.

ph34r# mkdir /root/kernels
ph34r# cp GENERIC /root/kernels/MYKERNEL
ph34r# ln -s /root/kernels/MYKERNEL MYKERNEL

What we just did is make a directory named kernels in root's home directory, then copy GENERIC to MYKERNEL in that directory, then make a symlink from /usr/src/sys/yourarchitecture/conf/MYKERNEL to that file to make sure that any scripts looking for your kernel in this directory will find it. (This IS important for later.)

Editing your new kernel

This is relatively easy: just edit /root/kernels/MYKERNEL. This article isn't going to go into much detail about all the wonderful things you can do to a custom kernel - see Why Custom Kernels if you're interested in that.

Editing make.conf

/etc/make.conf can be edited to allow for more cpu optimizations. For more details dmesg | grep -i cpu. See /usr/share/examples/etc/make.conf, and find the matching architecture and other information to edit /etc/make.conf.

Compiling your new kernel

Still easy... do it like this:

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

This is going to take a while - on my Athlon64 3000+, it takes approximately three and a half minutes. On Pete's Athlon 2000+, it took around seven minutes. If you're trying to build a stripped down kernel for legacy hardware with very few resources to work with at all, you could easily be in for half an hour or so of hot kernel compiling action, so go get a cup of coffee or something while it compiles.

Installing your new kernel

Does it ever get hard? Nah.

ph34r# make installkernel KERNCONF=MYKERNEL

This won't take any time at all - but if it does take a lot of time and throw pages and pages of text on the screen, you made a typo in the KERNCONF section of the command, and it's trying to build and install some other kernel, and you will have to hit Ctrl-C to break out of the compilation and go right back up to Compiling your new kernel and start from there. Whoops.

Recovering from your new kernel if you messed up

Did you screw something up in your kernel, and the system won't boot? Fear not, recovery is easier than you think. When the system boots, instead of selecting "Normal", "ACPI Disabled", or "Safe" at the menu (FreeBSD 5.x) or hitting enter to boot (FreeBSD 4.x), go into the boot loader - it's the option at the bottom of the menu on FreeBSD 5.x, and you just press any key OTHER than enter to get into it if you're running FreeBSD 4.x. Now that you're looking at this ominous and unhelpful-seeming command line, type boot kernel.old and you should be in business - and once the system is back up, you will probably want to mv /boot/kernel /boot/kernel.oops and cp -Rpv /boot/kernel.old /boot/kernel so that you'll have your old, working kernel in place again in case you have to reboot again before trying to fix what you did wrong the last time and reinstall a new kernel again.