<?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 more and more
of &os; becomes dynamically configurable it is still
occasionally necessary to reconfigure and recompile your
kernel.</para>
<para>After reading this chapter, you will know:</para>
<itemizedlist>
<listitem>
<para>Why you might need to build a custom kernel.</para>
</listitem>
<listitem>
<para>How to write a kernel configuration file, or alter an
existing 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 within this chapter by way of
example should be executed as <username>root</username> in
order to succeed.</para>
</sect1>
<sect1 id="kernelconfig-custom-kernel">
<title>Why Build a Custom Kernel?</title>
<para>Traditionally, &os; has had what is called a
<quote>monolithic</quote> kernel. This means that the kernel
was one large program, supported a fixed list of devices, and
if you wanted to change the kernel's behavior then you had to
compile a new kernel, and then reboot your computer with the
new kernel.</para>
<para>Today, &os; is rapidly moving to a model where much of the
kernel's functionality is contained in modules which can be
dynamically loaded and unloaded from the kernel as necessary.
This allows the kernel to adapt to new hardware suddenly
becoming available (such as PCMCIA cards in a laptop), or for
new functionality to be brought into the kernel that was not
necessary when the kernel was originally compiled. This is
known as a modular kernel.</para>
<para>Despite this, it is still necessary to carry out some
static kernel configuration. In some cases this is because
the functionality is so tied to the kernel that it can not be
made dynamically loadable. In others it may simply be because
no one has yet taken the time to write a dynamic loadable kernel
module for that functionality.</para>
<para>Building a custom kernel is one of the most important rites
of passage for advanced BSD users. This process, while
time consuming, will provide many benefits to your &os; system.
Unlike the <filename>GENERIC</filename> kernel, which must
support a wide range of hardware, a custom kernel only contains
support for <emphasis>your</emphasis> PC'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 you have on your system, the time it takes
your system to boot can decrease dramatically.</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 especially useful on a system with a small amount
of RAM.</para>
</listitem>
<listitem>
<para>Additional hardware support. A custom kernel allows
you to add in support for devices which are not present
in the <filename>GENERIC</filename> kernel, such as
sound cards.</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 may easily be created by viewing the current operating
system configuration. For example, µsoft;'s
<application>Device Manager</application> normally contains
important information about installed devices. The
<application>Device Manager</application> is located in the
control panel.</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 the &man.dmesg.8; utility and the &man.man.1;
commands. Most device drivers on &os; have a manual page,
listing supported hardware, and during the boot probe, found
hardware will be listed. For example, the following lines
indicate that the <devicename>psm</devicename> 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 viewing the
<filename>/var/run/dmesg.boot</filename> file.</para>
<para>Another method of finding hardware is by using the
&man.pciconf.8; utility 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 bit of output, obtained using
<command>pciconf <option>-lv</option></command> shows that the
<devicename>ath</devicename> driver located a wireless Ethernet
device. Using
<command>man <replaceable>ath</replaceable></command> will
return the &man.ath.4; manual page.</para>
<para>The <option>-k</option> flag, when passed to &man.man.1;
can also be used to provide useful information. From the
above, one can issue:</para>
<screen>&prompt.root; man -k <replaceable>Atheros</replaceable></screen>
<para>To get a list of manual pages which contain that particular
word:</para>
<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 reasons 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 the
<filename class="directory">/boot/kernel</filename> directory
and may be dynamically loaded into the running kernel using
&man.kldload.8;. Most, if not all kernel drivers have a
specific module and manual page. For example, the last section
noted the <devicename>ath</devicename> wireless Ethernet driver.
This device 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>As instructed, adding the
<literal>if_ath_load="YES"</literal> line to the
<filename>/boot/loader.conf</filename> file will
enable loading this module dynamically at boot time.</para>
<para>In some cases; however, there is no associated module.
This is mostly true for certain subsystems and very important
drivers, for instance, the fast file system
(<acronym>FFS</acronym>) is a required option in the kernel.
As is network support (INET). Unfortunately the only way to
tell if a driver is required 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 without the module added to
<filename>loader.conf</filename>. When in doubt, check for
the module and then 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>First, let us take a quick tour of the kernel build
directory. All directories mentioned will be relative to the
main <filename>/usr/src/sys</filename> directory, which is
also accessible through the path name <filename>/sys</filename>.
There are a number of subdirectories here representing different
parts of the kernel, but the most important for our purposes
are <filename><replaceable>arch</replaceable>/conf</filename>,
where you will edit your custom kernel configuration, and
<filename>compile</filename>, which is the staging area where
your kernel will be built. <replaceable>arch</replaceable>
represents one of <filename>i386</filename>,
<filename>amd64</filename>, <filename>ia64</filename>,
<filename>powerpc</filename>, <filename>sparc64</filename>,
or <filename>pc98</filename> (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 machine independent code common
to all platforms to which &os; could potentially be ported.
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 that you are using
the i386 architecture. If your system has a different
architecture you need to change the path names
accordingly.</para>
<note>
<para>If the directory <filename>/usr/src/</filename> does not
exist on your system (or if it is empty), then the sources
have not been installed. The easiest way to install the full
source is to use &man.csup.1; as described in <xref
linkend="synching"/>. You 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, change to the
<filename><replaceable>arch</replaceable>/conf</filename>
directory and copy the <filename>GENERIC</filename>
configuration file to the name you want to give your 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 and,
if you are maintaining multiple &os; machines with different
hardware, it is a good idea to name it after your machine's
hostname. We will call it
<filename><replaceable>MYKERNEL</replaceable></filename> for
the purpose of this example.</para>
<tip>
<para>Storing your kernel configuration file directly under
<filename>/usr/src</filename> can be a bad idea. If you are
experiencing problems it can be tempting to just delete
<filename>/usr/src</filename> and start again. After doing
this, it usually only takes a few seconds for
you to realize that you have deleted your custom kernel
configuration file. Also, do not edit
<filename>GENERIC</filename> directly, as it may get
overwritten the next time you
<link linkend="updating-upgrading">update your source
tree</link>,
and your kernel modifications will be lost.</para>
<para>You might want to keep your kernel configuration file
elsewhere, and then create a symbolic link to the file in
the <filename><replaceable>i386</replaceable></filename>
directory.</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>Now, edit
<filename><replaceable>MYKERNEL</replaceable></filename>
with your favorite text editor. If you are just starting out,
the only editor available will probably be
<application>vi</application>, which is too complex to explain
here, but is covered well in many books in the <link
linkend="bibliography">bibliography</link>. However, &os;
does offer an easier editor called <application>ee</application>
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 <filename>GENERIC</filename>.</para>
<indexterm><primary>SunOS</primary></indexterm>
<para>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 <filename>GENERIC</filename>
configuration file might seem overwhelming to you, so follow
the descriptions in the
<link linkend="kernelconfig-config">Configuration File</link>
section slowly and carefully.</para>
<note>
<para>If you <link
linkend="updating-upgrading">sync your source tree</link>
with the latest sources of the &os; project, be sure to always
check the file <filename>/usr/src/UPDATING</filename> before
you perform 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
your version of the &os; source, and is therefore more up
to date with new information than this handbook.</para>
</note>
<para>You must now 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>Change to the <filename
class="directory">/usr/src</filename> directory:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
</step>
<step>
<para>Compile the kernel:</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 you build a custom kernel,
<emphasis>all</emphasis> kernel modules will be rebuilt as
well. If you want to update a kernel faster or to build only
custom modules, you should 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 sets up a list of modules to build instead
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 variables which
you may find useful in the process of building kernel, refer
to &man.make.conf.5; manual page.</para>
</tip>
<indexterm>
<primary><filename class="directory">/boot/kernel.old</filename></primary>
</indexterm>
<para>The new kernel will be copied to the <filename
class="directory">/boot/kernel</filename> directory 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 to use your new kernel.
If something goes wrong, there are some <link
linkend="kernelconfig-trouble">troubleshooting</link>
instructions at the end of this chapter that you may find
useful. Be sure to read the section which explains how to
recover in case your 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>/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 or incorrectness.</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>.
<anchor
id="kernelconfig-options"/> For an exhaustive list of
architecture dependent options and devices, see the
<filename>NOTES</filename> file in the same directory as the
<filename>GENERIC</filename> file. For architecture independent
options, see
<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 logically included in the current
one, making it easy to maintain small changes relative to an
existing file. For example, if you require a
<filename>GENERIC</filename> kernel with only a small number
of additional options or drivers, this allows you to maintain
only a delta with respect to GENERIC:</para>
<programlisting>include GENERIC
ident MYKERNEL
options IPFIREWALL
options DUMMYNET
options IPFIREWALL_DEFAULT_TO_ACCEPT
options IPDIVERT</programlisting>
<para>Many administrators will find that this model offers
significant benefits over the historic writing of configuration
files from scratch: the local configuration file will express
only local differences from a <filename>GENERIC</filename>
kernel and as upgrades are performed, new features added to
<filename>GENERIC</filename> will be added to the local kernel
unless specifically prevented using
<literal>nooptions</literal> or <literal>nodevice</literal>.
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,
as normally done for testing purposes, 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 your 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>The above option specifies the type of CPU you have in your
system. You may have multiple instances of the CPU line (if,
for example, you are not sure whether you should use
<literal>I586_CPU</literal> or <literal>I686_CPU</literal>),
but for a custom kernel it is best to specify only the CPU
you have. If you are unsure of your CPU type, you can check
the <filename>/var/run/dmesg.boot</filename> file to view your
boot messages.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>ident</secondary>
</indexterm>
<programlisting>ident GENERIC</programlisting>
<para>This is the identification of the kernel. You should change
this to whatever you named your kernel,
i.e., <literal><replaceable>MYKERNEL</replaceable></literal>
if you have followed the instructions of the previous examples.
The value you put in the <literal>ident</literal> string will
print when you boot up the kernel, so it is useful to give the
new kernel a different name if you want to keep it separate
from your usual kernel (e.g., you want to build an experimental
kernel).</para>
<programlisting>#To statically compile in device wiring instead of /boot/device.hints
#hints "GENERIC.hints" # Default places to look for devices.</programlisting>
<para>The &man.device.hints.5; is
used to configure options of the device drivers. The default
location that &man.loader.8; will check at boot time is
<filename>/boot/device.hints</filename>. Using the
<literal>hints</literal> option you can compile these hints
statically into your kernel. Then there is no need to create a
<filename>device.hints</filename> file in
<filename>/boot</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>The normal build process of &os; includes
debugging information when building the kernel with the
<option>-g</option> option, which 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 threads that are in the kernel to be preempted
by higher priority threads. It helps with interactivity and
allows interrupt threads to run sooner rather than
waiting.</para>
<programlisting>options INET # InterNETworking</programlisting>
<para>Networking support. Leave this in, even if you do not
plan to be connected to a network. Most programs require at
least loopback networking (i.e., making network connections
within your PC), so this is essentially mandatory.</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
you boot from the hard disk.</para>
<programlisting>options SOFTUPDATES # Enable FFS Soft Updates support</programlisting>
<para>This option enables Soft Updates in the kernel, this will
help 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 from &man.mount.8; to
see if Soft Updates is enabled for your system disks. If you
do not see the <literal>soft-updates</literal> option then you
will need to activate it using the &man.tunefs.8; (for existing
file systems) or &man.newfs.8; (for new file systems)
commands.</para>
<programlisting>options UFS_ACL # Support for access control lists</programlisting>
<para>This option enables kernel support
for access control lists. 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 access control lists,
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. You would normally keep this for a large
server, or interactive workstation, and remove it if you are
using &os; on a smaller system 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. Unless you plan to mount
partitions from a &unix; file server over TCP/IP, you can
comment these out.</para>
<indexterm>
<primary>kernel options</primary>
<secondary>MSDOSFS</secondary>
</indexterm>
<programlisting>options MSDOSFS # MSDOS Filesystem</programlisting>
<para>The &ms-dos; file system. Unless you plan to mount a DOS
formatted hard drive partition at boot time, you can safely
comment this out. It will be automatically loaded the first
time you mount a DOS partition, as described above. Also,
the excellent
<filename role="package">emulators/mtools</filename> software
allows you to access DOS floppies without having to mount and
unmount them (and does not require <literal>MSDOSFS</literal> at
all).</para>
<programlisting>options CD9660 # ISO 9660 Filesystem</programlisting>
<para>The ISO 9660 file system for CDROMs. Comment it out if
you do not have a CDROM drive or only mount data CDs
occasionally (since it will be dynamically loaded the first
time you mount a data CD). 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>/proc</filename> which allows
programs like &man.ps.1; to give you 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>: installs 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>. 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; some programs
will act strangely if you comment this 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 only in
5.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 your system. If you only have IDE hard
drives, you can ignore this, otherwise you can try to lower
this number, to speed up booting. Of course, if you do this
and &os; has trouble recognizing your SCSI devices, you will
have to raise it 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 you use X, you will definitely
want to 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>The <option>-p</option> option of the &man.ipcs.1;
command 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
(such as <application>&staroffice;</application>).</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>/dev</filename>.</para>
<programlisting>options ADAPTIVE_GIANT # Giant mutex is adaptive.</programlisting>
<para>Giant is the name of a mutual exclusion mechanism (a
sleep mutex)that protects a large set of kernel resources.
Today, this is an unacceptable performance bottleneck which
is actively being replaced with locks that protect individual
resources. The <literal>ADAPTIVE_GIANT</literal> option causes
Giant to be included in the set of mutexes adaptively spun on.
That is, when a thread wants to lock the Giant mutex, but it
is already locked by a thread on another CPU, the first thread
will keep running and wait for the lock to be released.
Normally, the thread would instead go back to sleep and wait
for its next chance to run. If you are not sure, leave this
in.</para>
<note>
<para>Note that on &os; 8.0-RELEASE and later versions, all
mutexes are adaptive by default, unless explicitly set to
non-adaptive by compiling with the
<literal>NO_ADAPTIVE_MUTEXES</literal> option. As a result,
Giant is adaptive by default now, and the
<literal>ADAPTIVE_GIANT</literal> option has been removed
from the kernel configuration.</para>
</note>
<indexterm>
<primary>kernel options</primary>
<secondary>SMP</secondary>
</indexterm>
<programlisting>device apic # I/O APIC</programlisting>
<para>The apic device enables the use of the I/O APIC for
interrupt delivery. The apic device can be used in both UP
and SMP kernels, but is required for SMP kernels. Add
<literal>options SMP</literal> to include support for multiple
processors.</para>
<note>
<para>The apic device exists only on the i386 architecture, this
configuration line should not be used on other
architectures.</para>
</note>
<programlisting>device eisa</programlisting>
<para>Include this if you have 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 if you have 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. You only
need one <literal>device ata</literal> line 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>SCSI controllers. Comment out any you do not have in your
system. If you have an IDE only system, you can remove these
altogether. 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>SCSI peripherals. Again, comment out any you do not have,
or if you have only IDE hardware, you can remove them
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.
Therefore make sure not to 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 you do not have any of
these, you can 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 keyboard controller (<literal>atkbdc</literal>)
provides I/O services for the AT keyboard and PS/2 style
pointing devices. This controller is required by the keyboard
driver (<literal>atkbd</literal>) and the PS/2 pointing device
driver (<literal>psm</literal>).</para>
<programlisting>device atkbd # AT keyboard</programlisting>
<para>The <literal>atkbd</literal> driver, together with
<literal>atkbdc</literal> 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 your mouse plugs into the PS/2 mouse
port.</para>
<programlisting>device kbdmux # keyboard multiplexer</programlisting>
<para>Basic support for keyboard multiplexing. If you do not
plan to use more than one keyboard on the system, you can
safely remove that line.</para>
<programlisting>device vga # VGA video card driver</programlisting>
<para>The video card driver.</para>
<programlisting>
device splash # Splash screen and screen saver support</programlisting>
<para>Splash screen at start up! Screen savers require this
too.</para>
<programlisting># syscons is the default console driver, resembling an SCO console
device sc</programlisting>
<para><literal>sc</literal> 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
you use this or <literal>vt</literal>, the
<literal>VT220</literal> compatible console driver. When you
log in, set your <envar>TERM</envar> variable 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>.
Also set your <envar>TERM</envar> variable to
<literal>vt100</literal> or <literal>vt220</literal> when you
log in. This driver might also prove 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 often not
available — <literal>vt100</literal> should be available
on virtually any platform.</para>
<programlisting>device agp</programlisting>
<para>Include this if you have an AGP card in the system. This
will enable support for AGP, and AGP GART for boards which
have these features.</para>
<indexterm>
<primary>APM</primary>
</indexterm>
<programlisting># Power management support (see NOTES for more options)
#device apm</programlisting>
<para>Advanced Power Management support. Useful for laptops,
although this is disabled in
<filename>GENERIC</filename> by default.</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. You want this if you are using a
laptop.</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 the &ms-dos;/&windows;
world.</para>
<note>
<para>If you have an internal modem on
<devicename>COM4</devicename> and a serial port at
<devicename>COM2</devicename>, you will have to change the
IRQ of the modem to 2 (for obscure technical reasons,
IRQ2 = IRQ 9) in order to access it from &os;. If you have
a multiport serial card, check the manual page for &man.sio.4;
for more information on the proper values to add to your
<filename>/boot/device.hints</filename>. Some video cards
(notably those based on S3 chips) use IO addresses in the
form of <literal>0x*2e8</literal>, and since many cheap serial
cards do not fully decode the 16-bit IO 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
(unless you are using one of the multiport cards where shared
interrupts are supported), so the default IRQs for
<devicename>COM3</devicename> and
<devicename>COM4</devicename> cannot be used.</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>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 you have 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 not present in your 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
if you intend to 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. If you
telnet or FTP to <hostid>localhost</hostid> (aka <hostid
role="ipaddr">127.0.0.1</hostid>) it will come back at you
through this device. 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 you have an
Ethernet card. It includes generic Ethernet protocol
code.</para>
<programlisting>device sl # Kernel SLIP</programlisting>
<para><literal>sl</literal> is for 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 this book
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>This is the Berkeley Packet Filter. This pseudo-device
allows network interfaces to be placed in promiscuous mode,
capturing every packet on a broadcast network (e.g., an
Ethernet). These packets can be captured to disk and or
examined with the &man.tcpdump.1; program.</para>
<note>
<para>The &man.bpf.4; device is also used by
&man.dhclient.8; to obtain the IP address of the default
router (gateway) and so on. If you use DHCP, 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,
simply add the following line to your 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 VM 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 <option>kern.maxvnodes</option>
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
(see above) 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 the &man.tuning.7; manual page. The &man.pae.4;
manual page 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 the &man.config.8; command fails when you
give it your kernel description, you have probably made a
simple error somewhere. Fortunately,
&man.config.8; will print the line number that it
had trouble with, so that you can quickly locate the line
containing the error. For example, if you see:</para>
<screen>config: line 17: syntax error</screen>
<para>Make sure the
keyword 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 the <command>make</command> command fails, it
usually signals an error in your kernel description which
is not severe enough for &man.config.8; to catch. Again,
look over your configuration, and if you still cannot
resolve the problem, send mail to the &a.questions; with
your kernel configuration, and it should be diagnosed
quickly.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>The kernel does not boot:<anchor
id="kernelconfig-noboot"/></term>
<listitem>
<para>If your new kernel does not boot, or fails to
recognize your devices, do not panic! Fortunately, &os;
has an excellent mechanism for recovering from
incompatible kernels. Simply choose the kernel you want
to boot from at the &os; boot loader. You can access this
when the system boot menu appears. Select the
<quote>Escape to a loader prompt</quote> option, number
six. 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 you can check over
your configuration file and try to build it again. One
helpful resource is the
<filename>/var/log/messages</filename> file which records,
among other things, all of the kernel messages from every
successful boot. Also, the &man.dmesg.8; command will
print the kernel messages from the current boot.</para>
<note>
<para>If you are having trouble building a kernel, make
sure to keep a <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. You cannot 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. Also, 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 you have installed a different version of the
kernel 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 any more. You should
<link linkend="makeworld">recompile and install a
world</link> built with the same version of the
source tree as your kernel. 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.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>