os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

White space fix only. Translators can ignore.

Browse source 
Sponsored by: iXsystems
This commit is contained in:
Dru Lavigne 2014-03-19 17:14:08 +00:00
parent 045622bc49
commit ccdca8886e
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=44289
1 changed files with 157 additions and 150 deletions
Download patch file Download diff file Expand all files Collapse all files

307
en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml
View file

@ -69,17 +69,17 @@
</itemizedlist>
<para>All of the commands listed in the examples in this chapter
should be executed as <systemitem class="username">root</systemitem>.</para>
should be executed as <systemitem
class="username">root</systemitem>.</para>
</sect1>
<sect1 xml:id="kernelconfig-custom-kernel">
<title>Why Build a Custom Kernel?</title>
<para>Traditionally, &os; used a monolithic kernel.
The kernel was one large program, supported a fixed list of
devices, and in order to change the kernel's behavior, one had
to compile and then reboot into a new
kernel.</para>
<para>Traditionally, &os; used a monolithic kernel. The kernel
was one large program, supported a fixed list of devices, and in
order to change the kernel's behavior, one had to compile and
then reboot into a new kernel.</para>
<para>Today, most of the functionality in the &os; kernel is
contained in modules which can be dynamically loaded and
@ -132,12 +132,11 @@
doing so. If there is a need for specific hardware support,
it may already exist as a module.</para>
<para>Kernel modules exist in <filename>/boot/kernel</filename> and may be
dynamically loaded into the running kernel using
&man.kldload.8;. Most kernel drivers have a
loadable module and manual page. For example, the &man.ath.4;
wireless Ethernet driver has the following information in its
manual page:</para>
<para>Kernel modules exist in <filename>/boot/kernel</filename>
and may be dynamically loaded into the running kernel using
&man.kldload.8;. Most kernel drivers have a loadable module and
manual page. For example, the &man.ath.4; wireless Ethernet
driver has the following information in its manual page:</para>
<screen>Alternatively, to load the driver as a module at boot time, place the
following line in &man.loader.conf.5;:
@ -145,11 +144,12 @@ following line in &man.loader.conf.5;:
if_ath_load="YES"</screen>
<para>Adding <literal>if_ath_load="YES"</literal> to
<filename>/boot/loader.conf</filename> will load this
module dynamically at boot time.</para>
<filename>/boot/loader.conf</filename> will load this module
dynamically at boot time.</para>
<para>In some cases, there is no associated module in <filename>/boot/kernel</filename>. This is
mostly true for certain subsystems.</para>
<para>In some cases, there is no associated module in
<filename>/boot/kernel</filename>. This is mostly true for
certain subsystems.</para>
</sect1>
<sect1 xml:id="kernelconfig-devices">
@ -166,11 +166,10 @@ following line in &man.loader.conf.5;:
-->
<title>Finding the System Hardware</title>
<para>Before editing the kernel configuration file, it is recommended
to perform an inventory of the machine's hardware. On a dual-boot
system, the inventory
can be created from the other operating system.
For example, &microsoft;'s
<para>Before editing the kernel configuration file, it is
recommended to perform an inventory of the machine's hardware.
On a dual-boot system, the inventory can be created from the
other operating system. For example, &microsoft;'s
<application>Device Manager</application> contains information
about installed devices.</para>
@ -180,12 +179,11 @@ following line in &man.loader.conf.5;:
access <application>Device Manager</application>.</para>
</note>
<para>If &os; is the only installed operating system,
use &man.dmesg.8; to determine the hardware that was found and
listed during the boot probe. Most device
drivers on &os; have a manual page which lists the hardware supported by that driver.
For
example, the following lines indicate that the &man.psm.4;
<para>If &os; is the only installed operating system, use
&man.dmesg.8; to determine the hardware that was found and
listed during the boot probe. Most device drivers on &os; have
a manual page which lists the hardware supported by that driver.
For example, the following lines indicate that the &man.psm.4;
driver found a mouse:</para>
<screen>psm0: &lt;PS/2 Mouse&gt; irq 12 on atkbdc0
@ -197,12 +195,11 @@ psm0: model Generic PS/2 mouse, device ID 0</screen>
removed from a custom kernel configuration file.</para>
<para>If the output of <command>dmesg</command> does not display
the results of the boot probe output, instead read the contents of
<filename>/var/run/dmesg.boot</filename>.</para>
the results of the boot probe output, instead read the contents
of <filename>/var/run/dmesg.boot</filename>.</para>
<para>Another tool for finding hardware is
&man.pciconf.8;, which provides more verbose output. For
example:</para>
<para>Another tool for finding hardware is &man.pciconf.8;, which
provides more verbose output. For example:</para>
<screen>&prompt.user; <userinput>pciconf -lv</userinput>
ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00
@ -211,14 +208,12 @@ ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01
class = network
subclass = ethernet</screen>
<para>This output shows that the
<filename>ath</filename> driver located a wireless Ethernet
device.</para>
<para>This output shows that the <filename>ath</filename> driver
located a wireless Ethernet device.</para>
<para>The <option>-k</option> flag of &man.man.1;
can be used to provide useful information. For example, to
display a list of manual pages which contain the specified
word:</para>
<para>The <option>-k</option> flag of &man.man.1; can be used to
provide useful information. For example, to display a list of
manual pages which contain the specified word:</para>
<screen>&prompt.root; <userinput>man -k <replaceable>Atheros</replaceable></userinput></screen>
@ -252,36 +247,39 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
empty, source has not been installed. Source can be installed
using <application>Subversion</application> and the instructions
in <xref linkend="svn"/>.</para>
<para>Once source is installed, review the contents of
<filename>/usr/src/sys</filename>. This directory contains a
number of subdirectories, including those which represent the following
supported architectures: <filename>amd64</filename>, <filename>i386</filename>, <filename>ia64</filename>, <filename>pc98</filename>, <filename>powerpc</filename>, and <filename>sparc64</filename>. Everything inside a
particular architecture's directory deals with that architecture
only and the rest of the code is machine independent code common
to all platforms. Each supported architecture has a <filename>conf</filename> subdirectory
which contains the <filename>GENERIC</filename> kernel
configuration file for that architecture.</para>
number of subdirectories, including those which represent the
following supported architectures: <filename>amd64</filename>,
<filename>i386</filename>, <filename>ia64</filename>,
<filename>pc98</filename>, <filename>powerpc</filename>, and
<filename>sparc64</filename>. Everything inside a particular
architecture's directory deals with that architecture only and
the rest of the code is machine independent code common to all
platforms. Each supported architecture has a
<filename>conf</filename> subdirectory which contains the
<filename>GENERIC</filename> kernel configuration file for that
architecture.</para>
<para>Do not make edits to <filename>GENERIC</filename>. Instead,
copy the file to a different name and make edits to the copy.
The convention is to use a name with all capital letters. When
maintaining multiple &os; machines with different hardware, it
is a good idea to name it after the machine's hostname. This
example creates a copy, named <filename>MYKERNEL</filename>, of the
<filename>GENERIC</filename> configuration file for the
example creates a copy, named <filename>MYKERNEL</filename>, of
the <filename>GENERIC</filename> configuration file for the
<literal>amd64</literal> architecture:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/amd64/conf</userinput>
&prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen>
<para>The configuration file
<filename>MYKERNEL</filename> can now be customized
with any ASCII text editor. The default editor is
<application>vi</application>, though an easier editor
for beginners, called <application>ee</application>, is also
<para>The configuration file <filename>MYKERNEL</filename> can now
be customized with any ASCII text editor. The default editor is
<application>vi</application>, though an easier editor for
beginners, called <application>ee</application>, is also
installed with &os;.</para>
<indexterm>
<primary>kernel</primary>
<secondary>NOTES</secondary>
@ -299,9 +297,10 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
ignored. To remove kernel support for a device or subsystem,
put a <literal>#</literal> at the beginning of the line
representing that device or subsystem. Do not add or remove a
<literal>#</literal> for any line that you do not understand.</para>
<literal>#</literal> for any line that you do not
understand.</para>
<warning>
<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
@ -309,8 +308,8 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
in doubt, just leave support in the kernel.</para>
</warning>
<para>In addition to the brief descriptions provided in this file, additional
descriptions are contained in
<para>In addition to the brief descriptions provided in this file,
additional descriptions are contained in
<filename>NOTES</filename>, which can be found in the same
directory as <filename>GENERIC</filename> for that architecture.
For architecture independent options, refer to
@ -318,7 +317,8 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
<tip>
<para>When finished customizing the kernel configuration file,
save a backup copy to a location outside of <filename>/usr/src</filename>.</para>
save a backup copy to a location outside of
<filename>/usr/src</filename>.</para>
<para>Alternately, keep the kernel configuration file elsewhere
and create a symbolic link to the file:</para>
@ -332,10 +332,10 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
<para>An <literal>include</literal> directive is available for use
in configuration files. This allows another configuration file
to be included in the current one, making it easy to maintain
small changes relative to an existing file. If
only a small number of additional options or drivers are
required, this allows a delta to be maintained with respect
to <filename>GENERIC</filename>, as seen in this example:</para>
small changes relative to an existing file. If only a small
number of additional options or drivers are required, this
allows a delta to be maintained with respect to
<filename>GENERIC</filename>, as seen in this example:</para>
<programlisting>include GENERIC
ident MYKERNEL
@ -346,17 +346,19 @@ options IPFIREWALL_DEFAULT_TO_ACCEPT
options IPDIVERT</programlisting>
<para>Using this method, the local configuration file expresses
local differences from a <filename>GENERIC</filename>
kernel. As upgrades are performed, new features added to
local differences from a <filename>GENERIC</filename> kernel.
As upgrades are performed, new features added to
<filename>GENERIC</filename> will also be added to the local
kernel unless they are specifically prevented using
<literal>nooptions</literal> or <literal>nodevice</literal>.
A comprehensive list of configuration directives and their
<literal>nooptions</literal> or <literal>nodevice</literal>. A
comprehensive list of configuration directives and their
descriptions may be found in &man.config.5;.</para>
<note>
<para>To build a file which contains all available options,
run the following command as <systemitem class="username">root</systemitem>:</para>
run the following command as <systemitem
class="username">root</systemitem>:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>arch</replaceable>/conf &amp;&amp; make LINT</userinput></screen>
</note>
@ -461,9 +463,10 @@ options NFS_ROOT # NFS usable as /, requires NFSCLIENT</progra
<para>The &ms-dos; file system. Unless the system needs to mount
a DOS formatted hard drive partition at boot time, comment this
out. It will be automatically loaded the first time a DOS
partition is mounted. The <package>emulators/mtools</package> package allows
access to DOS floppies without having to mount and unmount
them and does not require <literal>MSDOSFS</literal>.</para>
partition is mounted. The <package>emulators/mtools</package>
package allows access to DOS floppies without having to mount
and unmount them and does not require
<literal>MSDOSFS</literal>.</para>
<programlisting>options CD9660 # ISO 9660 Filesystem</programlisting>
@ -476,24 +479,26 @@ options NFS_ROOT # NFS usable as /, requires NFSCLIENT</progra
<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 some programs
to provide more information on what processes are running. Use
of <literal>PROCFS</literal> is not required under most
circumstances, as most debugging and monitoring tools have been
adapted to run without <literal>PROCFS</literal>. The default
installation will not mount this file system by default.</para>
file system mounted on <filename>/proc</filename> which allows
some programs to provide more information on what processes are
running. Use of <literal>PROCFS</literal> is not required under
most circumstances, as most debugging and monitoring tools have
been adapted to run without <literal>PROCFS</literal>. The
default installation will not mount this file system by
default.</para>
<programlisting>options PSEUDOFS # Pseudo-filesystem framework</programlisting>
<para>Kernels making use of <literal>PROCFS</literal> must
also include support for <literal>PSEUDOFS</literal>.</para>
<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 <link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
Partition Tables</link> (<acronym>GPT</acronym>). GPT
provides the ability to have a large number of partitions per
disk, 128 in the standard configuration.</para>
<para>Adds support for <link
xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
Partition Tables</link> (<acronym>GPT</acronym>). GPT
provides the ability to have a large number of partitions per
disk, 128 in the standard configuration.</para>
<programlisting>options COMPAT_43 # Compatible with BSD 4.3 [KEEP THIS!]</programlisting>
@ -995,7 +1000,8 @@ device loop # Network loopback</programlisting>
<programlisting>device tun # Packet tunnel.</programlisting>
<para>This is used by the userland PPP software. See the <link linkend="userppp">PPP</link> section of the Handbook for more
<para>This is used by the userland PPP software. See the <link
linkend="userppp">PPP</link> section of the Handbook for more
information.</para>
<programlisting><anchor xml:id="kernelconfig-ptys"/>
@ -1076,7 +1082,7 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
&os;, see
<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename>.</para>
-->
<!--
This section refers to ancient hardware.
<sect2>
@ -1166,21 +1172,22 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
information on &os;'s <acronym>PAE</acronym> support.</para>
</sect2>
-->
</sect1>
</sect1>
<sect1 xml:id="kernelconfig-building">
<title>Building and Installing a Custom Kernel</title>
<para>Once the edits to the custom configuration file have been
saved, the source code for the
kernel can be compiled using the following steps:</para>
saved, the source code for the kernel can be compiled using the
following steps:</para>
<procedure>
<title>Building a Kernel</title>
<indexterm>
<primary>kernel</primary>
<secondary>building / installing</secondary>
</indexterm>
<indexterm>
<primary>kernel</primary>
<secondary>building / installing</secondary>
</indexterm>
<step>
<para>Change to this directory:</para>
@ -1197,13 +1204,14 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
<step>
<para>Install the new kernel associated with the specified
kernel configuration file. This command will copy the new kernel to
<filename>/boot/kernel/kernel</filename> and save the old kernel
to <filename>/boot/kernel.old/kernel</filename>:</para>
kernel configuration file. This command will copy the new
kernel to <filename>/boot/kernel/kernel</filename> and save
the old kernel to
<filename>/boot/kernel.old/kernel</filename>:</para>
<screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
</step>
<step>
<para>Shutdown the system and reboot into the new kernel.
If something goes wrong, refer to <xref
@ -1211,46 +1219,46 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
</step>
</procedure>
<para>By default, when a custom kernel is compiled,
all kernel modules are rebuilt.
To update a kernel faster or to build only custom modules,
edit <filename>/etc/make.conf</filename> before starting to
build the kernel.</para>
<para>By default, when a custom kernel is compiled, all kernel
modules are rebuilt. To update a kernel faster or to build
only custom modules, edit <filename>/etc/make.conf</filename>
before starting to build the kernel.</para>
<para>For example, this variable specifies the list of modules to build
instead of using the default of building all modules:</para>
<para>For example, this variable specifies the list of modules to
build instead of using the default of building all
modules:</para>
<programlisting>MODULES_OVERRIDE = linux acpi ntfs</programlisting>
<programlisting>MODULES_OVERRIDE = linux acpi ntfs</programlisting>
<para>Alternately, this variable lists which modules to
exclude from the build process:</para>
<para>Alternately, this variable lists which modules to exclude
from the build process:</para>
<programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting>
<programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting>
<para>Additional variables are available.
Refer to &man.make.conf.5; for details.</para>
<para>Additional variables are available. Refer to
&man.make.conf.5; for details.</para>
<indexterm>
<primary><filename>/boot/kernel.old</filename></primary>
</indexterm>
</sect1>
<sect1 xml:id="kernelconfig-trouble">
<title>If Something Goes Wrong</title>
<sect1 xml:id="kernelconfig-trouble">
<title>If Something Goes Wrong</title>
<para>There are four categories of trouble that can occur when
building a custom kernel:</para>
<para>There are four categories of trouble that can occur when
building a custom kernel:</para>
<variablelist>
<varlistentry>
<term><command>config</command> fails</term>
<variablelist>
<varlistentry>
<term><command>config</command> fails</term>
<listitem>
<para>If <command>config</command> fails, it will print the line
number that is incorrect. As an example, for
the following message, make sure that line 17 is typed correctly by
comparing it to
<filename>GENERIC</filename> or <filename>NOTES</filename>:</para>
<listitem>
<para>If <command>config</command> fails, it will print the
line number that is incorrect. As an example, for the
following message, make sure that line 17 is typed
correctly by comparing it to <filename>GENERIC</filename>
or <filename>NOTES</filename>:</para>
<screen>config: line 17: syntax error</screen>
</listitem>
@ -1261,16 +1269,17 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
<listitem>
<para>If <command>make</command> fails, it is usually due to
an error in the kernel configuration file which is not severe
enough for <command>config</command> to catch. Review the
configuration, and if the problem is not apparent,
send an email to the &a.questions; which contains the
kernel configuration file.</para>
an error in the kernel configuration file which is not
severe enough for <command>config</command> to catch.
Review the configuration, and if the problem is not
apparent, send an email to the &a.questions; which
contains the kernel configuration file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>The kernel does not boot<anchor xml:id="kernelconfig-noboot"/></term>
<term>The kernel does not boot<anchor
xml:id="kernelconfig-noboot"/></term>
<listitem>
<para>If the new kernel does not boot or fails to recognize
@ -1280,9 +1289,8 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
loader. This can be accessed when the system boot menu
appears by selecting the <quote>Escape to a loader
prompt</quote> option. At the prompt, type
<command>boot
kernel.old</command>, or
the name of any other kernel that is known to boot properly.</para>
<command>boot kernel.old</command>, or the name of any
other kernel that is known to boot properly.</para>
<para>After booting with a good kernel, check over the
configuration file and try to build it again. One helpful
@ -1293,19 +1301,17 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
<note>
<para>When troubleshooting a kernel, make sure to keep
a copy of <filename>GENERIC</filename>, or some other kernel that
is known to work, as a different name that will
not get erased on the next build. This is important
because every time
a new kernel is installed, <filename>kernel.old</filename> is
overwritten with the last installed kernel, which may or
may not be bootable. As soon as possible, move the
working kernel by renaming the directory
containing the good kernel:</para>
a copy of <filename>GENERIC</filename>, or some other
kernel that is known to work, as a different name that
will not get erased on the next build. This is
important because every time a new kernel is installed,
<filename>kernel.old</filename> is overwritten with the
last installed kernel, which may or may not be bootable.
As soon as possible, move the working kernel by renaming
the directory containing the good kernel:</para>
<screen>&prompt.root; <userinput>mv /boot/kernel /boot/kernel.bad</userinput>
&prompt.root; <userinput>mv /boot/kernel.good /boot/kernel</userinput></screen>
</note>
</listitem>
</varlistentry>
@ -1316,13 +1322,14 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
<listitem>
<para>If the kernel version differs from the one that the
system utilities have been built with, for example, a
kernel built from -CURRENT sources is installed on a -RELEASE system, many system status commands
like &man.ps.1; and &man.vmstat.8; will not work. To fix
this, <link linkend="makeworld">recompile and install a
world</link> built with the same version of the
source tree as the kernel. It is
never a good idea to use a different version of the kernel
than the rest of the operating system.</para>
kernel built from -CURRENT sources is installed on a
-RELEASE system, many system status commands like
&man.ps.1; and &man.vmstat.8; will not work. To fix this,
<link linkend="makeworld">recompile and install a
world</link> built with the same version of the source
tree as the kernel. It is never a good idea to use a
different version of the kernel than the rest of the
operating system.</para>
</listitem>
</varlistentry>
</variablelist>