1548 lines
67 KiB
XML
1548 lines
67 KiB
XML
<?xml version="1.0" encoding="ISO8859-1" standalone="no"?>
|
|
<!--
|
|
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 plip # TCP/IP over parallel</programlisting>
|
|
|
|
<para>This is the driver for the parallel network interface.</para>
|
|
|
|
<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>
|