First, let us take a quick tour of the kernel build directory. All directories mentioned will be relative to the main /usr/src/sys directory, which is also accessible through /sys. There are a number of subdirectories here representing different parts of the kernel, but the most important, for our purposes, are arch/conf, where you will edit your custom kernel configuration, and compile, which is the staging area where your kernel will be built. arch represents either i386, alpha, or pc98 (an alternative development branch of PC hardware, popular in Japan). Everything inside a particular architecture's directory deals with that architecture only; the rest of the code is common to all platforms to which FreeBSD could potentially be ported. Notice the logical organization of the directory structure, with each supported device, filesystem, and option in its own subdirectory.
Note: If there is not a /usr/src/sys directory on your system, then the kernel source has not been been installed. The easiest way to do this is by running /stand/sysinstall as root, choosing Configure, then Distributions, then src, then sys.
Next, move to the arch/conf directory and copy the GENERIC configuration file to the name you want to give your kernel. For example:
# cd /usr/src/sys/i386/conf
# cp GENERIC MYKERNEL
Traditionally, this name is in all capital letters and, if you are maintaining multiple FreeBSD machines with different hardware, it is a good idea to name it after your machine's hostname. We will call it MYKERNEL for the purpose of this example.
Note: You must execute these and all of the following commands under the root account or you will get permission denied errors.
Now, edit MYKERNEL with your favorite text editor. If you are just starting out, the only editor available will probably be vi, which is too complex to explain here, but is covered well in many books in the bibliography. However, FreeBSD does offer an easier editor called ``ee'' which, if you are a beginner, should be your editor of choice. Feel free to change the comment lines at the top to reflect your configuration or the changes you have made to differentiate it from GENERIC.
If you have built a kernel under SunOS or some other BSD operating system, much of this file will be very familiar to you. If you are coming from some other operating system such as DOS, on the other hand, the GENERIC configuration file might seem overwhelming to you, so follow the descriptions in the Configuration File section slowly and carefully.
Note: Be sure to always check the file /usr/src/UPDATING, before you perform any update steps, in the case you sync your source-tree with the latest sources of the FreeBSD project. In this file all important issues with updating FreeBSD are written down. /usr/src/UPDATING always fits to your version of the FreeBSD source, and is therefore more accurate for those information than the handbook.
When you are finished, type the following to compile and install your kernel if you are using FreeBSD prior FreeBSD 4.0 and don't want to upgrade to FreeBSD 4.0 or higher with this step, or if you are using a release-version of FreeBSD and your /usr/src/ directory only contains the sys/ sub-directory.
Note: If you are trying to upgrade your kernel from an older version of FreeBSD, you will probably have to get a new version of config(8) from the same place you got the new kernel sources. It is located in /usr/src/usr.sbin, so you will need to download those sources as well. Re-build and install it before running the next commands.
# /usr/sbin/config MYKERNEL
# cd ../../compile/MYKERNEL
# make depend
# make
# make install
If you have just upgraded to a newer version of 4.X or higher (ie from 3.X to 4-STABLE, or even from 4-STABLE to a later version of 4-STABLE), make sure you have built the world, and then run the following commands:
# cd /usr/src
# make buildkernel KERNEL=MYKERNEL
# make installkernel KERNEL=MYKERNEL
If you have not upgraded your source tree in any way (you have not run CVSup, CTM, or used anoncvs), then you should use the config, make depend, make, make install sequence.
WarningIf you have upgraded your sources since your last kernel build, you must use the make buildkernel method to build your kernel. Otherwise, old utilities will be used to build the kernel, which will probably fail. Do not use the config/make sequence to build your kernel if you have updated the sources!
The new kernel will be copied to the root directory as /kernel and the old kernel will be moved to /kernel.old. Now, shutdown the system and reboot to use your kernel. In case something goes wrong, there are some troubleshooting instructions at the end of this document. Be sure to read the section which explains how to recover in case your new kernel does not boot.
Note: If you have added any new devices (such as sound cards) you may have to add some device nodes to your /dev directory before you can use them.
For questions about FreeBSD, e-mail
<questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.