svn commit: r40999 - head/en_US.ISO8859-1/books/handbook/kernelconfig
Dru Lavigne
dru at FreeBSD.org
Sun Feb 17 17:41:06 UTC 2013
Author: dru
Date: Sun Feb 17 17:41:05 2013
New Revision: 40999
URL: http://svnweb.freebsd.org/changeset/doc/40999
Log:
Initial content fix. This patch addresses the following:
- fixes you
- fixes xref and directory tags
- general tightening
- csup changed to svn
Approved by: gjb (mentor)
Modified:
head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Sun Feb 17 17:28:26 2013 (r40998)
+++ head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Sun Feb 17 17:41:05 2013 (r40999)
@@ -37,21 +37,19 @@
<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>
+ networking, disk access, and much more. While much of &os; is
+ dynamically configurable, it is still occasionally necessary to
+ configure and compile a custom kernel.</para>
<para>After reading this chapter, you will know:</para>
<itemizedlist>
<listitem>
- <para>Why you might need to build a custom kernel.</para>
+ <para>When to build a custom kernel.</para>
</listitem>
<listitem>
- <para>How to write a kernel configuration file, or alter an
- existing configuration file.</para>
+ <para>How to customize a kernel configuration file.</para>
</listitem>
<listitem>
@@ -68,50 +66,46 @@
</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>
+ <para>All of the commands listed in the examples in this chapter
+ should be executed as <username>root</username>.</para>
</sect1>
<sect1 id="kernelconfig-custom-kernel">
<title>Why Build a Custom Kernel?</title>
- <para>Traditionally, &os; 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>
+ <para>Traditionally, &os; used a <quote>monolithic</quote> kernel.
+ The kernel was one large program, supported a fixed list of
+ devices, and in order to change the kernel's behavior, one had
+ to compile a new kernel, and then reboot into the new
+ kernel.</para>
+
+ <para>Today, most of the functionality in the &os; kernel is
+ contained in modules which can be dynamically loaded and
+ unloaded from the kernel as necessary. This allows the
+ running kernel to adapt immediately to new hardware or for new
+ functionality to be brought into the kernel. This is known as
+ a modular kernel.</para>
+
+ <para>Occasionally, it is still necessary to perform static kernel
+ configuration. This may be because the functionality is so tied
+ to the kernel that it can not be made dynamically loadable.
+ Some security environments prevent the loading and unloading of
+ kernel modules, and require that only needed functionality is
+ statically compiled into the kernel.</para>
+
+ <para>Building a custom kernel is often a rite of passage for
+ advanced BSD users. This process, while time consuming, can
+ provide benefits to the &os; system. Unlike the
+ <filename>GENERIC</filename> kernel, which must support a wide
+ range of hardware, a custom kernel can be stripped down to only
+ provide support for that computer's hardware. This has a number
+ of benefits, such as:</para>
<itemizedlist>
<listitem>
- <para>Faster boot time. Since the kernel will only probe
- the hardware you have on your system, the time it takes
- your system to boot can decrease dramatically.</para>
+ <para>Faster boot time. Since the kernel will only probe the
+ hardware on the system, the time it takes the system to boot
+ can decrease.</para>
</listitem>
<listitem>
@@ -121,15 +115,14 @@
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>
+ kernel is 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>
+ <para>Additional hardware support. A custom kernel can add in
+ support for devices which are not present in the
+ <filename>GENERIC</filename> kernel.</para>
</listitem>
</itemizedlist>
</sect1>
@@ -149,12 +142,10 @@
<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>
+ list can be created by viewing the current operating system
+ configuration. For example, µsoft;'s
+ <application>Device Manager</application> contains information
+ about installed devices.</para>
<note>
<para>Some versions of µsoft.windows; have a
@@ -165,12 +156,11 @@
<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>
+ method is using &man.dmesg.8; and &man.man.1;. Most device
+ drivers on &os; have a manual page, listing supported hardware.
+ During the boot probe, found hardware will be listed. For
+ example, the following lines indicate that the &man.psm.4;
+ driver found a mouse:</para>
<programlisting>psm0: <PS/2 Mouse> irq 12 on atkbdc0
psm0: [GIANT-LOCKED]
@@ -182,12 +172,12 @@ psm0: model Generic PS/2 mouse, device I
<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>
+ these situations, the output may be obtained by reading
+ <filename>/var/run/dmesg.boot</filename>.</para>
- <para>Another method of finding hardware is by using the
- &man.pciconf.8; utility which provides more verbose output.
- For example:</para>
+ <para>Another method for finding hardware is to use
+ &man.pciconf.8; which provides more verbose output. For
+ example:</para>
<programlisting>ath0 at pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00
vendor = 'Atheros Communications Inc.'
@@ -195,22 +185,20 @@ psm0: model Generic PS/2 mouse, device I
class = network
subclass = ethernet</programlisting>
- <para>This bit of output, obtained using
- <command>pciconf <option>-lv</option></command> shows that the
+ <para>This output, obtained by 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>
+ device. Type <command>man
+ <replaceable>ath</replaceable></command> to read
+ &man.ath.4;.</para>
<para>The <option>-k</option> flag, when passed to &man.man.1;
- can also be used to provide useful information. From the
- above, one can issue:</para>
+ can be used to provide useful information. For example, to
+ display a list of manual pages which contain the specified
+ word::</para>
<screen>&prompt.root; man -k <replaceable>Atheros</replaceable></screen>
- <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>
@@ -226,45 +214,37 @@ ath_hal(4) - Atheros Hardw
<secondary>drivers / modules / subsystems</secondary>
</indexterm>
- <para>Before building a custom kernel, consider the reasons for
+ <para>Before building a custom kernel, consider the reason for
doing so. If there is a need for specific hardware support,
it may already exist as a module.</para>
- <para>Kernel modules exist in the
- <filename class="directory">/boot/kernel</filename> directory
- and may be dynamically loaded into the running kernel using
+ <para>Kernel modules exist in <filename
+ class="directory">/boot/kernel</filename> and may be
+ dynamically loaded into the running kernel using
&man.kldload.8;. Most, if not all kernel drivers have a
- 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>
+ loadable module and manual page. For example, the &man.ath.4;
+ wireless Ethernet driver has the following information in its
+ manual page:</para>
<programlisting>Alternatively, to load the driver as a module at boot time, place the
following line in &man.loader.conf.5;:
if_ath_load="YES"</programlisting>
- <para>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>
+ <para>Adding <literal>if_ath_load="YES"</literal> to
+ <filename>/boot/loader.conf</filename> will enable loading this
+ module dynamically at boot time.</para>
+
+ <para>In some cases, there is no associated module. This is
+ mostly true for certain subsystems. One way to tell if a driver
+ is available is to check for the module itself.</para>
<warning>
- <para>It is easy to remove support for a
- device or option and end up with a broken kernel. For
- example, if the &man.ata.4; driver is removed from the kernel
- configuration file, a system using <acronym>ATA</acronym>
- disk drivers may not boot 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>
+ <para>It is easy to remove support for a device or option and
+ end up with a broken kernel. For example, if the &man.ata.4;
+ driver is removed from the kernel configuration file, a system
+ using <acronym>ATA</acronym> disk drivers may not boot. When
+ in doubt, just leave support in the kernel.</para>
</warning>
</sect1>
@@ -281,78 +261,66 @@ following line in &man.loader.conf.5;:
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
+ <para>The kernel build is located at <filename
+ class="directory">/usr/src/sys</filename>. It contains a
+ number of subdirectories representing different parts of the
+ kernel. These include <filename
+ class="directory"><replaceable>arch</replaceable>/conf</filename>,
+ which contains the kernel configuration file, and
+ <filename class="directory">compile</filename>, which is the
+ staging area where the kernel will be built.
+ <replaceable>arch</replaceable> contains subdirectories for each
+ supported architecture: <filename
+ class="directory">i386</filename>, <filename
+ class="directory">amd64</filename>, <filename
+ class="directory">ia64</filename>, <filename
+ class="directory">powerpc</filename>, <filename
+ class="directory">sparc64</filename>, and <filename
+ class="directory">pc98</filename>. Everything inside a
particular architecture's directory deals with that architecture
- only; 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>
+ only and the rest of the code is machine independent code common
+ to all platforms. Notice the logical organization of the
+ directory structure, with each supported device, file system,
+ and option in its own subdirectory.</para>
+
+ <para>The examples in this chapter assume the i386 architecture.
+ If the system has a different architecture, change the path
+ names accordingly.</para>
<note>
- <para>If 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
+ <para>If <filename class="directory">/usr/src/</filename> does
+ not exist or it is empty, source has not been installed. The
+ easiest way to install source is to use
+ <application>svn</application> as described in <link
+ linkend="svn"></link>. One should also create a symlink to
<filename class="directory">/usr/src/sys/</filename>:</para>
<screen>&prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput></screen>
</note>
- <para>Next, 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>
+ <para>Next, <application>cd</application> to <filename
+ class="directory"><replaceable>arch</replaceable>/conf</filename>
+ and copy the <filename>GENERIC</filename> configuration file to
+ the name of the custom kernel. For example:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
&prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen>
- <para>Traditionally, this name is in all capital letters 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>
+ <para>Traditionally, this name is in all capital letters. When
+ maintaining multiple &os; machines with different hardware, it
+ is a good idea to name it after the machine's hostname. This
+ example uses
+ <filename><replaceable>MYKERNEL</replaceable></filename>.</para>
<tip>
- <para>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>When finished customizing the kernel configuration file,
+ save a backup copy to a location outside of <filename
+ class="directory">/usr/src</filename>. Do not edit
+ <filename>GENERIC</filename> directly.</para>
+
+ <para>Alternately, keep the kernel configuration file elsewhere
+ and create a symbolic link to the file in <filename
+ class="directory"><replaceable>i386</replaceable></filename>.</para>
<para>For example:</para>
@@ -362,43 +330,36 @@ following line in &man.loader.conf.5;:
&prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
</tip>
- <para>Now, edit
+ <para>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
+ with a text editor. The default editor is
+ <application>vi</application>, whose usage is covered well in
+ many books in the <link
+ linkend="bibliography">bibliography</link>. An easier editor
+ for beginners, called <application>ee</application>, is also
+ available. Feel free to change the comment lines at the top to
+ reflect the configuration or the changes made to differentiate
it from <filename>GENERIC</filename>.</para>
- <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>
+ <para>If the <filename>GENERIC</filename> configuration file seems
+ overwhelming, follow the descriptions in the <link
+ linkend="kernelconfig-config">Configuration File</link>
section slowly and carefully.</para>
<note>
- <para>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
+ <para>After <link linkend="svn">syncing the source tree</link>
+ with the latest sources, <emphasis>always</emphasis> read
+ <filename class="directory">/usr/src/UPDATING</filename>
+ before performing any update steps. This file describes any
important issues or areas requiring special attention within
the updated source code.
<filename>/usr/src/UPDATING</filename> always matches
- your version of the &os; source, and is therefore more up
- to date with new information than this handbook.</para>
+ the version of the &os; source and contains more up-to-date
+ information than this Handbook.</para>
</note>
- <para>You must now compile the source code for the kernel.</para>
+ <para>After saving the edits, compile the source code for the
+ kernel.</para>
<procedure>
<title>Building a Kernel</title>
@@ -409,14 +370,15 @@ following line in &man.loader.conf.5;:
</note>
<step>
- <para>Change to the <filename
- class="directory">/usr/src</filename> directory:</para>
+ <para><command>cd</command> to <filename
+ class="directory">/usr/src</filename>:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
</step>
<step>
- <para>Compile the kernel:</para>
+ <para>Compile the new kernel by specifying the name of the
+ custom kernel configuration file:</para>
<screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
</step>
@@ -429,52 +391,49 @@ following line in &man.loader.conf.5;:
</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>
+ <para>By default, when a custom kernel is compiled,
+ <emphasis>all</emphasis> kernel modules are rebuilt as well.
+ To update a kernel faster or to build only custom modules,
+ edit <filename>/etc/make.conf</filename> before starting to
+ build the kernel:</para>
<programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting>
- <para>This variable sets up a list of modules to build instead
- of all of them.</para>
+ <para>This variable specifies the list of modules to build
+ instead the default of building of all of them.</para>
<programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting>
<para>This variable sets up a list of top level modules to
- exclude from the build process. For other variables which
- you may find useful in the process of building kernel, refer
- to &man.make.conf.5; manual page.</para>
+ exclude from the build process. For other available
+ variables, refer to &man.make.conf.5;.</para>
</tip>
<indexterm>
- <primary><filename class="directory">/boot/kernel.old</filename></primary>
+ <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
+ <para>The new kernel will be copied to <filename
+ class="directory">/boot/kernel</filename> as
<filename>/boot/kernel/kernel</filename> and the old kernel
will be moved to <filename>/boot/kernel.old/kernel</filename>.
- Now, shutdown the system and reboot to use your new kernel.
- If something goes wrong, there are some <link
+ Now, shutdown the system and reboot into the new kernel.
+ If something goes wrong, refer to the <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
+ instructions and the section which explains how to
+ recover when the new kernel <link
linkend="kernelconfig-noboot">does not boot</link>.</para>
<note>
<para>Other files relating to the boot process, such as the boot
- &man.loader.8; and configuration are stored in
- <filename>/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>
+ &man.loader.8; and configuration, are stored in <filename
+ class="directory">/boot</filename>. Third party or
+ custom modules can be placed in <filename
+ class="directory">/boot/kernel</filename>, although users
+ should be aware that keeping modules in sync with the compiled
+ kernel is very important. Modules not intended to run with
+ the compiled kernel may result in instability.</para>
</note>
</sect1>
@@ -506,22 +465,19 @@ following line in &man.loader.conf.5;:
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
+ For an exhaustive list of architecture dependent options and
+ devices, refer to <filename>NOTES</filename> in the same
+ directory as <filename>GENERIC</filename> for that architecture.
+ For architecture independent options, refer to
<filename>/usr/src/sys/conf/NOTES</filename>.</para>
- <para>An <literal>include</literal> directive is
- available for use in configuration files. This allows another
- configuration file to be 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>
+ <para>An <literal>include</literal> directive is available for use
+ in configuration files. This allows another configuration file
+ to be included in the current one, making it easy to maintain
+ small changes relative to an existing file. For example, if
+ only a small number of additional options or drivers are
+ required, this allows a delta to be maintained with respect
+ to GENERIC:</para>
<programlisting>include GENERIC
ident MYKERNEL
@@ -531,13 +487,11 @@ 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
+ <para>Using this method, the local configuration file expresses
+ local differences from a <filename>GENERIC</filename>
+ kernel. As upgrades are performed, new features added to
+ <filename>GENERIC</filename> will be also be added to the local
+ kernel unless they are specifically prevented using
<literal>nooptions</literal> or <literal>nodevice</literal>.
The remainder of this chapter addresses the contents of a
typical configuration file and the role various options and
@@ -545,8 +499,7 @@ options IPDIVERT</programlisting
<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>
+ 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>
@@ -559,7 +512,7 @@ options IPDIVERT</programlisting
<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
+ example should match the copy in
<filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/GENERIC</filename>
fairly closely.</para>
@@ -571,9 +524,9 @@ options IPDIVERT</programlisting
<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>amd64</literal>, <literal>i386</literal>,
+ <literal>ia64</literal>, <literal>pc98</literal>,
+ <literal>powerpc</literal>, or
<literal>sparc64</literal>.</para>
<indexterm>
@@ -584,14 +537,11 @@ options IPDIVERT</programlisting
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>
+ <para>This option specifies the type of CPU. It is fine to have
+ multiple instances of the CPU entries, but for a custom kernel
+ it is best to specify the CPU. To determine the CPU type,
+ review the boot messages in
+ <filename>/var/run/dmesg.boot</filename>.</para>
<indexterm>
<primary>kernel options</primary>
@@ -600,37 +550,29 @@ cpu I686_CPU</programlisting>
<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>
+ <para>This is the identification of the kernel. Change
+ this to the new kernel name, such as
+ <literal><replaceable>MYKERNEL</replaceable></literal>.
+ The value in the <literal>ident</literal> string will
+ print when the kernel boots.</para>
<programlisting>#To statically compile in device wiring instead of /boot/device.hints
#hints "GENERIC.hints" # Default places to look for devices.</programlisting>
- <para>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>
+ <para>&man.device.hints.5; is used to configure options for device
+ drivers. The default location is
+ <filename>/boot/device.hints</filename>. The
+ <literal>hints</literal> option compiles these hints statically
+ into the kernel so that there is no need to create
+ <filename>/boot/device.hints</filename>.</para>
<!-- XXX: Add a comment here that explains when compiling hints into
the kernel is a good idea and why. -->
<programlisting>makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols</programlisting>
- <para>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>
+ <para>This option enables debugging information when passed to
+ &man.gcc.1;.</para>
<programlisting>options SCHED_ULE # ULE scheduler</programlisting>
@@ -638,17 +580,14 @@ cpu I686_CPU</programlisting>
<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>
+ <para>Allows kernel threads to be preempted by higher priority
+ threads. This helps with interactivity and allows interrupt
+ threads to run sooner rather than waiting.</para>
<programlisting>options INET # InterNETworking</programlisting>
- <para>Networking support. 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>
+ <para>Networking support. This is mandatory as most programs
+ require at least loopback networking.</para>
<programlisting>options INET6 # IPv6 communications protocols</programlisting>
@@ -657,40 +596,38 @@ cpu I686_CPU</programlisting>
<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>
+ the system boots from the hard disk.</para>
<programlisting>options SOFTUPDATES # Enable FFS Soft Updates support</programlisting>
- <para>This option enables Soft Updates in the kernel, this will
- help speed up write access on the disks. Even when this
+ <para>This option enables Soft Updates in the kernel which helps
+ to speed up write access on the disks. Even when this
functionality is provided by the kernel, it must be turned on
- for specific disks. Review the output 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>
+ for specific disks. Review the output so &man.mount.8; to
+ determine if Soft Updates is enabled. If the
+ <literal>soft-updates</literal> option is not in the output, it
+ can be activated using &man.tunefs.8; for existing file systems
+ or &man.newfs.8; for new file systems.</para>
<programlisting>options UFS_ACL # Support for access control lists</programlisting>
- <para>This option enables kernel support
- for access control lists. This relies on the use of extended
+ <para>This option enables kernel support for access control lists
+ (<acronym>ACL</acronym>s). This relies on the use of extended
attributes and <acronym>UFS2</acronym>, and the feature is
- described in detail in <xref linkend="fs-acl"/>.
- <acronym>ACL</acronym>s are enabled by default and should not
- be disabled in the kernel if they have been used previously
- on a file system, as this will remove the access control lists,
- changing the way files are protected in unpredictable
- ways.</para>
+ described in detail in <link linkend="fs-acl"></link>.
+ <acronym>ACL</acronym>s are enabled by default and should not be
+ disabled in the kernel if they have been used previously on a
+ file system, as this will remove the ACLs, changing the way
+ files are protected in unpredictable ways.</para>
<programlisting>options UFS_DIRHASH # Improve performance on big directories</programlisting>
<para>This option includes functionality to speed up disk
operations on large directories, at the expense of using
- additional memory. 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>
+ additional memory. Keep this for a large server or interactive
+ workstation, and remove it from smaller systems where memory is
+ at a premium and disk access speed is less important, such as a
+ firewall.</para>
<programlisting>options MD_ROOT # MD is a potential root device</programlisting>
@@ -709,9 +646,10 @@ cpu I686_CPU</programlisting>
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>
+ <para>The network file system (<acronym>NFS</acronym>). These
+ lines can be commented unless the system needs to mount
+ partitions from a <acronym>NFS</acronym> file server over
+ TCP/IP.</para>
<indexterm>
<primary>kernel options</primary>
@@ -719,34 +657,32 @@ options NFS_ROOT # NFS
</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>
+ <para>The &ms-dos; file system. Unless the system needs to mount
+ a DOS formatted hard drive partition at boot time, comment this
+ out. It will be automatically loaded the first time a DOS
+ partition is mounted. The <filename
+ role="package">emulators/mtools</filename> package allows
+ access to DOS floppies without having to mount and unmount
+ them and does not require <literal>MSDOSFS</literal>.</para>
<programlisting>options CD9660 # ISO 9660 Filesystem</programlisting>
- <para>The ISO 9660 file system for CDROMs. Comment it out if
- 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
+ <para>The ISO 9660 file system for CDROMs. Comment it out if the
+ system does not have a CDROM drive or only mounts data CDs
+ occasionally since it will be dynamically loaded the first
+ time a data CD is mounted. Audio CDs do not need this file
system.</para>
<programlisting>options PROCFS # Process filesystem (requires PSEUDOFS)</programlisting>
<para>The process file system. This is a <quote>pretend</quote>
- file system mounted on <filename>/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>
+ file system mounted on <filename
+ class="directory">/proc</filename> which allows some programs
+ to provide more information on what processes are running. Use
+ of <literal>PROCFS</literal> is not required under most
+ circumstances, as most debugging and monitoring tools have been
+ adapted to run without <literal>PROCFS</literal>. The default
+ installation will not mount this file system by default.</para>
<programlisting>options PSEUDOFS # Pseudo-filesystem framework</programlisting>
@@ -757,51 +693,49 @@ options NFS_ROOT # NFS
<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>
+ Partition Tables</ulink> (<acronym>GPT</acronym>. GPT
+ provides the ability to have a large number of partitions per
+ disk, 128 in the standard configuration.</para>
<programlisting>options COMPAT_43 # Compatible with BSD 4.3 [KEEP THIS!]</programlisting>
- <para>Compatibility with 4.3BSD. Leave this in; some programs
- will act strangely if you comment this out.</para>
+ <para>Compatibility with 4.3BSD. Leave this in as some programs
+ will act strangely if this is commented out.</para>
<programlisting>options COMPAT_FREEBSD4 # Compatible with &os;4</programlisting>
- <para>This option is required
- to support applications compiled on older versions of &os;
- that use older system call interfaces. It is recommended that
- this option be used on all &i386; systems that may
- run older applications; platforms that gained support only in
- 5.X, such as ia64 and &sparc64;, do not require this
- option.</para>
+ <para>This option is required to support applications compiled on
+ older versions of &os; that use older system call interfaces.
+ It is recommended that this option be used on all &i386; systems
+ that may run older applications. Platforms that gained support
+ after &os; 4.X, such as ia64 and &sparc64;, do not require
+ this option.</para>
<programlisting>options COMPAT_FREEBSD5 # Compatible with &os;5</programlisting>
- <para>This option is required to
- support applications compiled on &os; 5.X versions that
- use &os; 5.X system call interfaces.</para>
+ <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>
+ <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>
+ <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>
+ each SCSI device in the system. If the system only has IDE hard
+ drives, ignore this or lower the number to speed up booting.
+ However, if &os; has trouble recognizing the SCSI devices, the
+ number will have to be raised again.</para>
<programlisting>options KTRACE # ktrace(1) support</programlisting>
@@ -810,11 +744,11 @@ options NFS_ROOT # NFS
<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>
+ <para>This option provides for System V shared memory. The
+ most common use of this is the XSHM extension in X, which many
+ graphics-intensive programs will automatically take advantage of
+ for extra speed. If <application>Xorg</application> is
+ installed, include this.</para>
<programlisting>options SYSVMSG # SYSV-style message queues</programlisting>
@@ -823,47 +757,44 @@ options NFS_ROOT # NFS
<programlisting>options SYSVSEM # SYSV-style semaphores</programlisting>
- <para>Support for System V semaphores. Less commonly used
+ <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>
+ <para>Using <option>-p</option> with &man.ipcs.1; will list any
+ processes using each of these System V facilities.</para>
</note>
<programlisting>options _KPOSIX_PRIORITY_SCHEDULING # POSIX P1003_1B real-time extensions</programlisting>
<para>Real-time extensions added in the 1993 &posix;. Certain
- applications in the Ports Collection use these
- (such as <application>&staroffice;</application>).</para>
+ applications in the Ports Collection use these.</para>
<programlisting>options KBD_INSTALL_CDEV # install a CDEV entry in /dev</programlisting>
<para>This option is required to allow the creation of keyboard
- device nodes in <filename>/dev</filename>.</para>
+ device nodes in <filename
+ class="directory">/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.
+ <para>Giant is the name of a mutual exclusion mechanism, a
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list