In order to create a custom kernel configuration file and build a custom kernel, the full FreeBSD source tree must first be installed.
If /usr/src/
does not exist or it is
empty, source has not been installed. Source can be installed
using Subversion and the instructions
in Section A.3, “Using Subversion”.
Once source is installed, review the contents of
/usr/src/sys
. This directory contains a
number of subdirectories, including those which represent the
following supported architectures: amd64
,
i386
,
powerpc
, and
sparc64
. Everything inside a particular
architecture's directory deals with that architecture only and
the rest of the code is machine independent code common to all
platforms. Each supported architecture has a
conf
subdirectory which contains the
GENERIC
kernel configuration file for that
architecture.
Do not make edits to GENERIC
. Instead,
copy the file to a different name and make edits to the copy.
The convention is to use a name with all capital letters. When
maintaining multiple FreeBSD machines with different hardware, it
is a good idea to name it after the machine's hostname. This
example creates a copy, named MYKERNEL
, of
the GENERIC
configuration file for the
amd64
architecture:
#
cd /usr/src/sys/
amd64
/conf#
cp GENERIC
MYKERNEL
can
now be customized with any ASCII text editor.
The default editor is vi, though an
easier editor for beginners, called
ee, is also installed with
FreeBSD.MYKERNEL
The format of the kernel configuration file is simple.
Each line contains a keyword that represents a device or
subsystem, an argument, and a brief description. Any text
after a #
is considered a comment and
ignored. To remove kernel support for a device or subsystem,
put a #
at the beginning of the line
representing that device or subsystem. Do not add or remove a
#
for any line that you do not
understand.
It is easy to remove support for a device or option and end up with a broken kernel. For example, if the ata(4) driver is removed from the kernel configuration file, a system using ATA disk drivers may not boot. When in doubt, just leave support in the kernel.
In addition to the brief descriptions provided in this file,
additional descriptions are contained in
NOTES
, which can be found in the same
directory as GENERIC
for that architecture.
For architecture independent options, refer to
/usr/src/sys/conf/NOTES
.
When finished customizing the kernel configuration file,
save a backup copy to a location outside of
/usr/src
.
Alternately, keep the kernel configuration file elsewhere and create a symbolic link to the file:
#
cd /usr/src/sys/amd64/conf
#
mkdir /root/kernels
#
cp GENERIC /root/kernels/MYKERNEL
#
ln -s /root/kernels/MYKERNEL
An include
directive is available for use
in configuration files. This allows another configuration file
to be included in the current one, making it easy to maintain
small changes relative to an existing file. If only a small
number of additional options or drivers are required, this
allows a delta to be maintained with respect to
GENERIC
, as seen in this example:
include GENERIC ident MYKERNEL options IPFIREWALL options DUMMYNET options IPFIREWALL_DEFAULT_TO_ACCEPT options IPDIVERT
Using this method, the local configuration file expresses
local differences from a GENERIC
kernel.
As upgrades are performed, new features added to
GENERIC
will also be added to the local
kernel unless they are specifically prevented using
nooptions
or nodevice
. A
comprehensive list of configuration directives and their
descriptions may be found in config(5).
To build a file which contains all available options,
run the following command as root
:
#
cd /usr/src/sys/
arch
/conf && make LINT
All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.