[deployment-guide/comm-rel: 659/727] Re-indexed the chapter.
Jaromir Hradilek
jhradile at fedoraproject.org
Tue Oct 19 13:21:06 UTC 2010
commit e18021091ab18e841f9f028ead8912dc60e85a8a
Author: Jaromir Hradilek <jhradile at redhat.com>
Date: Wed Sep 15 13:56:39 2010 +0200
Re-indexed the chapter.
en-US/Working_with_Kernel_Modules.xml | 279 ++++++++++++++++-----------------
1 files changed, 132 insertions(+), 147 deletions(-)
---
diff --git a/en-US/Working_with_Kernel_Modules.xml b/en-US/Working_with_Kernel_Modules.xml
index ea2783b..d2765fc 100644
--- a/en-US/Working_with_Kernel_Modules.xml
+++ b/en-US/Working_with_Kernel_Modules.xml
@@ -4,52 +4,31 @@
<chapter
id="ch-Working_with_Kernel_Modules">
<title>Working with Kernel Modules</title>
- <indexterm
- significance="normal">
+ <indexterm>
<primary>kernel module</primary>
- <secondary>introducing</secondary>
+ <secondary>definition</secondary>
</indexterm>
- <indexterm
- significance="normal">
- <primary>module</primary>
- <see>kernel module</see>
- </indexterm>
- <indexterm
- significance="normal">
- <primary>drivers</primary>
+ <para>Linux <firstterm>loadable kernel modules</firstterm> are so-called because they are able to be dynamically loaded into a running kernel to extend its capabilities, and dynamically also removed from it, using user-space commands. Device drivers are one type of kernel module, but not the only type. Like the kernel itself, kernel modules can take custom parameters to define their behavior. Kernel modules have default parameters which work in most, but not all cases.</para>
+ <indexterm>
+ <primary>driver</primary>
<see>kernel module</see>
</indexterm>
- <indexterm
- significance="normal">
- <primary>kernel module</primary>
- <secondary>types of</secondary>
- </indexterm>
- <para>Linux <firstterm>loadable kernel modules</firstterm> are so-called because they are able to be dynamically loaded into a running kernel to extend its capabilities, and dynamically also removed from it, using user-space commands. Device drivers are one type of kernel module, but not the only type. Like the kernel itself, kernel modules can take custom parameters to define their behavior. Kernel modules have default parameters which work in most, but not all cases.</para>
- <para>This chapter is provided to illustrate <emphasis>some</emphasis> of the possible parameters available for common hardware device <firstterm>drivers</firstterm>
+ <para>This chapter is provided to illustrate <emphasis>some</emphasis> of the possible parameters available for common hardware device <firstterm>drivers</firstterm>,
<footnote>
<para>A <firstterm>driver</firstterm> is software that enables Linux to use a particular hardware device. Without a driver, the kernel cannot communicate with attached devices.</para>
- </footnote>, which under &MAJOROS; are called <firstterm>kernel module</firstterm>s . In most cases, the default parameters do work. However, there may be times when extra module parameters are necessary for a device to function properly or to override the module's default parameters for the device.</para>
+ </footnote> which under &MAJOROS; are called <firstterm>kernel module</firstterm>s . In most cases, the default parameters do work. However, there may be times when extra module parameters are necessary for a device to function properly or to override the module's default parameters for the device.</para>
<para>During installation, &MAJOROS; uses a limited subset of device drivers to create a stable installation environment. Although the installation program supports installation on many different types of hardware, some drivers (including those for SCSI adapters and network adapters) are not included in the installation kernel. Rather, they must be loaded as modules by the user at boot time.</para>
<para>Once installation is completed, support exists for a large number of devices through kernel modules.</para>
<section
id="s1-kernel-module-utils">
<title>Kernel Module Utilities</title>
- <indexterm>
- <primary>kernel module</primary>
- <secondary>utilities</secondary>
- </indexterm>
- <indexterm>
- <primary>kernel module</primary>
- <secondary>commands</secondary>
- <tertiary>group of</tertiary>
- </indexterm>
- <indexterm>
- <primary>kernel module</primary>
- <secondary>module-init-tools</secondary>
- </indexterm>
<para>To determine if a module has been loaded successfully, or when trying different modules for a piece of new hardware, you can use the following utilities.</para>
<note>
<title>Note: Installing the module-init-tools package</title>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>system requirements</secondary>
+ </indexterm>
<para>In order to use the kernel module utilities, first ensure the <package>module-init-tools</package> package is installed on your system by running, as root:</para>
<screen>~]# <command>yum install module-init-tools</command>
</screen>
@@ -59,16 +38,19 @@
<section
id="sec-Listing_Currently-Loaded_Modules">
<title>Listing Currently-Loaded Modules</title>
- <indexterm
- significance="normal">
- <primary>
- <command>lsmod</command>
- </primary>
- </indexterm>
- <indexterm
- significance="normal">
+ <indexterm>
<primary>kernel module</primary>
<secondary>listing</secondary>
+ <tertiary>loaded modules</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>utilities</secondary>
+ <tertiary><command>lsmod</command></tertiary>
+ </indexterm>
+ <indexterm>
+ <primary><command>lsmod</command></primary>
+ <seealso>kernel module</seealso>
</indexterm>
<para>To display the list of currently loaded modules, use the <command>lsmod</command> command:</para>
<example
@@ -112,6 +94,11 @@ kvm 253162 1 kvm_intel
<lineannotation>[output truncated]</lineannotation>
</screen>
</example>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>files</secondary>
+ <tertiary><filename>/proc/modules</filename></tertiary>
+ </indexterm>
<para>Each row of <command>lsmod</command> output specifies the name of a kernel module loaded in memory, the amount of memory it uses, the number of other modules which depend on it (its <firstterm>use count</firstterm>), and finally a list of those modules which depend on it.<footnote
id="footnote-Dependency_List_Length"><para>If a module has a large number of dependencies, then <command>modprobe</command> may truncate or even omit the names of those modules in the <computeroutput>Used by</computeroutput> column of its output. This is the case in <xref
linkend="ex-Using_lsmod_to_display_the_list_of_currently-loaded_kernel_modules"/>, where the <systemitem
@@ -122,16 +109,19 @@ kvm 253162 1 kvm_intel
<section
id="sec-Displaying_Information_About_a_Module">
<title>Displaying Information About a Module</title>
- <indexterm
- significance="normal">
- <primary>
- <command>modinfo</command>
- </primary>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>listing</secondary>
+ <tertiary>module information</tertiary>
</indexterm>
- <indexterm
- significance="normal">
+ <indexterm>
<primary>kernel module</primary>
- <secondary>examining</secondary>
+ <secondary>utilities</secondary>
+ <tertiary><command>modinfo</command></tertiary>
+ </indexterm>
+ <indexterm>
+ <primary><command>modinfo</command></primary>
+ <seealso>kernel module</seealso>
</indexterm>
<para>To display detailed information about a kernel module, run the <command>modinfo <replaceable><module_name></replaceable>
</command> command.</para>
@@ -176,22 +166,30 @@ debug:Debug level (0=none,...,16=all)</screen>
<section
id="s2-kernel-module-utils-modprobe">
<title>Loading a Module</title>
- <indexterm
- significance="normal">
- <primary>
- <command>modprobe</command>
- </primary>
- </indexterm>
- <indexterm
- significance="normal">
+ <indexterm>
<primary>kernel module</primary>
<secondary>loading</secondary>
+ <tertiary>for the current session</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>utilities</secondary>
+ <tertiary><command>modprobe</command></tertiary>
+ </indexterm>
+ <indexterm>
+ <primary><command>modprobe</command></primary>
+ <seealso>kernel module</seealso>
</indexterm>
<para>To load a kernel module, run <command>modprobe <replaceable><module_name></replaceable>
</command> as root. For example, to load the <systemitem
class="resource">wacom</systemitem> module, run:</para>
<screen>~]# <command>modprobe wacom</command>
</screen>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>directories</secondary>
+ <tertiary><filename class="directory">/lib/modules/<replaceable><kernel_version></replaceable>/kernel/drivers/</filename></tertiary>
+ </indexterm>
<para>By default, <command>modprobe</command> attempts to load the module from <filename
class="directory">/lib/modules/<replaceable><kernel_version></replaceable>/kernel/drivers/</filename>. In this directory, each type of module has its own subdirectory, such as <filename
class="directory">net/</filename> for network interface drivers, and <filename
@@ -204,31 +202,25 @@ insmod /lib/modules/2.6.32-54.el6.i686/kernel/drivers/net/e100.ko</screen>
<para>This output indicates that <command>modprobe</command> loaded the <systemitem
class="resource">mii</systemitem> module (using the <command>insmod</command> command) as a dependency before loading <systemitem
class="resource">e100</systemitem>.</para>
- <indexterm
- significance="normal">
- <primary>
- <command>insmod</command>
- </primary>
- </indexterm>
<important
id="important-Do_not_use_insmod_directly">
<title>Do not use insmod directly!</title>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>utilities</secondary>
+ <tertiary><command>insmod</command></tertiary>
+ </indexterm>
+ <indexterm>
+ <primary><command>insmod</command></primary>
+ <seealso>kernel module</seealso>
+ </indexterm>
<para>Although the <command>insmod</command> command can also be used to load kernel modules, it does not resolve dependencies. Because of this, you should <emphasis>always</emphasis> load modules using <command>modprobe</command> instead.</para>
</important>
<indexterm>
<primary>kernel module</primary>
- <secondary>module parameters</secondary>
+ <secondary>parameters</secondary>
<tertiary>specifying</tertiary>
</indexterm>
- <indexterm>
- <primary>module parameters</primary>
- <see>kernel module</see>
- </indexterm>
- <indexterm>
- <primary>kernel module</primary>
- <secondary>module parameters</secondary>
- <tertiary>supplying</tertiary>
- </indexterm>
<para>You may want to customize the behavior of a certain module, which you can do by supplying it with additional parameters. The format for doing so is:</para>
<example
id="ex-Supplying_optional_parameters_when_loading_a_kernel_module">
@@ -245,17 +237,19 @@ insmod /lib/modules/2.6.32-54.el6.i686/kernel/drivers/net/e100.ko</screen>
<section
id="s2-kernel-module-utils-rmmod">
<title>Unloading a Module</title>
- <indexterm
- significance="normal">
- <primary>
- <command>modprobe</command>
- </primary>
- </indexterm>
- <indexterm
- significance="normal">
+ <indexterm>
<primary>kernel module</primary>
<secondary>unloading</secondary>
</indexterm>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>utilities</secondary>
+ <tertiary><command>modprobe</command></tertiary>
+ </indexterm>
+ <indexterm>
+ <primary><command>modprobe</command></primary>
+ <seealso>kernel module</seealso>
+ </indexterm>
<para>To unload a kernel module, run <command>modprobe -r <replaceable><module_name></replaceable>
</command> as root. For example, to unload the <systemitem
class="resource">wacom</systemitem> module, run:</para>
@@ -266,15 +260,18 @@ insmod /lib/modules/2.6.32-54.el6.i686/kernel/drivers/net/e100.ko</screen>
<screen>~]# <command>modprobe -v -r e100</command>
rmmod /lib/modules/2.6.32-54.el6.i686/kernel/drivers/net/e100.ko
rmmod /lib/modules/2.6.32-54.el6.i686/kernel/drivers/net/mii.ko</screen>
- <indexterm
- significance="normal">
- <primary>
- <command>rmmod</command>
- </primary>
- </indexterm>
<important
id="important-Do_not_use_rmmod_directly">
<title>Do not use rmmod directly!</title>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>utilities</secondary>
+ <tertiary><command>rmmod</command></tertiary>
+ </indexterm>
+ <indexterm>
+ <primary><command>rmmod</command></primary>
+ <seealso>kernel module</seealso>
+ </indexterm>
<para>Although the <command>rmmod</command> command can be used to unload kernel modules, it is recommended to use <command>modprobe -r</command> instead.</para>
</important>
</section>
@@ -283,11 +280,13 @@ rmmod /lib/modules/2.6.32-54.el6.i686/kernel/drivers/net/mii.ko</screen>
<title>Persistent Module Loading</title>
<indexterm>
<primary>kernel module</primary>
- <secondary>persistent loading</secondary>
+ <secondary>loading</secondary>
+ <tertiary>at the boot time</tertiary>
</indexterm>
<indexterm>
<primary>kernel module</primary>
- <secondary>/etc/sysconfig/modules/</secondary>
+ <secondary>directories</secondary>
+ <tertiary><filename class="directory">/etc/sysconfig/modules/</filename></tertiary>
</indexterm>
<para>As shown in <xref
linkend="ex-Using_lsmod_to_display_the_list_of_currently-loaded_kernel_modules"/>, many kernel modules are loaded automatically at boot time. You can specify additional modules to be loaded by creating a new <filename><replaceable><file_name></replaceable>.modules</filename> file in the <filename
@@ -329,13 +328,13 @@ fi</programlisting>
id="s2-modules-scsi">
<title>Storage Parameters</title>
<indexterm>
- <primary>SCSI module</primary>
- <see>kernel module</see>
+ <primary>kernel module</primary>
+ <secondary>parameters</secondary>
+ <tertiary>storage module parameters</tertiary>
</indexterm>
<indexterm>
<primary>kernel module</primary>
- <secondary>SCSImodule</secondary>
- <tertiary>parameters</tertiary>
+ <secondary>storage module</secondary>
</indexterm>
<table
id="tb-modules-scsiparameters">
@@ -606,20 +605,22 @@ fi</programlisting>
id="s2-modules-ethernet">
<title>Ethernet Parameters</title>
<indexterm>
- <primary>Ethernet module</primary>
- <see>kernel module</see>
+ <primary>kernel module</primary>
+ <secondary>parameters</secondary>
+ <tertiary>ethernet module parameters</tertiary>
</indexterm>
<indexterm>
<primary>kernel module</primary>
<secondary>Ethernet module</secondary>
+ <tertiary>parameters</tertiary>
</indexterm>
<indexterm>
- <primary>NIC module</primary>
- <secondary>kernel module</secondary>
+ <primary><command>ethtool</command></primary>
+ <seealso>kernel module</seealso>
</indexterm>
<indexterm>
- <primary>kernel module</primary>
- <secondary>NIC module</secondary>
+ <primary><command>mii-tool</command></primary>
+ <seealso>kernel module</seealso>
</indexterm>
<para>The preferred way to configure most modern Ethernet-based network interface cards (NICs) is to use <command>ethtool</command> or <command>mii-tool</command>. Only after these tools fail to work should module parameters be adjusted. Refer to manual pages for <command>ethtool</command> and <command>mii-tool</command> for more information on their usage.</para>
<table
@@ -1022,8 +1023,9 @@ fi</programlisting>
<tertiary>supporting multiple cards</tertiary>
</indexterm>
<indexterm>
- <primary>Ethernet module</primary>
- <see>kernel module</see>
+ <primary>kernel module</primary>
+ <secondary>directories</secondary>
+ <tertiary><filename class="directory">/etc/modprobe.d/</filename></tertiary>
</indexterm>
<para>It is possible to use multiple Ethernet cards on a single machine. For each card there must be an <command>alias</command> and, possibly, <command>options</command> lines for each card in a user-created <filename><replaceable><module_name></replaceable>.conf</filename> file in the <filename>/etc/modprobe.d/</filename> directory.</para>
<para>For additional information about using multiple Ethernet cards, refer to the <citetitle>Linux Ethernet-HOWTO</citetitle> online at <ulink
@@ -1034,30 +1036,17 @@ fi</programlisting>
<title>The Channel Bonding Module</title>
<indexterm>
<primary>channel bonding</primary>
- <secondary>bonding options</secondary>
+ <secondary>description</secondary>
</indexterm>
<indexterm>
- <primary>kernel module</primary>
- <secondary>channel bonding</secondary>
+ <primary>bonding</primary>
+ <see>channel bonding</see>
+ </indexterm>
+ <para>&MAJOROS; allows administrators to bind NICs together into a single channel using the <filename>bonding</filename> kernel module and a special network interface, called a <firstterm>channel bonding interface</firstterm>. Channel bonding enables two or more network interfaces to act as one, simultaneously increasing the bandwidth and providing redundancy.</para>
+ <indexterm>
+ <primary>channel bonding</primary>
+ <secondary>configuration</secondary>
</indexterm>
- <para>&MAJOROS; allows administrators to bind NICs
- <indexterm><primary>NIC</primary>
- <secondary>binding into single channel</secondary>
- </indexterm>
- together into a single channel using the <filename>bonding</filename> kernel module
- <indexterm><primary>kernel module</primary>
- <secondary>bonding kernel module</secondary>
- </indexterm>
- and a special network interface, called a <firstterm>channel bonding interface</firstterm>
- <indexterm>
- <primary>kernel module</primary>
- <secondary>channel bonding interface</secondary>
- </indexterm>
- <indexterm>
- <primary>channel bonding interface</primary>
- <see>kernel module</see>
- </indexterm>
- . Channel bonding enables two or more network interfaces to act as one, simultaneously increasing the bandwidth and providing redundancy.</para>
<para>To channel bond multiple network interfaces, the administrator must perform the following steps:</para>
<orderedlist
continuation="restarts"
@@ -1080,34 +1069,22 @@ fi</programlisting>
id="s3-modules-bonding-directives">
<title>Bonding Module Directives</title>
<indexterm>
- <primary>channel bonding</primary>
- <secondary>bonding directives</secondary>
- </indexterm>
- <indexterm>
<primary>kernel module</primary>
- <secondary>bonding kernel module</secondary>
- <tertiary>bonding directives</tertiary>
+ <secondary>parameters</secondary>
+ <tertiary>bonding module parameters</tertiary>
</indexterm>
- <para>It is a good idea to test which channel bonding module parameters work best for your bonded interfaces before adding them to the <parameter
- class="option">BONDING_OPTS="<replaceable><bonding parameters></replaceable>"</parameter> directive in your bonding interface configuration file (<filename>ifcfg-bond0</filename> for example). Parameters to bonded interfaces can be configured
- <indexterm><primary>channel bonding</primary>
- <secondary>parameters to bonded interfaces</secondary>
- </indexterm>
- <indexterm>
- <primary>kernel module</primary>
- <secondary>bonding kernel module</secondary>
- <tertiary>parameters to bonded interfaces</tertiary>
- </indexterm>
- without unloading (and reloading) the bonding module by manipulating files in the <systemitem
- class="filesystem">sysfs</systemitem> file system.</para>
<indexterm>
- <primary>bonding kernel module</primary>
- <secondary>sysfs</secondary>
+ <primary>kernel module</primary>
+ <secondary>bonding module</secondary>
+ <see>channel bonding</see>
</indexterm>
<indexterm>
- <primary>kernel bonding</primary>
- <secondary>sysfs</secondary>
+ <primary>channel bonding</primary>
+ <secondary>parameters</secondary>
</indexterm>
+ <para>It is a good idea to test which channel bonding module parameters work best for your bonded interfaces before adding them to the <parameter
+ class="option">BONDING_OPTS="<replaceable><bonding parameters></replaceable>"</parameter> directive in your bonding interface configuration file (<filename>ifcfg-bond0</filename> for example). Parameters to bonded interfaces can be configured without unloading (and reloading) the bonding module by manipulating files in the <systemitem
+ class="filesystem">sysfs</systemitem> file system.</para>
<para>
<systemitem
class="filesystem">sysfs</systemitem> is a virtual file system that represents kernel objects as directories, files and symbolic links. <systemitem
@@ -1117,9 +1094,7 @@ fi</programlisting>
class="option">SLAVE=yes</parameter> and <parameter
class="option">MASTER=bond0</parameter> directives in the bonded interfaces following the instructions in <xref
linkend="s2-networkscripts-interfaces-chan"/>, you can proceed to testing and determining the best parameters for your bonded interface.</para>
- <para>First, bring up the bond you created by running <command>ifconfig <option>bond<replaceable><N></replaceable>
- </option> <option>up</option>
- </command> as root:</para>
+ <para>First, bring up the bond you created by running <command>ifconfig <option>bond<replaceable><N></replaceable></option> <option>up</option></command> as root:</para>
<screen>~]# <command>ifconfig bond0 up</command>
</screen>
<para>If you have correctly created the <filename>ifcfg-bond0</filename> bonding interface file, you will be able to see <computeroutput>bond0</computeroutput> listed in the output of running <command>ifconfig</command> (without any options):</para>
@@ -1438,7 +1413,7 @@ bond0</screen>
( <replaceable><source_MAC></replaceable> XOR <replaceable><destination_MAC></replaceable> ))
MODULO <replaceable><slave_count></replaceable>
</screen>
- <para>This algorithm will place all traffic to a particular network peer on the same slave. For non-IP traffic, the formula is the same as for the layer2 transmit hash policy.</para>
+ <para>This algorithm will place all traffic to a particular network peer on the same slave. For non-IP traffic, the formula is the same as for the layer2 transmit hash policy.</para>
<para>This policy is intended to provide a more balanced distribution of traffic than layer2 alone, especially in environments where a layer3 gateway device is required to reach most destinations.</para>
<para>This algorithm is 802.3ad compliant.</para>
</listitem>
@@ -1456,6 +1431,11 @@ bond0</screen>
<section
id="s2-kernel-modules-additional-resource-installed">
<title>Installed Documentation</title>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>additional resources</secondary>
+ <tertiary>installed documentation</tertiary>
+ </indexterm>
<variablelist>
<varlistentry>
<term>
@@ -1524,6 +1504,11 @@ bond0</screen>
<section
id="s2-kernel-modules-additional-resource-online">
<title>Useful Websites</title>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>additional resources</secondary>
+ <tertiary>useful websites</tertiary>
+ </indexterm>
<variablelist>
<varlistentry>
<term>
More information about the docs-commits
mailing list