5.5. If Something Goes Wrong

There are four categories of trouble that can occur when building a custom kernel. They are:

Config command fails

If the config command fails when you give it your kernel description, you've probably made a simple error somewhere. Fortunately, config will print the line number that it had trouble with, so you can quickly skip to it with vi. For example, if you see:

config: line 17: syntax error

you can skip to the problem in vi by typing ``17G'' in command mode. Make sure the keyword is typed correctly, by comparing it to the GENERIC kernel or another reference.

Make command fails

If the make command fails, it usually signals an error in your kernel description, but not severe enough for config to catch it. Again, look over your configuration, and if you still cannot resolve the problem, send mail to questions@FreeBSD.ORG with your kernel configuration, and it should be diagnosed very quickly.

Kernel will not boot

If your new kernel does not boot, or fails to recognize your devices, do not panic! Fortunately, BSD has an excellent mechanism for recovering from incompatible kernels. Simply type the name of the kernel you want to boot from (i.e. ``kernel.old'') at the FreeBSD boot prompt instead of pressing return. When reconfiguring a kernel, it is always a good idea to keep a kernel that is known to work on hand.

After booting with a good kernel you can check over your configuration file and try to build it again. One helpful resource is the /var/log/messages file which records, among other things, all of the kernel messages from every successful boot. Also, the dmesg(8) command will print the kernel messages from the current boot.

Note: If you are having trouble building a kernel, make sure to keep a GENERIC, or some other kernel that is known to work on hand as a different name that will not get erased on the next build. You cannot rely on kernel.old because when installing a new kernel, kernel.old is overwritten with the last installed kernel which may be non-functional. Also, as soon as possible, move the working kernel to the proper ``kernel'' location or commands such as ps(1) will not work properly. The proper command to ``unlock'' the kernel file that make installs (in order to move another kernel back permanently) is:

# chflags noschg /kernel

And, if you want to ``lock'' your new kernel into place, or any file for that matter, so that it cannot be moved or tampered with:

# chflags schg /kernel

Kernel works, but ps does not work any more!

If you've installed a different version of the kernel from the one that the system utilities have been built with, for example, an experimental ``2.2.0'' kernel on a 2.1.0-RELEASE system, many system-status commands like ps(1) and vmstat(8) will not work any more. You must recompile the libkvm library as well as these utilities. This is one reason it is not normally a good idea to use a different version of the kernel from the rest of the operating system.