<?xml version="1.0" encoding="iso-8859-1"?>
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="kernelconfig">
<chapterinfo>
<authorgroup>
<author>
<firstname>Jim</firstname>
<surname>Mock</surname>
<contrib>Updated and restructured by </contrib>
<!-- Mar 2000 -->
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Jake</firstname>
<surname>Hamby</surname>
<contrib>Originally contributed by </contrib>
<!-- 6 Oct 1995 -->
</author>
</authorgroup>
</chapterinfo>
<title>Configuring the FreeBSD Kernel</title>
<sect1 id="kernelconfig-synopsis">
<title>Synopsis</title>
<indexterm>
<primary>kernel</primary>
<secondary>building a custom kernel</secondary>
</indexterm>
<para>The kernel is the core of the &os; operating system. It
is responsible for managing memory, enforcing security controls,
networking, disk access, and much more. While much of &os; is
dynamically configurable, it is still occasionally necessary to
configure and compile a custom kernel.</para>
<para>After reading this chapter, you will know:</para>
<itemizedlist>
<listitem>
<para>When to build a custom kernel.</para>
</listitem>
<listitem>
<para>How to customize a kernel configuration file.</para>
</listitem>
<listitem>
<para>How to use the kernel configuration file to create and
build a new kernel.</para>
</listitem>
<listitem>
<para>How to install the new kernel.</para>
</listitem>
<listitem>
<para>How to troubleshoot if things go wrong.</para>
</listitem>
</itemizedlist>
<para>All of the commands listed in the examples in this chapter
should be executed as <username>root</username>.</para>
</sect1>
<sect1 id="kernelconfig-custom-kernel">
<title>Why Build a Custom Kernel?</title>
<para>Traditionally, &os; used a <quote>monolithic</quote> kernel.
The kernel was one large program, supported a fixed list of
devices, and in order to change the kernel's behavior, one had
to compile a new kernel, and then reboot into the new
kernel.</para>
<para>Today, most of the functionality in the &os; kernel is
contained in modules which can be dynamically loaded and
unloaded from the kernel as necessary. This allows the
running kernel to adapt immediately to new hardware or for new
functionality to be brought into the kernel. This is known as
a modular kernel.</para>
<para>Occasionally, it is still necessary to perform static kernel
configuration. This may be because the functionality is so tied
to the kernel that it can not be made dynamically loadable.
Some security environments prevent the loading and unloading of
kernel modules, and require that only needed functionality is
statically compiled into the kernel.</para>
<para>Building a custom kernel is often a rite of passage for
advanced BSD users. This process, while time consuming, can
provide benefits to the &os; system. Unlike the
<filename>GENERIC</filename> kernel, which must support a wide
range of hardware, a custom kernel can be stripped down to only
provide support for that computer's hardware. This has a number
of benefits, such as:</para>
<itemizedlist>
<listitem>
<para>Faster boot time. Since the kernel will only probe the
hardware on the system, the time it takes the system to boot
can decrease.</para>
</listitem>
<listitem>
<para>Lower memory usage. A custom kernel often uses less
memory than the <filename>GENERIC</filename> kernel by
omitting unused features and device drivers. This is
important because the kernel code remains resident in
physical memory at all times, preventing that memory from
being used by applications. For this reason, a custom
kernel is useful on a system with a small amount of
RAM.</para>
</listitem>
<listitem>
<para>Additional hardware support. A custom kernel can add in
support for devices which are not present in the
<filename>GENERIC</filename> kernel.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="kernelconfig-devices">
<sect1info>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
<contrib>Written by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Finding the System Hardware</title>
<para>Before venturing into kernel configuration, it would be
wise to get an inventory of the machine's hardware. In cases
where &os; is not the primary operating system, the inventory
list can be created by viewing the current operating system
configuration. For example, µsoft;'s
<application>Device Manager</application> contains information
about installed devices.</para>
<note>
<para>Some versions of µsoft.windows; have a
<application>System</application> icon which will display a
screen where <application>Device Manager</application> may
be accessed.</para>
</note>
<para>If another operating system does not exist on the machine,
the administrator must find this information out manually. One
method is using &man.dmesg.8; and &man.man.1;. Most device
drivers on &os; have a manual page, listing supported hardware.
During the boot probe, found hardware will be listed. For
example, the following lines indicate that the &man.psm.4;
driver found a mouse:</para>
<programlisting>psm0: <PS/2 Mouse> irq 12 on atkbdc0
psm0: [GIANT-LOCKED]
psm0: [ITHREAD]
psm0: model Generic PS/2 mouse, device ID 0</programlisting>
<para>This driver will need to be included in the custom kernel
configuration file or loaded using &man.loader.conf.5;.</para>
<para>On occasion, the data from <command>dmesg</command> will
only show system messages instead of the boot probe output. In
these situations, the output may be obtained by reading
<filename>/var/run/dmesg.boot</filename>.</para>
<para>Another method for finding hardware is to use
&man.pciconf.8; which provides more verbose output. For
example:</para>
<programlisting>ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00
vendor = 'Atheros Communications Inc.'
device = 'AR5212 Atheros AR5212 802.11abg wireless'
class = network
subclass = ethernet</programlisting>
<para>This output, obtained by using
<command>pciconf <option>-lv</option></command>, shows that the
<devicename>ath</devicename> driver located a wireless Ethernet
device. Type <command>man
<replaceable>ath</replaceable></command> to read
&man.ath.4;.</para>
<para>The <option>-k</option> flag, when passed to &man.man.1;
can be used to provide useful information. For example, to
display a list of manual pages which contain the specified
word:</para>
<screen>&prompt.root; man -k <replaceable>Atheros</replaceable></screen>
<programlisting>ath(4) - Atheros IEEE 802.11 wireless network driver
ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
<para>Armed with a hardware inventory list, the process of
building a custom kernel should appear less daunting.</para>
</sect1>
<sect1 id="kernelconfig-modules">
<title>Kernel Drivers, Subsystems, and Modules</title>
<indexterm>
<primary>kernel</primary>
<secondary>drivers / modules / subsystems</secondary>
</indexterm>
<para>Before building a custom kernel, consider the reason for
doing so. If there is a need for specific hardware support,
it may already exist as a module.</para>
<para>Kernel modules exist in <filename
class="directory">/boot/kernel</filename> and may be
dynamically loaded into the running kernel using
&man.kldload.8;. Most, if not all kernel drivers have a
loadable module and manual page. For example, the &man.ath.4;
wireless Ethernet driver has the following information in its
manual page:</para>
<programlisting>Alternatively, to load the driver as a module at boot time, place the
following line in &man.loader.conf.5;:
if_ath_load="YES"</programlisting>
<para>Adding <literal>if_ath_load="YES"</literal> to
<filename>/boot/loader.conf</filename> will enable loading this
module dynamically at boot time.</para>
<para>In some cases, there is no associated module. This is
mostly true for certain subsystems. One way to tell if a driver
is available is to check for the module itself.</para>
<warning>
<para>It is easy to remove support for a device or option and
end up with a broken kernel. For example, if the &man.ata.4;
driver is removed from the kernel configuration file, a system
using <acronym>ATA</acronym> disk drivers may not boot. When
in doubt, just leave support in the kernel.</para>
</warning>
</sect1>
<sect1 id="kernelconfig-building">
<title>Building and Installing a Custom Kernel</title>
<indexterm>
<primary>kernel</primary>
<secondary>building / installing</secondary>
</indexterm>
<note>
<para>It is required to have the full &os; source tree installed
to build the kernel.</para>
</note>
<para>The kernel build is located at <filename
class="directory">/usr/src/sys</filename>. It contains a
number of subdirectories representing different parts of the
kernel. These include <filename
class="directory"><replaceable>arch</replaceable>/conf</filename>,
which contains the kernel configuration file, and
<filename class="directory">compile</filename>, which is the
staging area where the kernel will be built.
<replaceable>arch</replaceable> contains subdirectories for each
supported architecture: <filename
class="directory">i386</filename>, <filename
class="directory">amd64</filename>, <filename
class="directory">ia64</filename>, <filename
class="directory">powerpc</filename>, <filename
class="directory">sparc64</filename>, and <filename
class="directory">pc98</filename>. 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. Notice the logical organization of the
directory structure, with each supported device, file system,
and option in its own subdirectory.</para>
<para>The examples in this chapter assume the i386 architecture.
If the system has a different architecture, change the path
names accordingly.</para>
<note>
<para>If <filename class="directory">/usr/src/</filename> does
not exist or it is empty, source has not been installed. The
easiest way to install source is to use
<application>svn</application> as described in <xref
linkend="svn"/>. One should also create a symlink to
<filename class="directory">/usr/src/sys/</filename>:</para>
<screen>&prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput></screen>
</note>
<para>Next, <application>cd</application> to <filename
class="directory"><replaceable>arch</replaceable>/conf</filename>
and copy the <filename>GENERIC</filename> configuration file to
the name of the custom kernel. For example:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
&prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen>
<para>Traditionally, this name is in all capital letters. When
maintaining multiple &os; machines with different hardware, it
is a good idea to name it after the machine's hostname. This
example uses
<filename><replaceable>MYKERNEL</replaceable></filename>.</para>
<tip>
<para>When finished customizing the kernel configuration file,
save a backup copy to a location outside of <filename
class="directory">/usr/src</filename>. Do not edit
<filename>GENERIC</filename> directly.</para>
<para>Alternately, keep the kernel configuration file elsewhere
and create a symbolic link to the file in <filename
class="directory"><replaceable>i386</replaceable></filename>.</para>
<para>For example:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
&prompt.root; <userinput>mkdir /root/kernels</userinput>
&prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput>
&prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
</tip>
<para>Edit
<filename><replaceable>MYKERNEL</replaceable></filename>
with a text editor. The default editor is
<application>vi</application>, whose usage is covered well in
many books in the <link
linkend="bibliography">bibliography</link>. An easier editor
for beginners, called <application>ee</application>, is also
available. Feel free to change the comment lines at the top to
reflect the configuration or the changes made to differentiate
it from <filename>GENERIC</filename>.</para>
<para>If the <filename>GENERIC</filename> configuration file seems
overwhelming, follow the descriptions in the <link
linkend="kernelconfig-config">Configuration File</link>
section slowly and carefully.</para>
<note>
<para>After <link linkend="svn">syncing the source tree</link>
with the latest sources, <emphasis>always</emphasis> read
<filename class="directory">/usr/src/UPDATING</filename>
before performing any update steps. This file describes any
important issues or areas requiring special attention within
the updated source code.
<filename>/usr/src/UPDATING</filename> always matches
the version of the &os; source and contains more up-to-date
information than this Handbook.</para>
</note>
<para>After saving the edits, compile the source code for the
kernel.</para>
<procedure>
<title>Building a Kernel</title>
<note>
<para>It is required to have the full &os; source tree
installed to build the kernel.</para>
</note>
<step>
<para><command>cd</command> to <filename
class="directory">/usr/src</filename>:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
</step>
<step>
<para>Compile the new kernel by specifying the name of the
custom kernel configuration file:</para>
<screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
</step>
<step>
<para>Install the new kernel:</para>
<screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
</step>
</procedure>
<tip>
<para>By default, when a custom kernel is compiled,
<emphasis>all</emphasis> kernel modules are rebuilt as well.
To update a kernel faster or to build only custom modules,
edit <filename>/etc/make.conf</filename> before starting to
build the kernel:</para>
<programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting>
<para>This variable specifies the list of modules to build
instead the default of building of all of them.</para>
<programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting>
<para>This variable sets up a list of top level modules to
exclude from the build process. For other available
variables, refer to &man.make.conf.5;.</para>
</tip>
<indexterm>
<primary><filename
class="directory">/boot/kernel.old</filename></primary>
</indexterm>
<para>The new kernel will be copied to <filename
class="directory">/boot/kernel</filename> as
<filename>/boot/kernel/kernel</filename> and the old kernel
will be moved to <filename>/boot/kernel.old/kernel</filename>.
Now, shutdown the system and reboot into the new kernel.
If something goes wrong, refer to the <link
linkend="kernelconfig-trouble">troubleshooting</link>
instructions and the section which explains how to
recover when the new kernel <link
linkend="kernelconfig-noboot">does not boot</link>.</para>
<note>
<para>Other files relating to the boot process, such as the boot
&man.loader.8; and configuration, are stored in <filename
class="directory">/boot</filename>. Third party or
custom modules can be placed in <filename
class="directory">/boot/kernel</filename>, although users
should be aware that keeping modules in sync with the compiled
kernel is very important. Modules not intended to run with
the compiled kernel may result in instability.</para>
</note>
</sect1>
<sect1 id="kernelconfig-config">
<sect1info>
<authorgroup>
<author>
<firstname>Joel</firstname>
<surname>Dahl</surname>
<contrib>Updated by </contrib>
</author>
</authorgroup>
</sect1info>
<title>The Configuration File</title>
<indexterm>
<primary>kernel</primary>
<secondary>NOTES</secondary>
</indexterm>
<indexterm><primary>NOTES</primary></indexterm>
<indexterm>
<primary>kernel</primary>
<secondary>configuration file</secondary>
</indexterm>
<para>The general format of a configuration file is quite simple.
Each line contains a keyword and one or more arguments. For
simplicity, most lines only contain one argument. Anything
following a <literal>#</literal> is considered a comment and
ignored. The following sections describe each keyword, in
the order they are listed in <filename>GENERIC</filename>.
For an exhaustive list of architecture dependent options and
devices, refer to <filename>NOTES</filename> in the same
directory as <filename>GENERIC</filename> for that architecture.
For architecture independent options, refer to
<filename>/usr/src/sys/conf/NOTES</filename>.</para>
<para>An <literal>include</literal> 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. For example, if
only a small number of additional options or drivers are
required, this allows a delta to be maintained with respect
to GENERIC:</para>
<programlisting>include GENERIC
ident MYKERNEL
options IPFIREWALL
options DUMMYNET
options IPFIREWALL_DEFAULT_TO_ACCEPT
options IPDIVERT</programlisting>
<para>Using this method, the local configuration file expresses
local differences from a <filename>GENERIC</filename>
kernel. As upgrades are performed, new features added to
<filename>GENERIC</filename> will be also be added to the local
kernel unless they are specifically prevented using
<literal>nooptions</literal> or <literal>nodevice</literal>.
A comprehensive list of configuration directives and their
descriptions may be found in &man.config.5;.</para>
<para>The remainder of this chapter addresses the contents of a
typical configuration file and the role various options and
devices play.</para>
<note>
<para>To build a file which contains all available options,
run the following command as <username>root</username>:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf && make LINT</userinput></screen>
</note>
<indexterm>
<primary>kernel</primary>
<secondary>configuration file</secondary>
</indexterm>
<para>The following is an example of the
<filename>GENERIC</filename> kernel configuration file with
various additional comments where needed for clarity. This
example should match the copy in
<filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/GENERIC</filename>
fairly closely.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>machine</secondary>
</indexterm>
<programlisting>machine i386</programlisting>
<para>This is the machine architecture. It must be either
<literal>amd64</literal>, <literal>i386</literal>,
<literal>ia64</literal>, <literal>pc98</literal>,
<literal>powerpc</literal>, or
<literal>sparc64</literal>.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>cpu</secondary>
</indexterm>
<programlisting>cpu I486_CPU
cpu I586_CPU
cpu I686_CPU</programlisting>
<para>This option specifies the type of CPU. It is fine to have
multiple instances of the CPU entries, but for a custom kernel
it is best to specify the CPU. To determine the CPU type,
review the boot messages in
<filename>/var/run/dmesg.boot</filename>.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>ident</secondary>
</indexterm>
<programlisting>ident GENERIC</programlisting>
<para>This is the identification of the kernel. Change
this to the new kernel name, such as
<literal><replaceable>MYKERNEL</replaceable></literal>.
The value in the <literal>ident</literal> string will
print when the kernel boots.</para>
<programlisting>#To statically compile in device wiring instead of /boot/device.hints
#hints "GENERIC.hints" # Default places to look for devices.</programlisting>
<para>&man.device.hints.5; is used to configure options for device
drivers. The default location is
<filename>/boot/device.hints</filename>. The
<literal>hints</literal> option compiles these hints statically
into the kernel so that there is no need to create
<filename>/boot/device.hints</filename>.</para>
<!-- XXX: Add a comment here that explains when compiling hints into
the kernel is a good idea and why. -->
<programlisting>makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols</programlisting>
<para>This option enables debugging information when passed to
&man.gcc.1;.</para>
<programlisting>options SCHED_ULE # ULE scheduler</programlisting>
<para>The default system scheduler for &os;. Keep this.</para>
<programlisting>options PREEMPTION # Enable kernel thread preemption</programlisting>
<para>Allows kernel threads to be preempted by higher priority
threads. This helps with interactivity and allows interrupt
threads to run sooner rather than waiting.</para>
<programlisting>options INET # InterNETworking</programlisting>
<para>Networking support. This is mandatory as most programs
require at least loopback networking.</para>
<programlisting>options INET6 # IPv6 communications protocols</programlisting>
<para>This enables the IPv6 communication protocols.</para>
<programlisting>options FFS # Berkeley Fast Filesystem</programlisting>
<para>This is the basic hard drive file system. Leave it in if
the system boots from the hard disk.</para>
<programlisting>options SOFTUPDATES # Enable FFS Soft Updates support</programlisting>
<para>This option enables Soft Updates in the kernel which helps
to speed up write access on the disks. Even when this
functionality is provided by the kernel, it must be turned on
for specific disks. Review the output of &man.mount.8; to
determine if Soft Updates is enabled. If the
<literal>soft-updates</literal> option is not in the output, it
can be activated using &man.tunefs.8; for existing file systems
or &man.newfs.8; for new file systems.</para>
<programlisting>options UFS_ACL # Support for access control lists</programlisting>
<para>This option enables kernel support for access control lists
(<acronym>ACL</acronym>s). This relies on the use of extended
attributes and <acronym>UFS2</acronym>, and the feature is
described in detail in <xref linkend="fs-acl"/>.
<acronym>ACL</acronym>s are enabled by default and should not be
disabled in the kernel if they have been used previously on a
file system, as this will remove the ACLs, changing the way
files are protected in unpredictable ways.</para>
<programlisting>options UFS_DIRHASH # Improve performance on big directories</programlisting>
<para>This option includes functionality to speed up disk
operations on large directories, at the expense of using
additional memory. Keep this for a large server or interactive
workstation, and remove it from smaller systems where memory is
at a premium and disk access speed is less important, such as a
firewall.</para>
<programlisting>options MD_ROOT # MD is a potential root device</programlisting>
<para>This option enables support for a memory backed virtual disk
used as a root device.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>NFS</secondary>
</indexterm>
<indexterm>
<primary>kernel options</primary>
<secondary>NFS_ROOT</secondary>
</indexterm>
<programlisting>options NFSCLIENT # Network Filesystem Client
options NFSSERVER # Network Filesystem Server
options NFS_ROOT # NFS usable as /, requires NFSCLIENT</programlisting>
<para>The network file system (<acronym>NFS</acronym>). These
lines can be commented unless the system needs to mount
partitions from a <acronym>NFS</acronym> file server over
TCP/IP.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>MSDOSFS</secondary>
</indexterm>
<programlisting>options MSDOSFS # MSDOS Filesystem</programlisting>
<para>The &ms-dos; file system. Unless the system needs to mount
a DOS formatted hard drive partition at boot time, comment this
out. It will be automatically loaded the first time a DOS
partition is mounted. The <filename
role="package">emulators/mtools</filename> package allows
access to DOS floppies without having to mount and unmount
them and does not require <literal>MSDOSFS</literal>.</para>
<programlisting>options CD9660 # ISO 9660 Filesystem</programlisting>
<para>The ISO 9660 file system for CDROMs. Comment it out if the
system does not have a CDROM drive or only mounts data CDs
occasionally since it will be dynamically loaded the first
time a data CD is mounted. Audio CDs do not need this file
system.</para>
<programlisting>options PROCFS # Process filesystem (requires PSEUDOFS)</programlisting>
<para>The process file system. This is a <quote>pretend</quote>
file system mounted on <filename
class="directory">/proc</filename> which allows some programs
to provide more information on what processes are running. Use
of <literal>PROCFS</literal> is not required under most
circumstances, as most debugging and monitoring tools have been
adapted to run without <literal>PROCFS</literal>. The default
installation will not mount this file system by default.</para>
<programlisting>options PSEUDOFS # Pseudo-filesystem framework</programlisting>
<para>Kernels making use of <literal>PROCFS</literal> must
also include support for <literal>PSEUDOFS</literal>.</para>
<programlisting>options GEOM_PART_GPT # GUID Partition Tables.</programlisting>
<para>Adds support for <ulink
url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
Partition Tables</ulink> (<acronym>GPT</acronym>). GPT
provides the ability to have a large number of partitions per
disk, 128 in the standard configuration.</para>
<programlisting>options COMPAT_43 # Compatible with BSD 4.3 [KEEP THIS!]</programlisting>
<para>Compatibility with 4.3BSD. Leave this in as some programs
will act strangely if this is commented out.</para>
<programlisting>options COMPAT_FREEBSD4 # Compatible with &os;4</programlisting>
<para>This option is required to support applications compiled on
older versions of &os; that use older system call interfaces.
It is recommended that this option be used on all &i386; systems
that may run older applications. Platforms that gained support
after &os; 4.X, such as ia64 and &sparc64;, do not require
this option.</para>
<programlisting>options COMPAT_FREEBSD5 # Compatible with &os;5</programlisting>
<para>This option is required to support applications compiled on
&os; 5.X versions that use &os; 5.X system call
interfaces.</para>
<programlisting>options COMPAT_FREEBSD6 # Compatible with &os;6</programlisting>
<para>This option is required to support applications compiled on
&os; 6.X versions that use &os; 6.X system call
interfaces.</para>
<programlisting>options COMPAT_FREEBSD7 # Compatible with &os;7</programlisting>
<para>This option is required on &os; 8 and above to support
applications compiled on &os; 7.X versions that use
&os; 7.X system call interfaces.</para>
<programlisting>options SCSI_DELAY=5000 # Delay (in ms) before probing SCSI</programlisting>
<para>This causes the kernel to pause for 5 seconds before probing
each SCSI device in the system. If the system only has IDE hard
drives, ignore this or lower the number to speed up booting.
However, if &os; has trouble recognizing the SCSI devices, the
number will have to be raised again.</para>
<programlisting>options KTRACE # ktrace(1) support</programlisting>
<para>This enables kernel process tracing, which is useful in
debugging.</para>
<programlisting>options SYSVSHM # SYSV-style shared memory</programlisting>
<para>This option provides for System V shared memory. The
most common use of this is the XSHM extension in X, which many
graphics-intensive programs will automatically take advantage of
for extra speed. If <application>Xorg</application> is
installed, include this.</para>
<programlisting>options SYSVMSG # SYSV-style message queues</programlisting>
<para>Support for System V messages. This option only adds
a few hundred bytes to the kernel.</para>
<programlisting>options SYSVSEM # SYSV-style semaphores</programlisting>
<para>Support for System V semaphores. Less commonly used,
but only adds a few hundred bytes to the kernel.</para>
<note>
<para>Using <option>-p</option> with &man.ipcs.1; will list any
processes using each of these System V facilities.</para>
</note>
<programlisting>options _KPOSIX_PRIORITY_SCHEDULING # POSIX P1003_1B real-time extensions</programlisting>
<para>Real-time extensions added in the 1993 &posix;. Certain
applications in the Ports Collection use these.</para>
<programlisting>options KBD_INSTALL_CDEV # install a CDEV entry in /dev</programlisting>
<para>This option is required to allow the creation of keyboard
device nodes in <filename
class="directory">/dev</filename>.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>SMP</secondary>
</indexterm>
<programlisting>device apic # I/O APIC</programlisting>
<para>This device enables the use of the I/O APIC for interrupt
delivery. It can be used in both uni-processor and SMP kernels,
but is required for SMP kernels. Add <literal>options
SMP</literal> to include support for multiple
processors.</para>
<note>
<para>This device exists only on the i386 architecture and this
configuration line should not be used on other
architectures.</para>
</note>
<programlisting>device eisa</programlisting>
<para>Include this for systems with an EISA motherboard. This
enables auto-detection and configuration support for all devices
on the EISA bus.</para>
<programlisting>device pci</programlisting>
<para>Include this for systems with a PCI motherboard. This
enables auto-detection of PCI cards and gatewaying from the PCI
to ISA bus.</para>
<programlisting># Floppy drives
device fdc</programlisting>
<para>This is the floppy drive controller.</para>
<programlisting># ATA and ATAPI devices
device ata</programlisting>
<para>This driver supports all ATA and ATAPI devices. Only
one <literal>device ata</literal> line is needed for the kernel
to detect all PCI ATA/ATAPI devices on modern machines.</para>
<programlisting>device atadisk # ATA disk drives</programlisting>
<para>This is needed along with <literal>device ata</literal> for
ATA disk drives.</para>
<programlisting>device ataraid # ATA RAID drives</programlisting>
<para>This is needed along with <literal>device ata</literal>
for ATA RAID drives.</para>
<programlisting><anchor id="kernelconfig-atapi"/>
device atapicd # ATAPI CDROM drives</programlisting>
<para>This is needed along with <literal>device ata</literal>
for ATAPI CDROM drives.</para>
<programlisting>device atapifd # ATAPI floppy drives</programlisting>
<para>This is needed along with <literal>device ata</literal> for
ATAPI floppy drives.</para>
<programlisting>device atapist # ATAPI tape drives</programlisting>
<para>This is needed along with <literal>device ata</literal> for
ATAPI tape drives.</para>
<programlisting>options ATA_STATIC_ID # Static device numbering</programlisting>
<para>This makes the controller number static. Without this, the
device numbers are dynamically allocated.</para>
<programlisting># SCSI Controllers
device ahb # EISA AHA1742 family
device ahc # AHA2940 and onboard AIC7xxx devices
options AHC_REG_PRETTY_PRINT # Print register bitfields in debug
# output. Adds ~128k to driver.
device ahd # AHA39320/29320 and onboard AIC79xx devices
options AHD_REG_PRETTY_PRINT # Print register bitfields in debug
# output. Adds ~215k to driver.
device amd # AMD 53C974 (Teckram DC-390(T))
device isp # Qlogic family
#device ispfw # Firmware for QLogic HBAs- normally a module
device mpt # LSI-Logic MPT-Fusion
#device ncr # NCR/Symbios Logic
device sym # NCR/Symbios Logic (newer chipsets + those of `ncr')
device trm # Tekram DC395U/UW/F DC315U adapters
device adv # Advansys SCSI adapters
device adw # Advansys wide SCSI adapters
device aha # Adaptec 154x SCSI adapters
device aic # Adaptec 15[012]x SCSI adapters, AIC-6[23]60.
device bt # Buslogic/Mylex MultiMaster SCSI adapters
device ncv # NCR 53C500
device nsp # Workbit Ninja SCSI-3
device stg # TMC 18C30/18C50</programlisting>
<para>In this section, comment out any SCSI controllers not on
the system. For an IDE only system, these lines can be removed.
The <literal>*_REG_PRETTY_PRINT</literal> lines are
debugging options for their respective drivers.</para>
<programlisting># SCSI peripherals
device scbus # SCSI bus (required for SCSI)
device ch # SCSI media changers
device da # Direct Access (disks)
device sa # Sequential Access (tape etc)
device cd # CD
device pass # Passthrough device (direct SCSI access)
device ses # SCSI Environmental Services (and SAF-TE)</programlisting>
<para>Comment out any SCSI peripherals not on the system. If
the system only has IDE hardware, these lines can be removed
completely.</para>
<note>
<para>The USB &man.umass.4; driver and a few other drivers use
the SCSI subsystem even though they are not real SCSI devices.
Do not remove SCSI support if any such drivers are included in
the kernel configuration.</para>
</note>
<programlisting># RAID controllers interfaced to the SCSI subsystem
device amr # AMI MegaRAID
device arcmsr # Areca SATA II RAID
device asr # DPT SmartRAID V, VI and Adaptec SCSI RAID
device ciss # Compaq Smart RAID 5*
device dpt # DPT Smartcache III, IV - See NOTES for options
device hptmv # Highpoint RocketRAID 182x
device hptrr # Highpoint RocketRAID 17xx, 22xx, 23xx, 25xx
device iir # Intel Integrated RAID
device ips # IBM (Adaptec) ServeRAID
device mly # Mylex AcceleRAID/eXtremeRAID
device twa # 3ware 9000 series PATA/SATA RAID
# RAID controllers
device aac # Adaptec FSA RAID
device aacp # SCSI passthrough for aac (requires CAM)
device ida # Compaq Smart RAID
device mfi # LSI MegaRAID SAS
device mlx # Mylex DAC960 family
device pst # Promise Supertrak SX6000
device twe # 3ware ATA RAID</programlisting>
<para>Supported RAID controllers. If the system does not have any
of these, comment them out or remove them.</para>
<programlisting># atkbdc0 controls both the keyboard and the PS/2 mouse
device atkbdc # AT keyboard controller</programlisting>
<para>The <literal>atkbdc</literal> keyboard controller provides
I/O services for the AT keyboard and PS/2 style pointing
devices. This controller is required by &man.atkbd.4; and
&man.psm.4;.</para>
<programlisting>device atkbd # AT keyboard</programlisting>
<para>The &man.atkbd.4; driver, together with the &man.atkbdc.4;
controller, provides access to the AT 84 keyboard or the AT
enhanced keyboard which is connected to the AT keyboard
controller.</para>
<programlisting>device psm # PS/2 mouse</programlisting>
<para>Use this device if the mouse plugs into the PS/2 mouse
port.</para>
<programlisting>device kbdmux # keyboard multiplexer</programlisting>
<para>Basic support for keyboard multiplexing. If the system
does not use more than one keyboard, this line can be safely
removed.</para>
<programlisting>device vga # VGA video card driver</programlisting>
<para>The &man.vga.4; video card driver.</para>
<programlisting>
device splash # Splash screen and screen saver support</programlisting>
<para>Required by the boot splash screen and screen savers.</para>
<programlisting># syscons is the default console driver, resembling an SCO console
device sc</programlisting>
<para>&man.sc.4; is the default console driver and resembles a SCO
console. Since most full-screen programs access the console
through a terminal database library like
<filename>termcap</filename>, it should not matter whether
this or <literal>vt</literal>, the
<literal>VT220</literal> compatible console driver, is used.
When a user logs in, the <envar>TERM</envar> variable can be set
to <literal>scoansi</literal> if full-screen programs have
trouble running under this console.</para>
<programlisting># Enable this for the pcvt (VT220 compatible) console driver
#device vt
#options XSERVER # support for X server on a vt console
#options FAT_CURSOR # start with block cursor</programlisting>
<para>This is a VT220-compatible console driver, backward
compatible to VT100/102. It works well on some laptops which
have hardware incompatibilities with <literal>sc</literal>.
Users may need to set <envar>TERM</envar> to
<literal>vt100</literal> or <literal>vt220</literal> after
login. This driver is useful when connecting to a large number
of different machines over the network, where
<filename>termcap</filename> or <filename>terminfo</filename>
entries for the <literal>sc</literal> device are not
available as <literal>vt100</literal> should be available
on virtually any platform.</para>
<programlisting>device agp</programlisting>
<para>Include this if the system has an AGP card. This will
enable support for AGP and AGP GART for boards which have these
features.</para>
<programlisting># Add suspend/resume support for the i8254.
device pmtimer</programlisting>
<para>Timer device driver for power management events, such as
APM and ACPI.</para>
<programlisting># PCCARD (PCMCIA) support
# PCMCIA and cardbus bridge support
device cbb # cardbus (yenta) bridge
device pccard # PC Card (16-bit) bus
device cardbus # CardBus (32-bit) bus</programlisting>
<para>PCMCIA support. Keep this on laptop systems.</para>
<programlisting># Serial (COM) ports
device sio # 8250, 16[45]50 based serial ports</programlisting>
<para>These are the serial ports referred to as
<devicename>COM</devicename> ports in &windows;.</para>
<note>
<para>If the system has an internal modem on
<devicename>COM4</devicename> and a serial port at
<devicename>COM2</devicename>, change the IRQ of the modem to
2. For a multiport serial card, refer to &man.sio.4; for more
information on the proper values to add to
<filename>/boot/device.hints</filename>. Some video cards,
notably those based on S3 chips, use I/O addresses in the
form of <literal>0x*2e8</literal>. Since many cheap serial
cards do not fully decode the 16-bit I/O address space, they
clash with these cards, making the
<devicename>COM4</devicename> port practically
unavailable.</para>
<para>Each serial port is required to have a unique IRQ and the
default IRQs for <devicename>COM3</devicename> and
<devicename>COM4</devicename> cannot be used. The exception
is multiport cards where shared interrupts are
supported.</para>
</note>
<programlisting># Parallel port
device ppc</programlisting>
<para>This is the ISA bus parallel port interface.</para>
<programlisting>device ppbus # Parallel port bus (required)</programlisting>
<para>Provides support for the parallel port bus.</para>
<programlisting>device lpt # Printer</programlisting>
<para>Adds support for parallel port printers.</para>
<note>
<para>All three of the above are required to enable parallel
printer support.</para>
</note>
<programlisting>device ppi # Parallel port interface device</programlisting>
<para>The general-purpose I/O (<quote>geek port</quote>) +
IEEE1284 I/O.</para>
<programlisting>#device vpo # Requires scbus and da</programlisting>
<indexterm><primary>zip drive</primary></indexterm>
<para>This is for an Iomega Zip drive. It requires
<literal>scbus</literal> and <literal>da</literal> support.
Best performance is achieved with ports in EPP 1.9 mode.</para>
<programlisting>#device puc</programlisting>
<para>Uncomment this device if the system has a
<quote>dumb</quote> serial or parallel PCI card that is
supported by the &man.puc.4; glue driver.</para>
<programlisting># PCI Ethernet NICs.
device de # DEC/Intel DC21x4x (<quote>Tulip</quote>)
device em # Intel PRO/1000 adapter Gigabit Ethernet Card
device ixgb # Intel PRO/10GbE Ethernet Card
device txp # 3Com 3cR990 (<quote>Typhoon</quote>)
device vx # 3Com 3c590, 3c595 (<quote>Vortex</quote>)</programlisting>
<para>Various PCI network card drivers. Comment out or remove
any of these which are not present in the system.</para>
<programlisting># PCI Ethernet NICs that use the common MII bus controller code.
# NOTE: Be sure to keep the 'device miibus' line in order to use these NICs!
device miibus # MII bus support</programlisting>
<para>MII bus support is required for some PCI 10/100 Ethernet
NICs, namely those which use MII-compliant transceivers or
implement transceiver control interfaces that operate like an
MII. Adding <literal>device miibus</literal> to the kernel
config pulls in support for the generic miibus API and all of
the PHY drivers, including a generic one for PHYs that are not
specifically handled by an individual driver.</para>
<programlisting>device bce # Broadcom BCM5706/BCM5708 Gigabit Ethernet
device bfe # Broadcom BCM440x 10/100 Ethernet
device bge # Broadcom BCM570xx Gigabit Ethernet
device dc # DEC/Intel 21143 and various workalikes
device fxp # Intel EtherExpress PRO/100B (82557, 82558)
device lge # Level 1 LXT1001 gigabit ethernet
device msk # Marvell/SysKonnect Yukon II Gigabit Ethernet
device nge # NatSemi DP83820 gigabit ethernet
device nve # nVidia nForce MCP on-board Ethernet Networking
device pcn # AMD Am79C97x PCI 10/100 (precedence over 'lnc')
device re # RealTek 8139C+/8169/8169S/8110S
device rl # RealTek 8129/8139
device sf # Adaptec AIC-6915 (<quote>Starfire</quote>)
device sis # Silicon Integrated Systems SiS 900/SiS 7016
device sk # SysKonnect SK-984x & SK-982x gigabit Ethernet
device ste # Sundance ST201 (D-Link DFE-550TX)
device stge # Sundance/Tamarack TC9021 gigabit Ethernet
device ti # Alteon Networks Tigon I/II gigabit Ethernet
device tl # Texas Instruments ThunderLAN
device tx # SMC EtherPower II (83c170 <quote>EPIC</quote>)
device vge # VIA VT612x gigabit ethernet
device vr # VIA Rhine, Rhine II
device wb # Winbond W89C840F
device xl # 3Com 3c90x (<quote>Boomerang</quote>, <quote>Cyclone</quote>)</programlisting>
<para>Drivers that use the MII bus controller code.</para>
<programlisting># ISA Ethernet NICs. pccard NICs included.
device cs # Crystal Semiconductor CS89x0 NIC
# 'device ed' requires 'device miibus'
device ed # NE[12]000, SMC Ultra, 3c503, DS8390 cards
device ex # Intel EtherExpress Pro/10 and Pro/10+
device ep # Etherlink III based cards
device fe # Fujitsu MB8696x based cards
device ie # EtherExpress 8/16, 3C507, StarLAN 10 etc.
device lnc # NE2100, NE32-VL Lance Ethernet cards
device sn # SMC's 9000 series of Ethernet chips
device xe # Xircom pccard Ethernet
# ISA devices that use the old ISA shims
#device le</programlisting>
<para>ISA Ethernet drivers. See
<filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/NOTES</filename>
for details of which cards are supported by which driver.</para>
<programlisting># Wireless NIC cards
device wlan # 802.11 support</programlisting>
<para>Generic 802.11 support. This line is required for wireless
networking.</para>
<programlisting>device wlan_wep # 802.11 WEP support
device wlan_ccmp # 802.11 CCMP support
device wlan_tkip # 802.11 TKIP support</programlisting>
<para>Crypto support for 802.11 devices. These lines are needed
on systems which use encryption and 802.11i security
protocols.</para>
<programlisting>device an # Aironet 4500/4800 802.11 wireless NICs.
device ath # Atheros pci/cardbus NIC's
device ath_hal # Atheros HAL (Hardware Access Layer)
device ath_rate_sample # SampleRate tx rate control for ath
device awi # BayStack 660 and others
device ral # Ralink Technology RT2500 wireless NICs.
device wi # WaveLAN/Intersil/Symbol 802.11 wireless NICs.
#device wl # Older non 802.11 Wavelan wireless NIC.</programlisting>
<para>Support for various wireless cards.</para>
<programlisting># Pseudo devices
device loop # Network loopback</programlisting>
<para>This is the generic loopback device for TCP/IP. This is
<emphasis>mandatory</emphasis>.</para>
<programlisting>device random # Entropy device</programlisting>
<para>Cryptographically secure random number generator.</para>
<programlisting>device ether # Ethernet support</programlisting>
<para><literal>ether</literal> is only needed if the system has
an Ethernet card. It includes generic Ethernet protocol
code.</para>
<programlisting>device sl # Kernel SLIP</programlisting>
<para><literal>sl</literal> provides SLIP support. This has been
almost entirely supplanted by PPP, which is easier to set up,
better suited for modem-to-modem connection, and more
powerful.</para>
<programlisting>device ppp # Kernel PPP</programlisting>
<para>This is for kernel PPP support for dial-up connections.
There is also a version of PPP implemented as a userland
application that uses <literal>tun</literal> and offers more
flexibility and features such as demand dialing.</para>
<programlisting>device tun # Packet tunnel.</programlisting>
<para>This is used by the userland PPP software. See the <link
linkend="userppp">PPP</link> section of the Handbook for more
information.</para>
<programlisting><anchor id="kernelconfig-ptys"/>
device pty # Pseudo-ttys (telnet etc)</programlisting>
<para>This is a <quote>pseudo-terminal</quote> or simulated
login port. It is used by incoming <command>telnet</command>
and <command>rlogin</command> sessions,
<application>xterm</application>, and some other applications
such as <application>Emacs</application>.</para>
<programlisting>device md # Memory <quote>disks</quote></programlisting>
<para>Memory disk pseudo-devices.</para>
<programlisting>device gif # IPv6 and IPv4 tunneling</programlisting>
<para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6
tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6
tunneling. The <literal>gif</literal> device is
<quote>auto-cloning</quote>, and will create device nodes as
needed.</para>
<programlisting>device faith # IPv6-to-IPv4 relaying (translation)</programlisting>
<para>This pseudo-device captures packets that are sent to it and
diverts them to the IPv4/IPv6 translation daemon.</para>
<programlisting># The `bpf' device enables the Berkeley Packet Filter.
# Be aware of the administrative consequences of enabling this!
# Note that 'bpf' is required for DHCP.
device bpf # Berkeley packet filter</programlisting>
<para>The Berkeley Packet Filter pseudo-device allows network
interfaces to be placed in promiscuous mode, capturing every
packet on a broadcast network such as an Ethernet network.
These packets can be captured to disk and or examined using
&man.tcpdump.1;.</para>
<note>
<para>The &man.bpf.4; device is also used by &man.dhclient.8;.
If DHCP is used, leave this uncommented.</para>
</note>
<programlisting># USB support
device uhci # UHCI PCI->USB interface
device ohci # OHCI PCI->USB interface
device ehci # EHCI PCI->USB interface (USB 2.0)
device usb # USB Bus (required)
#device udbp # USB Double Bulk Pipe devices
device ugen # Generic
device uhid # <quote>Human Interface Devices</quote>
device ukbd # Keyboard
device ulpt # Printer
device umass # Disks/Mass storage - Requires scbus and da
device ums # Mouse
device ural # Ralink Technology RT2500USB wireless NICs
device urio # Diamond Rio 500 MP3 player
device uscanner # Scanners
# USB Ethernet, requires mii
device aue # ADMtek USB Ethernet
device axe # ASIX Electronics USB Ethernet
device cdce # Generic USB over Ethernet
device cue # CATC USB Ethernet
device kue # Kawasaki LSI USB Ethernet
device rue # RealTek RTL8150 USB Ethernet</programlisting>
<para>Support for various USB devices.</para>
<programlisting># FireWire support
device firewire # FireWire bus code
device sbp # SCSI over FireWire (Requires scbus and da)
device fwe # Ethernet over FireWire (non-standard!)</programlisting>
<para>Support for various Firewire devices.</para>
<para>For more information and additional devices supported by
&os;, see
<filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/NOTES</filename>.</para>
<sect2>
<title>Large Memory Configurations
(<acronym>PAE</acronym>)</title>
<indexterm>
<primary>Physical Address Extensions
(<acronym>PAE</acronym>)</primary>
<secondary>large memory</secondary>
</indexterm>
<para>Large memory configuration machines require access to
more than the 4 gigabyte limit on User+Kernel Virtual
Address (<acronym>KVA</acronym>) space. Due to this
limitation, Intel added support for 36-bit physical address
space access in the &pentium; Pro and later line of
CPUs.</para>
<para>The Physical Address Extension (<acronym>PAE</acronym>)
capability of the &intel; &pentium; Pro and later CPUs allows
memory configurations of up to 64 gigabytes. &os; provides
support for this capability via the <option>PAE</option>
kernel configuration option, available in all current release
versions of &os;. Due to the limitations of the Intel memory
architecture, no distinction is made for memory above or below
4 gigabytes. Memory allocated above 4 gigabytes is simply
added to the pool of available memory.</para>
<para>To enable <acronym>PAE</acronym> support in the kernel,
add the following line to the kernel configuration
file:</para>
<programlisting>options PAE</programlisting>
<note>
<para>The <acronym>PAE</acronym> support in &os; is only
available for &intel; IA-32 processors. It should also be
noted that the <acronym>PAE</acronym> support in &os; has
not received wide testing, and should be considered beta
quality compared to other stable features of &os;.</para>
</note>
<para><acronym>PAE</acronym> support in &os; has a few
limitations:</para>
<itemizedlist>
<listitem>
<para>A process is not able to access more than 4
gigabytes of virtual memory space.</para>
</listitem>
<listitem>
<para>Device drivers that do not use the &man.bus.dma.9;
interface will cause data corruption in a
<acronym>PAE</acronym> enabled kernel and are not
recommended for use. For this reason, a
<filename>PAE</filename> kernel configuration file is
provided in &os; which excludes all drivers not known to
work in a <acronym>PAE</acronym> enabled kernel.</para>
</listitem>
<listitem>
<para>Some system tunables determine memory resource usage
by the amount of available physical memory. Such
tunables can unnecessarily over-allocate due to the
large memory nature of a <acronym>PAE</acronym> system.
One such example is the
<varname>kern.maxvnodes</varname> sysctl, which controls
the maximum number of vnodes allowed in the kernel. It
is advised to adjust this and other such tunables to a
reasonable value.</para>
</listitem>
<listitem>
<para>It might be necessary to increase the kernel virtual
address (<acronym>KVA</acronym>) space or to reduce the
amount of specific kernel resource that is heavily used
in order to avoid <acronym>KVA</acronym> exhaustion.
The <option>KVA_PAGES</option> kernel option can be used
for increasing the <acronym>KVA</acronym> space.</para>
</listitem>
</itemizedlist>
<para>For performance and stability concerns, it is advised to
consult &man.tuning.7;. &man.pae.4; contains up-to-date
information on &os;'s <acronym>PAE</acronym> support.</para>
</sect2>
</sect1>
<sect1 id="kernelconfig-trouble">
<title>If Something Goes Wrong</title>
<para>There are four categories of trouble that can occur when
building a custom kernel. They are:</para>
<variablelist>
<varlistentry>
<term><command>config</command> fails:</term>
<listitem>
<para>If &man.config.8; fails, it is probably a simple
error. Fortunately, &man.config.8; will print the line
number that it had trouble with. For example, for
this message:</para>
<screen>config: line 17: syntax error</screen>
<para>Make sure the keyword on line 17 is typed correctly by
comparing it to the
<filename>GENERIC</filename> kernel or another
reference.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>make</command> fails:</term>
<listitem>
<para>If <command>make</command> fails, it usually signals
an error in the kernel description which is not severe
enough for &man.config.8; to catch. Review the
configuration, and if you still cannot resolve the
problem, send an email to the &a.questions; with the
kernel configuration.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>The kernel does not boot:<anchor
id="kernelconfig-noboot"/></term>
<listitem>
<para>If the new kernel does not boot, or fails to recognize
devices, do not panic! Fortunately, &os; has an excellent
mechanism for recovering from incompatible kernels.
Simply choose the kernel to boot from at the &os; boot
loader. This can be accessed when the system boot menu
appears by selecting the <quote>Escape to a loader
prompt</quote> option. At the prompt, type
<command>boot
<replaceable>kernel.old</replaceable></command>, or
the name of any other kernel that will boot properly.
When reconfiguring a kernel, it is always a good idea to
keep a kernel that is known to work on hand.</para>
<para>After booting with a good kernel, check over the
configuration file and try to build it again. One helpful
resource is <filename>/var/log/messages</filename> which
records the kernel messages from every successful boot.
Also, &man.dmesg.8; will print the kernel messages from
the current boot.</para>
<note>
<para>When troubleshooting a kernel, make sure to keep
<filename>GENERIC</filename>, or some other kernel that
is known to work, on hand as a different name that will
not get erased on the next build. Do not rely on
<filename>kernel.old</filename> because when installing
a new kernel, <filename>kernel.old</filename> is
overwritten with the last installed kernel which may
be non-functional. As soon as possible, move the
working kernel to the proper <filename
class="directory">/boot/kernel</filename>
location or commands such as &man.ps.1; may not work
properly. To do this, simply rename the directory
containing the good kernel:</para>
<screen>&prompt.root; <userinput>mv /boot/kernel <replaceable>/boot/kernel.bad</replaceable></userinput>
&prompt.root; <userinput>mv /boot/<replaceable>kernel.good</replaceable> /boot/kernel</userinput></screen>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>The kernel works, but &man.ps.1; does not work
any more:</term>
<listitem>
<para>If the kernel version differs from the one that the
system utilities have been built with, for example, a
-CURRENT kernel on a -RELEASE, many system status commands
like &man.ps.1; and &man.vmstat.8; will not work. To fix
this, <link linkend="makeworld">recompile and install a
world</link> built with the same version of the
source tree as the kernel. This is one reason why it is
not a good idea to use a different version of the kernel
than the rest of the operating system.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>