[deployment-guide/comm-rel: 667/727] Merge branch 'master' of git+ssh://git.engineering.redhat.com/srv/git/users/dhensley/Deployment_Guid
Jaromir Hradilek
jhradile at fedoraproject.org
Tue Oct 19 13:21:50 UTC 2010
commit 0ca1c38d3cc764917fc372f4dc2c09b74bcf56fe
Merge: b019fb6... 97197aa...
Author: Douglas Silas <dhensley at redhat.com>
Date: Thu Sep 16 13:21:42 2010 +0200
Merge branch 'master' of git+ssh://git.engineering.redhat.com/srv/git/users/dhensley/Deployment_Guide
Conflicts:
en-US/Working_with_Kernel_Modules.xml
en-US/Authentication_Configuration.xml | 3 +-
en-US/Email.xml | 4 +-
en-US/FTP.xml | 16 +-
en-US/Gathering_System_Information.xml | 10 +-
en-US/Log_Files.xml | 359 +++++++++---
en-US/The_Apache_HTTP_Server.xml | 802 +++++++++++--------------
en-US/Working_with_Kernel_Modules.xml | 29 +-
en-US/images/apache-mod_ssl-genkey-01.png | Bin 0 -> 139602 bytes
en-US/images/apache-mod_ssl-genkey-02.png | Bin 0 -> 145185 bytes
en-US/images/apache-mod_ssl-genkey-03.png | Bin 0 -> 91440 bytes
en-US/images/apache-mod_ssl-genkey-04.png | Bin 0 -> 147106 bytes
en-US/images/apache-mod_ssl-genkey-05.png | Bin 0 -> 137555 bytes
en-US/images/apache-mod_ssl-genkey-06.png | Bin 0 -> 148690 bytes
en-US/images/apache-mod_ssl-genkey-07.png | Bin 0 -> 144241 bytes
en-US/images/genkey1.png | Bin 9587 -> 0 bytes
en-US/images/genkey10.png | Bin 16485 -> 0 bytes
en-US/images/genkey11.png | Bin 7436 -> 0 bytes
en-US/images/genkey2.png | Bin 10374 -> 0 bytes
en-US/images/genkey3.png | Bin 18324 -> 0 bytes
en-US/images/genkey4.png | Bin 6604 -> 0 bytes
en-US/images/genkey5.png | Bin 9053 -> 0 bytes
en-US/images/genkey6.png | Bin 12479 -> 0 bytes
en-US/images/genkey7.png | Bin 17567 -> 0 bytes
en-US/images/genkey8.png | Bin 10794 -> 0 bytes
en-US/images/genkey9.png | Bin 11766 -> 0 bytes
en-US/images/redhat-filter-enable.png | Bin 0 -> 194249 bytes
en-US/images/redhat-filter-sample.png | Bin 0 -> 16132 bytes
en-US/images/redhat-filters.png | Bin 0 -> 9495 bytes
en-US/images/redhat-logviewer-add.png | Bin 13899 -> 147036 bytes
en-US/images/redhat-logviewer-monitoring.png | Bin 0 -> 159116 bytes
en-US/images/redhat-logviewer-monitoring1.png | Bin 20495 -> 0 bytes
en-US/images/redhat-logviewer-monitoring2.png | Bin 27489 -> 0 bytes
en-US/images/redhat-logviewer-monitoring3.png | Bin 26805 -> 0 bytes
en-US/images/redhat-logviewer-prefs.png | Bin 27983 -> 0 bytes
en-US/images/redhat-logviewer-sample.png | Bin 21035 -> 0 bytes
en-US/images/redhat-logviewer.png | Bin 26264 -> 166037 bytes
36 files changed, 664 insertions(+), 559 deletions(-)
---
diff --cc en-US/Working_with_Kernel_Modules.xml
index 9b72cd6,179a3ca..35c6b1d
--- a/en-US/Working_with_Kernel_Modules.xml
+++ b/en-US/Working_with_Kernel_Modules.xml
@@@ -6,83 -6,57 +6,84 @@@
<title>Working with Kernel Modules</title>
<indexterm>
<primary>kernel module</primary>
- <secondary>introducing</secondary>
+ <secondary>definition</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>
<indexterm>
- <primary>driver</primary>
+ <primary>module</primary>
<see>kernel module</see>
</indexterm>
- <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>
- <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>
+ <indexterm>
+ <primary>drivers</primary>
+ <see>kernel module</see>
+ </indexterm>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>types of</secondary>
+ </indexterm>
+ <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>The Linux kernel is modular, which means it can extend its capabilities through the use of dynamically loaded <firstterm>kernel modules</firstterm>. Kernel modules can provide:</para>
+ <itemizedlist>
+ <listitem>
+ <para>device drivers which add support for new hardware;</para>
+ </listitem>
+ <listitem>
+ <para>file systems such as <systemitem
+ class="filesystem">ext4</systemitem> and <systemitem
+ class="filesystem">NFS</systemitem>; or,</para>
+ </listitem>
+ <listitem>
+ <para>new system calls.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Like the kernel itself, modules can take parameters that customize their behavior, though the default parameters work well in most cases. User-space tools can list the modules currently loaded into a running kernel; query all available modules for available parameters and module-specific information; and load or unload (remove) modules dynamically into or from a running kernel. Many of these utilities, which are provided by the <package>module-init-tools</package> package, take module dependencies into account when performing operations so that manual dependency-tracking is rarely necessary.</para>
+ <para>On modern systems, kernel modules are automatically loaded by various mechanisms when the conditions call for it. However, there are occasions when it is necessary to load and/or unload modules manually, such as when a module provides optional functionality, one module should be preferred over another though either could provide basic functionality, or when a module is misbehaving, among other situations.</para>
+ <para>This chapter explains how to:</para>
+ <itemizedlist>
+ <listitem>
+ <para>use the user-space <package>module-init-tools</package> package to display, query, load and unload kernel modules and their dependencies; </para>
+ </listitem>
+ <listitem>
+ <para>set module parameters both dynamically on the command line and permanently so that you can customize the behavior of your kernel modules; and,</para>
+ </listitem>
+ <listitem>
+ <para>how to load modules at boot time.</para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <title>Note: Installing the module-init-tools package</title>
+ <para>In order to use the kernel module utilities described in this chapter, first ensure the module-init-tools package is installed on your system by running, as root:</para>
+ <screen>~]# <command>yum install module-init-tools</command>
+ </screen>
+ <para>For more information on installing packages with Yum, refer to <xref
+ linkend="sec-Installing"/>.</para>
+ </note>
<section
- id="s1-kernel-module-utils">
- <title>Kernel Module Utilities</title>
- <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>
- <para>For more information on installing packages with <application>Yum</application>, refer to <xref
- linkend="sec-Installing"/>.</para>
- </note>
- <section
- id="sec-Listing_Currently-Loaded_Modules">
- <title>Listing Currently-Loaded Modules</title>
- <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
- id="ex-Using_lsmod_to_display_the_list_of_currently-loaded_kernel_modules">
- <title>Using lsmod to display the list of currently-loaded kernel modules</title>
- <screen>
+ id="sec-Listing_Currently-Loaded_Modules">
+ <title>Listing Currently-Loaded Modules</title>
+ <indexterm>
+ <primary>
+ <command>lsmod</command>
+ </primary>
+ </indexterm>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>listing</secondary>
+ </indexterm>
+ <para>You can list all kernel modules that are currently loaded into the kernel by running the <command>lsmod</command> command:</para>
+ <screen>
++
~]$ <command>lsmod</command>
Module Size Used by
xfs 803635 1
@@@ -118,824 -92,229 +119,822 @@@ dm_crypt 10930
kvm_intel 40311 0
kvm 253162 1 kvm_intel
<lineannotation>[output truncated]</lineannotation>
+ </screen>
+ <para>Each row of <command>lsmod</command> output specifies:</para>
+ <itemizedlist>
+ <listitem>
+ <para>the name of a kernel module currently loaded in memory;</para>
+ </listitem>
+ <listitem>
+ <para>the amount of memory it uses; and,</para>
+ </listitem>
+ <listitem>
+ <para>the sum total of processes that are using the module and other modules which depend on it, followed by a list of the names of those modules, if there are any. Using this list, you can first unload all the modules depending the module you want to unload. For more information, refer to <xref
+ linkend="sec-Unloading_a_Module"/>.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Finally, note that <command>lsmod</command> output is less verbose and considerably easier to read than the content of the <filename>/proc/modules</filename> pseudo-file.</para>
+ </section>
+ <section
+ id="sec-Displaying_Information_About_a_Module">
+ <title>Displaying Information About a Module</title>
+ <indexterm>
+ <primary>
+ <command>modinfo</command>
+ </primary>
+ </indexterm>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>examining</secondary>
+ </indexterm>
+ <para>You can display detailed information about a kernel module by running the <command>modinfo <replaceable><module_name></replaceable>
+ </command> command.</para>
+ <note
+ id="note-Module_names_do_not_end_in_.ko">
+ <title>Module names do not end in .ko</title>
+ <para>When entering the name of a kernel module as an argument to one of the <package>module-init-tools</package> utilities, do not append a <filename>.ko</filename> extension to the end of the name. Kernel module names do not have extensions: their corresponding files do.</para>
+ </note>
+ <para>For example, to display information about the <systemitem
+ class="resource">e1000e</systemitem> module, which is the Intel PRO/1000 network driver, run:</para>
+ <example
+ id="ex-Listing_information_about_a_kernel_module_with_lsmod">
+ <title>Listing information about a kernel module with lsmod</title>
+ <screen>~]# <command>modinfo e1000e</command>
+filename: /lib/modules/2.6.32-71.el6.x86_64/kernel/drivers/net/e1000e/e1000e.ko
+version: 1.2.7-k2
+license: GPL
+description: Intel(R) PRO/1000 Network Driver
+author: Intel Corporation, <linux.nics at intel.com>
+srcversion: 93CB73D3995B501872B2982
+alias: pci:v00008086d00001503sv*sd*bc*sc*i*
+alias: pci:v00008086d00001502sv*sd*bc*sc*i*
+<lineannotation>[some <literal>alias</literal> lines ommitted]</lineannotation>
+alias: pci:v00008086d0000105Esv*sd*bc*sc*i*
+depends:
+vermagic: 2.6.32-71.el6.x86_64 SMP mod_unload modversions
+parm: copybreak:Maximum size of packet that is copied to a new buffer on receive (uint)
+parm: TxIntDelay:Transmit Interrupt Delay (array of int)
+parm: TxAbsIntDelay:Transmit Absolute Interrupt Delay (array of int)
+parm: RxIntDelay:Receive Interrupt Delay (array of int)
+parm: RxAbsIntDelay:Receive Absolute Interrupt Delay (array of int)
+parm: InterruptThrottleRate:Interrupt Throttling Rate (array of int)
+parm: IntMode:Interrupt Mode (array of int)
+parm: SmartPowerDownEnable:Enable PHY smart power down (array of int)
+parm: KumeranLockLoss:Enable Kumeran lock loss workaround (array of int)
+parm: WriteProtectNVM:Write-protect NVM [WARNING: disabling this can lead to corrupted NVM] (array of int)
+parm: CrcStripping:Enable CRC Stripping, disable if your BMC needs the CRC (array of int)
+parm: EEE:Enable/disable on parts that support the feature (array of int)</screen>
+ </example>
+ <variablelist>
+ <para>Here are descriptions of a few of the fields in <command>modinfo</command> output:</para>
+ <varlistentry>
+ <term>filename</term>
+ <listitem>
+ <para>The absolute path to the <filename>.ko</filename> kernel object file. You can use <command>modinfo -n</command> as a shorcut command for printing only the <computeroutput>filename</computeroutput> field.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>description</term>
+ <listitem>
+ <para>A short description of the module. You can use <command>modinfo -d</command> as a shortcut command for printing only the description field.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>alias</term>
+ <listitem>
+ <para>The <computeroutput>alias</computeroutput> field appears as many times as there are aliases for a module, or is ommitted entirely if there are none.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>depends</term>
+ <listitem>
+ <para>This field contains a comma-separated list of all the modules this module depends on.</para>
+ <note
+ id="note-Omitted_depends_field">
+ <title>Note</title>
+ <para>If a module has no dependencies, the <computeroutput>depends</computeroutput> field may be omitted from the output.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>parm</term>
+ <listitem>
+ <para>Each <computeroutput>parm</computeroutput> field presents one module parameter in the form <computeroutput><replaceable>parameter_name</replaceable>:<replaceable>description</replaceable></computeroutput>, where:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <replaceable>parameter_name</replaceable> is the exact syntax you should use when using it as a module parameter on the command line, or in an option line in a <filename>.conf</filename> file in the <filename>/etc/modprobe.d/</filename> directory; and,</para>
+ </listitem>
+ <listitem>
+ <para>
+ <replaceable>description</replaceable> is a brief explanation of what the parameter does, along with an expectation for the type of value the parameter accepts (such as <type>int</type>, <type>unit</type> or <type>array of int</type>) in parentheses.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>You can display a brief summary of the kernel module by using the <option>-d</option> option:</para>
+ <screen>~]# <command>modinfo -d e1000e</command>
+Intel(R) PRO/1000 Network Driver</screen>
+ <para>You can display the absolute path to the module file with the <option>-n</option> option:</para>
+ <screen>~]# <command>modinfo -n e1000e</command>
+/lib/modules/2.6.32-71.el6.x86_64/kernel/drivers/net/e1000e/e1000e.ko</screen>
+ <para>Finally, you can list all parameters that the module supports by using the <option>-p</option> option. However, because useful value type information is omitted from <command>modinfo -p</command> output, it is better to run:</para>
+ <screen>~]# <command>modinfo e1000e |grep "^parm" |sort</command>
+parm: copybreak:Maximum size of packet that is copied to a new buffer on receive (uint)
+parm: CrcStripping:Enable CRC Stripping, disable if your BMC needs the CRC (array of int)
+parm: EEE:Enable/disable on parts that support the feature (array of int)
+parm: InterruptThrottleRate:Interrupt Throttling Rate (array of int)
+parm: IntMode:Interrupt Mode (array of int)
+parm: KumeranLockLoss:Enable Kumeran lock loss workaround (array of int)
+parm: RxAbsIntDelay:Receive Absolute Interrupt Delay (array of int)
+parm: RxIntDelay:Receive Interrupt Delay (array of int)
+parm: SmartPowerDownEnable:Enable PHY smart power down (array of int)
+parm: TxAbsIntDelay:Transmit Absolute Interrupt Delay (array of int)
+parm: TxIntDelay:Transmit Interrupt Delay (array of int)
+parm: WriteProtectNVM:Write-protect NVM [WARNING: disabling this can lead to corrupted NVM] (array of int)</screen>
+ </section>
+ <section
+ id="sec-Loading_a_Module">
+ <title>Loading a Module</title>
+ <indexterm>
+ <primary>
+ <command>modprobe</command>
+ </primary>
+ </indexterm>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>loading</secondary>
+ </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>
+ <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> and <filename
+ class="directory">scsi/</filename>, for network and SCSI interface drivers respectively.</para>
+ <para>Some modules have dependencies, which are other kernel modules that must be loaded before the module in question can be loaded. The <command>modprobe</command> command always takes dependencies into account when performing operations. When you ask <command>modprobe</command> to load a specific kernel module, it first examines the dependencies of that module, if there are any, and loads them if they are not already loaded into the kernel. <command>modprobe</command> resolves dependencies recursively: it will load all dependencies of dependencies, and so on, if necessary, thus ensuring that all dependencies are always met.<!-- Because of this, there is no need to determine and resolve module dependencies manually.-->
+ </para>
+ <para>You can use the <option>-v</option> (i.e. <option>--verbose</option>) option to cause <command>modprobe</command> to display detailed information about what it is doing, which may include loading module dependencies. Here's an example of loading the <systemitem
+ class="protocol">Fibre Channel over Ethernet</systemitem> module verbosely:</para>
+ <example
+ id="ex-modprobe_-v_shows_module_dependencies_as_they_are_loaded">
+ <title>modprobe -v shows module dependencies as they are loaded</title>
+ <screen>~]# <command>modprobe -v fcoe</command>
+insmod /lib/modules/2.6.32-71.el6.x86_64/kernel/drivers/scsi/scsi_tgt.ko
+insmod /lib/modules/2.6.32-71.el6.x86_64/kernel/drivers/scsi/scsi_transport_fc.ko
+insmod /lib/modules/2.6.32-71.el6.x86_64/kernel/drivers/scsi/libfc/libfc.ko
+insmod /lib/modules/2.6.32-71.el6.x86_64/kernel/drivers/scsi/fcoe/libfcoe.ko
+insmod /lib/modules/2.6.32-71.el6.x86_64/kernel/drivers/scsi/fcoe/fcoe.ko</screen>
+ </example>
+ <para>
+ <xref
+ linkend="ex-modprobe_-v_shows_module_dependencies_as_they_are_loaded"/> shows that <command>modprobe</command> loaded the <systemitem
+ class="resource">scsi_tgt</systemitem>, <systemitem
+ class="resource">scsi_transport_fc</systemitem>, <systemitem
+ class="resource">libfc</systemitem> and <systemitem
+ class="resource">libfcoe</systemitem> modules as dependencies before finally loading <systemitem
+ class="resource">fcoe</systemitem>. Also note that <command>modprobe</command> used the more <quote>primitive</quote>
+ <command>insmod</command> command to insert the modules into the running kernel.</para>
+ <indexterm>
+ <primary>
+ <command>insmod</command>
+ </primary>
+ </indexterm>
+ <important
+ id="important-Always_use_modprobe_instead_of_insmod">
+ <title>Always use modprobe instead of insmod!</title>
+ <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>
+ </section>
+ <section
+ id="sec-Unloading_a_Module">
+ <title>Unloading a Module</title>
+ <indexterm>
+ <primary>
+ <command>modprobe</command>
+ </primary>
+ </indexterm>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>unloading</secondary>
+ </indexterm>
+ <para>You can unload a kernel module by running <command>modprobe -r <replaceable><module_name></replaceable>
+ </command> as root. For example, assuming that the <systemitem
+ class="resource">wacom</systemitem> module is already loaded into the kernel, you can unload it by running:</para>
+ <screen>~]# <command>modprobe -r wacom</command>
+ </screen>
+ <para>However, this command will fail if a process is using:</para>
+ <itemizedlist>
+ <listitem>
+ <para>the <systemitem
+ class="resource">wacom</systemitem> module,</para>
+ </listitem>
+ <listitem>
+ <para>a module that <systemitem
+ class="resource">wacom</systemitem> directly depends on, or,</para>
+ </listitem>
+ <listitem>
+ <para>any module that <systemitem
+ class="resource">wacom</systemitem>—through the dependency tree—depends on indirectly.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Refer to <xref
+ linkend="sec-Listing_Currently-Loaded_Modules"/> for more information about using <command>lsmod</command> to obtain the names of the modules which are preventing you from unloading a certain module.</para>
+ <para>For example, if you want to unload the <systemitem
+ class="resource">firewire_ohci</systemitem> module because (because you believe there is a bug in it that is affecting system stability, for example), your terminal session might look similar to this:</para>
- <screen>~]# <command>modinfo firewire_ohci |grep "^dep"</command>
++ <screen>~]# <command>modinfo -F depends firewire_ohci</command>
+depends: firewire-core
- ~]# <command>modinfo firewire_core |grep "^dep"</command>
++~]# <command>modinfo -F depends firewire_core</command>
+depends: crc-itu-t
- ~]#<command>modinfo crc-itu-t |grep "^dep"</command>
++~]#<command>modinfo -F depends crc-itu-t</command>
+depends:</screen>
+ <para>You have figured out the dependency tree (which does not branch in this example) for the loaded Firewire modules: <systemitem
+ class="resource">firewire_ohci</systemitem> depends on <systemitem
+ class="resource">firewire_core</systemitem>, which itself depends on <systemitem
+ class="resource">crc-itu-t</systemitem>.</para>
+ <para>You can unload <systemitem
+ class="resource">firewire_ohci</systemitem> using the <command>modprobe -v -r <replaceable><module_name></replaceable>
+ </command> command, where <option>-r</option> is short for <option>--remove</option> and <option>-v</option> for <option>--verbose</option>:</para>
+ <screen>~]# <command>modprobe -r -v firewire_ohci</command>
+rmmod /lib/modules/2.6.32-71.el6.x86_64/kernel/drivers/firewire/firewire-ohci.ko
+rmmod /lib/modules/2.6.32-71.el6.x86_64/kernel/drivers/firewire/firewire-core.ko
+rmmod /lib/modules/2.6.32-71.el6.x86_64/kernel/lib/crc-itu-t.ko</screen>
+ <para>The output shows that modules are unloaded in the reverse order that they are loaded, given that no proceses depend on any of the modules being unloaded.</para>
+ <indexterm>
+ <primary>
+ <command>rmmod</command>
+ </primary>
+ </indexterm>
+ <important
+ id="important-Do_not_use_rmmod_directly">
+ <title>Do not use rmmod directly!</title>
+ <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>
+ <section
+ id="sec-Setting_Module_Parameters">
+ <title>Setting Module Parameters</title>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>module 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>Like the kernel itself, modules can also take parameters that change their behavior. Most of the time, the default ones work well, but occasionally it is necessary or desirable to set custom parameters for a module. Because parameters cannot be dynamically set for a module that is already loaded into a running kernel, there are two different methods for setting them.</para>
+ <orderedlist>
+ <listitem>
+ <para>You can unload all dependencies of the module you want to set parameters for, unload the module using <command>modprobe -r</command>, and then load it with <command>modprobe</command> along with a list of customized parameters. This method is often used when the module does not have many dependencies, or to test different combinations of parameters without making them persistent, and is the method covered in this section.</para>
+ </listitem>
+ <listitem>
+ <para>Alternatively, you can list the new parameters in an existing or newly-created file in the <filename>/etc/modprobe.d/</filename> directory. This method makes the module parameters persistent by ensuring that they are set each time the module is loaded, such as after every reboot or <command>modprobe</command> command. This method is covered in <xref
+ linkend="sec-Persistent_Module_Loading"/>, though the following information is a prerequisite.</para>
+ </listitem>
+ </orderedlist>
+ <para>You can use <command>modprobe</command> to load a kernel module with custom parameters using the following command line format:</para>
+ <example
+ id="ex-Supplying_optional_parameters_when_loading_a_kernel_module">
+ <title>Supplying optional parameters when loading a kernel module</title>
+ <screen>~]# <command>modprobe <replaceable><module_name></replaceable> <optional><replaceable>parameter</replaceable>=<replaceable>value</replaceable></optional>
+ </command>
+ </screen>
+ </example>
+ <para>Here are some things to be aware of when loading a module with custom parameters on the command line:</para>
+ <itemizedlist>
+ <listitem>
+ <para>You can enter multiple parameters and values by separating them with spaces.</para>
+ </listitem>
+ <listitem>
+ <para>Some module parameters expect a list of comma-separated values as their argument. When entering the list of values, do <emphasis>not</emphasis> insert a space after each comma, or <command>modprobe</command> will incorrectly interpret the values following spaces as additional parameters.</para>
+ </listitem>
+ <listitem>
+ <para>The <command>modprobe</command> command silently succeeds with an exit status of <constant>0</constant> if:</para>
+ <itemizedlist>
+ <listitem>
+ <para>it successfully loads the module, <emphasis>or</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>the module is <emphasis>already</emphasis> loaded into the kernel.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Thus, you must ensure that the module is not already loaded before attempting to load it with custom parameters. The <command>modprobe</command> command does not automatically reload the module, or alert you that it is already loaded.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Here are the recommended steps for setting custom parameters and then loading a kernel module. This procedure illustrates the steps using the <systemitem
+ class="resource">e1000e</systemitem> module, which is the network driver for Intel PRO/1000 network adapters, as an example:</para>
+ <procedure
+ id="proc-Loading_a_Kernel_Module_with_Custom_Parameters">
+ <title>Loading a Kernel Module with Custom Parameters</title>
+ <step
+ id="proc-step1-Loading_a_Kernel_Module_with_Custom_Parameters">
+ <para>First, ensure the module is not already loaded into the kernel:</para>
+ <screen>~]# <command>lsmod |grep e1000e</command>
+~]# </screen>
+ <para>Output indicates that the module is already loaded into the kernel, in which case you must first unload it before proceeding. Refer to <xref
+ linkend="sec-Unloading_a_Module"/> for instructions on safely unloading it.</para>
+ </step>
+ <step
+ id="proc-step2-Loading_a_Kernel_Module_with_Custom_Parameters">
+ <para>Load the module and list all custom parameters after the module name. For example, if you wanted to load the Intel PRO/1000 network driver with the interrupt throttle rate set to 3000 interrupts per second for the first, second and third instances of the driver, and Energy Efficient Ethernet (EEE) turned on<footnote
+ id="footnote-Energy_Efficient_Ethernet"><para>Despite what the example might imply, Energy Efficient Ethernet is turned on by default in the <systemitem
+ class="resource">e1000e</systemitem> driver.</para>
+ </footnote>
+, you would run, as root:</para>
+ <screen>~]# <command>modprobe e1000e InterruptThrottleRate=3000,3000,3000 EEE=1</command>
</screen>
- </example>
+ <para>This example illustrates passing multiple valued to a single parameter by separating them with commas and omitting any spaces between them.</para>
+ </step>
+ </procedure>
+ </section>
+ <section
+ id="sec-Persistent_Module_Loading">
+ <title>Persistent Module Loading</title>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>persistent loading</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>kernel module</primary>
+ <secondary>/etc/sysconfig/modules/</secondary>
+ </indexterm>
+ <para>As shown in <xref
+ linkend="ex-Listing_information_about_a_kernel_module_with_lsmod"/>, 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
+ class="directory">/etc/sysconfig/modules/</filename> directory, where <replaceable><file_name></replaceable> is any descriptive name of your choice. Your <filename><replaceable><file_name></replaceable>.modules</filename> files are treated by the system startup scripts as shell scripts, and as such should begin with an <firstterm>interpreter directive</firstterm> (also called a <quote>bang line</quote>) as their first line:</para>
+ <example
+ id="ex-First_line_of_a_file_name.modules_file">
+ <title>First line of a <replaceable>file_name</replaceable>.modules file</title>
+ <screen>#!/bin/sh</screen>
+ </example>
+ <para>Additionally, the <filename><replaceable><file_name></replaceable>.modules</filename> file should be executable. You can make it executable by running:</para>
+ <screen>modules]# <command>chmod +x <replaceable><file_name></replaceable>.modules</command>
+ </screen>
+ <para>For example, the following <filename>bluez-uinput.modules</filename> script loads the <systemitem
+ class="resource">uinput</systemitem> module:</para>
+ <example
+ id="ex-bluez-uinput.modules">
+ <title>/etc/sysconfig/modules/bluez-uinput.modules</title>
+ <programlisting
+ language="Bash">#!/bin/sh
+
+if [ ! -c /dev/input/uinput ] ; then
+ exec /sbin/modprobe uinput >/dev/null 2>&1
+fi</programlisting>
+ <para>The <literal>if</literal>-conditional statement on the third line ensures that the <filename>/dev/input/uinput</filename> file does <emphasis>not</emphasis> already exist (the <literal>!</literal> symbol negates the condition), and, if that is the case, loads the <systemitem
+ class="resource">uinput</systemitem> module by calling <command>exec /sbin/modprobe uinput</command>. Note that the <systemitem
+ class="resource">uinput</systemitem> module creates the <filename>/dev/input/uinput</filename> file, so testing to see if that file exists serves as verification of whether the <systemitem
+ class="resource">uinput</systemitem> module is loaded into the kernel.</para>
+ <para>The following <command>>/dev/null 2>&1</command> clause at the end of that line simply redirects any output to <filename>/dev/null</filename> so that the <command>modprobe</command> command remains quiet.</para>
+ </example>
+ <!-- silas: most modules are autoloaded these days...
+ <note
+ id="note-No_Need_to_Load_Network_and_SCSI_Modules">
+ <title>Note: Do Not Load Network and SCSI Modules</title>
+ <para>Networking and SCSI modules do not generally need to be manually loaded as they have their own particular loading mechanisms.</para>
+ </note>-->
+ </section>
+ <section
+ id="sec-Specific_Kernel_Module_Capabilities">
+ <title>Specific Kernel Module Capabilities</title>
+ <para>This section explains how to enable specific kernel capabilities using various kernel modules.</para>
+ <section
+ id="sec-Using_Multiple_Ethernet_Cards">
+ <title>Using Multiple Ethernet Cards</title>
<indexterm>
<primary>kernel module</primary>
- <secondary>files</secondary>
- <tertiary><filename>/proc/modules</filename></tertiary>
+ <secondary>Ethernet module</secondary>
+ <tertiary>supporting multiple cards</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
- class="resource">ipv6</systemitem> module has 33 dependencies.</para>
- </footnote>
- <command>lsmod</command> output is less verbose and considerably easier to read than the content of the <filename>/proc/modules</filename> pseudo-file.</para>
+ <indexterm>
+ <primary>Ethernet module</primary>
+ <see>kernel module</see>
+ </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
+ url="http://www.redhat.com/mirrors/LDP/HOWTO/Ethernet-HOWTO.html">http://www.redhat.com/mirrors/LDP/HOWTO/Ethernet-HOWTO.html</ulink>.</para>
</section>
<section
- id="sec-Displaying_Information_About_a_Module">
- <title>Displaying Information About a Module</title>
+ id="sec-Using_Channel_Bonding">
+ <title>Using Channel Bonding</title>
<indexterm>
- <primary>kernel module</primary>
- <secondary>listing</secondary>
- <tertiary>module information</tertiary>
+ <primary>channel bonding</primary>
+ <secondary>bonding options</secondary>
</indexterm>
++
<indexterm>
<primary>kernel module</primary>
- <secondary>utilities</secondary>
- <tertiary><command>modinfo</command></tertiary>
+ <secondary>channel bonding</secondary>
</indexterm>
<indexterm>
- <primary><command>modinfo</command></primary>
- <seealso>kernel module</seealso>
+ <primary>NIC</primary>
+ <secondary>binding into single channel</secondary>
</indexterm>
- <para>To display detailed information about a kernel module, run the <command>modinfo <replaceable><module_name></replaceable>
- </command> command.</para>
- <note
- id="note-Module_names_do_not_end_in_.ko">
- <title>Module names do not end in .ko</title>
- <para>When entering the name of a kernel module as an argument to one of the <package>module-init-tools</package> utilities, do not append a <filename>.ko</filename> extension to the end of the name.</para>
- </note>
- <para>For example, to display information about the <systemitem
- class="resource">e100</systemitem> module, enter:</para>
- <screen>~]# <command>modinfo e100</command>
-filename: /lib/modules/2.6.32-54.&PKGOS;.i686/kernel/drivers/net/e100.ko
-firmware: e100/d102e_ucode.bin
-firmware: e100/d101s_ucode.bin
-firmware: e100/d101m_ucode.bin
-version: 3.5.24-k2-NAPI
-license: GPL
-author: Copyright(c) 1999-2006 Intel Corporation
-description: Intel(R) PRO/100 Network Driver
-srcversion: B3A9FA10F08AF446AA1CC6B
-alias: pci:v00008086d000027DCsv*sd*bc02sc00i*
-alias: pci:v00008086d0000245Dsv*sd*bc02sc00i*
-alias: pci:v00008086d00002459sv*sd*bc02sc00i*
-<lineannotation>[some output ommitted]</lineannotation>
-depends: mii
-vermagic: 2.6.32-54.&PKGOS;.i686 SMP mod_unload modversions 686
-parm: debug:Debug level (0=none,...,16=all) (int)
-parm: eeprom_bad_csum_allow:Allow bad eeprom checksums (int)
-parm: use_io:Force use of i/o access mode (int)</screen>
- <para>To display only a brief description of the module, use the <option>-d</option> option. For example:</para>
- <screen>~]# <command>modinfo -d e100</command>
-Intel(R) PRO/100 Network Driver</screen>
- <para>To list all parameters the module supports, use the <option>-p</option> option:</para>
- <screen>~]# <command>modinfo -p e100</command>
-use_io:Force use of i/o access mode
-eeprom_bad_csum_allow:Allow bad eeprom checksums
-debug:Debug level (0=none,...,16=all)</screen>
- <para>Finally, to display the absolute path to the module file, use the <option>-n</option> option:</para>
- <screen>~]# <command>modinfo -n e100</command>
-/lib/modules/2.6.32-54.el6.i686/kernel/drivers/net/e100.ko</screen>
- </section>
- <section
- id="s2-kernel-module-utils-modprobe">
- <title>Loading a Module</title>
<indexterm>
<primary>kernel module</primary>
- <secondary>loading</secondary>
- <tertiary>for the current session</tertiary>
+ <secondary>bonding kernel module</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>
+ <secondary>channel bonding interface</secondary>
</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>
+ <primary>channel bonding interface</primary>
+ <see>kernel module</see>
</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
- class="directory">scsi/</filename> for SCSI interface drivers.</para>
- <para>Some kernel modules have dependencies, which are other modules they depend on, and which must be loaded first. Before <command>modprobe</command> loads any kernel module, it first examines the dependencies of that module (if there are any) and ensures they are loaded, or loads them if not. Like the <application>Yum</application> package manager, <command>modprobe</command> resolves dependencies recursively, which means that all dependencies are always met. Because of this, there is no need to determine and resolve module dependencies manually.</para>
- <para>You can use the <option>-v</option> option to cause <command>modprobe</command> to display detailed information about what it is doing, which may include loading module dependencies:</para>
- <screen>~]# <command>modprobe -v e100</command>
-insmod /lib/modules/2.6.32-54.el6.i686/kernel/drivers/net/mii.ko
-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>
- <important
- id="important-Do_not_use_insmod_directly">
- <title>Do not use insmod directly!</title>
+ <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>
+ <para>To channel bond multiple network interfaces, the administrator must perform the following steps:</para>
+ <orderedlist
+ continuation="restarts"
+ inheritnum="ignore">
+ <listitem>
+ <para>As root, create a new file named <filename><replaceable><bonding></replaceable>.conf</filename> in the <filename>/etc/modprobe.d/</filename> directory. Note that you can name this file anything you like as long as it ends with a <filename>.conf</filename> extension. Insert the following line in this new file:</para>
+ <screen>alias bond<replaceable><N></replaceable> bonding</screen>
+ <para>Replace <replaceable><N></replaceable> with the interface number, such as <command>0</command>. For each configured channel bonding interface, there must be a corresponding entry in your new <filename>/etc/modprobe.d/<replaceable><bonding></replaceable>.conf</filename> file.</para>
+ </listitem>
+ <listitem>
+ <para>Configure a channel bonding interface as outlined in <xref
+ linkend="s2-networkscripts-interfaces-chan"/>.</para>
+ </listitem>
+ <listitem>
+ <para>To enhance performance, adjust available module options to ascertain what combination works best. Pay particular attention to the <command>miimon</command> or <command>arp_interval</command> and the <command>arp_ip_target</command> parameters. Refer to <xref
+ linkend="s3-modules-bonding-directives"/> for a list of available options and how to quickly determine the best ones for your bonded interface.</para>
+ </listitem>
+ </orderedlist>
+ <section
+ 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>utilities</secondary>
- <tertiary><command>insmod</command></tertiary>
++ <secondary>parameters</secondary>
++ <tertiary>bonding module parameters</tertiary>
</indexterm>
<indexterm>
- <primary><command>insmod</command></primary>
- <seealso>kernel module</seealso>
+ <primary>channel bonding</primary>
+ <secondary>parameters to bonded interfaces</secondary>
</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>parameters</secondary>
- <tertiary>specifying</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">
- <title>Supplying optional parameters when loading a kernel module</title>
- <screen>~]# <command>modprobe <replaceable><module_name></replaceable> <optional><replaceable>parameter</replaceable>=<replaceable>value</replaceable></optional>
- </command>
- </screen>
- </example>
- <para>For example, to allow bad eeprom checksums, and to set the debug level to maximum for an Intel Ether Express/100 driver, enter:</para>
- <screen>~]# <command>modprobe e100 eeprom_bad_csum_allow=1 debug=16</command>
- </screen>
- <para>Some module parameters expect a list of comma-separated values as their argument. When entering the values, do <emphasis>not</emphasis> insert a space after each comma, or <command>modprobe</command> will incorrectly interpret the values following spaces as additional parameters.</para>
- </section>
- <section
- id="s2-kernel-module-utils-rmmod">
- <title>Unloading a Module</title>
- <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>
- <screen>~]# <command>modprobe -r wacom</command>
- </screen>
- <para>The <command>modprobe -r</command> command only unloads modules that are not in use and that are not a dependency of other modules in use. On the other hand, it checks for dependencies and unloads all modules that were previously required, but that are no longer necessary.</para>
- <para>To display all commands as <command>modprobe</command> executes them, use the <option>-v</option> option. For example:</para>
- <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>
- <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>
+ <secondary>bonding kernel module</secondary>
+ <tertiary>parameters to bonded interfaces</tertiary>
</indexterm>
<indexterm>
- <primary>bonding kernel module</primary>
- <secondary>sysfs</secondary>
- <primary><command>rmmod</command></primary>
- <seealso>kernel module</seealso>
++ <primary>kernel module</primary>
++ <secondary>bonding module</secondary>
++ <see>channel bonding</see>
</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>
- <section
- id="s2-kernel-modules-persistent">
- <title>Persistent Module Loading</title>
- <indexterm>
- <primary>kernel module</primary>
- <secondary>loading</secondary>
- <tertiary>at the boot time</tertiary>
- </indexterm>
- <indexterm>
- <primary>kernel module</primary>
- <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
- class="directory">/etc/sysconfig/modules/</filename> directory. Note that you can use any descriptive name that you like in place of <filename><replaceable><file_name></replaceable></filename>. Your <filename>file_name.modules</filename> files are treated by the system startup scripts as shell scripts, and as such should begin with an <firstterm>interpreter directive</firstterm> (also called a <quote>bang line</quote>) as their first line:</para>
- <example
- id="ex-First_line_of_a_file_name.modules_file">
- <title>First line of a <replaceable>file_name</replaceable>.modules file</title>
- <screen>#!/bin/sh</screen>
- </example>
- <para>Additionally, the <filename><replaceable><file_name></replaceable>.modules</filename> file should be executable. You can make it executable by running:</para>
- <screen>modules]# <command>chmod +x <replaceable><file_name></replaceable>.modules</command>
- </screen>
- <para>For example, the following <filename>bluez-uinput.modules</filename> script loads the <systemitem
- class="resource">uinput</systemitem> module:</para>
- <example
- id="ex-bluez-uinput.modules">
- <title>/etc/sysconfig/modules/bluez-uinput.modules</title>
- <programlisting>#!/bin/sh
-if [ ! -c /dev/input/uinput ] ; then
- exec /sbin/modprobe uinput >/dev/null 2>&1
-fi</programlisting>
- </example>
- <para>The <literal>if</literal>-conditional statement on the third line ensures that the <filename>/dev/input/uinput</filename> file does <emphasis>not</emphasis> already exist (the <literal>!</literal> symbol negates the condition), and, if that is the case, loads the <systemitem class="resource">uinput</systemitem> module by calling <command>exec /sbin/modprobe uinput</command>. The following <command>>/dev/null 2>&1</command> clause at the end of that line simply redirects any output to <filename>/dev/null</filename> so that the <command>modprobe</command> command remains quiet.</para>
- <note
- id="note-No_Need_to_Load_Network_and_SCSI_Modules">
- <title>Note: Do Not Load Network and SCSI Modules</title>
- <para>Networking and SCSI modules do not generally need to be manually loaded as they have their own particular loading mechanisms.</para>
- </note>
+ <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
+ class="filesystem">sysfs</systemitem> can be used to query for information about kernel objects, and can also manipulate those objects through the use of normal file system commands. The <systemitem
+ class="filesystem">sysfs</systemitem> virtual file system has a line in <filename>/etc/fstab</filename>, and is mounted under the <filename>/sys/</filename> directory. All bonding interfaces can be configured dynamically by interacting with and manipulating files under the <filename>/sys/class/net/</filename> directory. </para>
+ <para>After you have created a channel bonding interface file such as <filename>ifcfg-bond0</filename> and inserted <parameter
+ class="option">SLAVE=yes</parameter> and <parameter
+ class="option">MASTER=bond0</parameter> directives in the configuration files for each interface bonded to bond0 following the instructions in <xref
+ linkend="s2-networkscripts-interfaces-chan"/>, you can proceed to testing and determining the best parameters for your bonding 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>
+ <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>
+ <screen>~]# <command>ifconfig</command>
+bond0 Link encap:Ethernet HWaddr 00:00:00:00:00:00
+ UP BROADCAST RUNNING MASTER MULTICAST MTU:1500 Metric:1
+ RX packets:0 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:0
+ RX bytes:0 (0.0 b) TX bytes:0 (0.0 b)
+eth0 Link encap:Ethernet HWaddr 52:54:00:26:9E:F1
+ inet addr:192.168.122.251 Bcast:192.168.122.255 Mask:255.255.255.0
+ inet6 addr: fe80::5054:ff:fe26:9ef1/64 Scope:Link
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:207 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:205 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:70374 (68.7 KiB) TX bytes:25298 (24.7 KiB)
+<lineannotation>[output truncated]</lineannotation>
+ </screen>
+ <para>To view all existing bonds, even if they are not up, run:</para>
+ <screen>~]# <command>cat /sys/class/net/bonding_masters</command>
+bond0</screen>
+ <para>You can configure each bond individually by manipulating the files located in the <filename>/sys/class/net/bond<replaceable><N></replaceable>/bonding/</filename> directory. First, the bond you are configuring must be taken down:</para>
+ <screen>~]# <command>ifconfig bond0 down</command>
+ </screen>
+ <para>As an example, to enable MII monitoring on bond0 with a 1 second interval, you could run (as root):</para>
+ <screen>~]# <command>echo 1000 > /sys/class/net/bond0/bonding/miimon</command>
+ </screen>
+ <para>To configure bond0 for <parameter
+ class="option">balance-alb</parameter> mode, you could run either:</para>
+ <screen>~]# <command>echo 6 > /sys/class/net/bond0/bonding/mode</command>
+ </screen>
+ <para>...or, using the name of the mode:</para>
+ <screen>~]# <command>echo balance-alb > /sys/class/net/bond0/bonding/mode</command>
+ </screen>
+ <para>After configuring some options for the bond in question, you can bring it up and test it by running <command>ifconfig bond<replaceable><N></replaceable> <option>up</option>
+ </command>. If you decide to change the options, take the interface down, modify its parameters using <systemitem
+ class="filesystem">sysfs</systemitem>, bring it back up, and re-test.</para>
+ <para>Once you have determined the best set of parameters for your bond, add those parameters as a space-separated list to the <parameter
+ class="option">BONDING_OPTS=</parameter> directive of the <filename>/etc/sysconfig/network-scripts/ifcfg-bond<replaceable><N></replaceable>
+ </filename> file for the bonding interface you are configuring. Whenever that bond is brought up (for example, by the system during the boot sequence if the <parameter
+ class="option">ONBOOT=yes</parameter> directive is set), the bonding options specified in the <parameter
+ class="option">BONDING_OPTS</parameter> will take effect for that bond. For more information on configuring bonding interfaces (and <parameter
+ class="option">BONDING_OPTS</parameter>), refer to <xref
+ linkend="s2-networkscripts-interfaces-chan"/>.</para>
+ <para>The following list provides the names of many of the more common channel bonding parameters, along with a descriptions of what they do. For more information, refer to the brief descriptions for each <computeroutput>parm</computeroutput> in <command>modinfo bonding</command> output, or the exhaustive descriptions in the <filename>bonding.txt</filename> file in the <package>kernel-doc</package> package (see <xref
+ linkend="s1-kernel-modules-additional-resources"/>).</para>
+ <variablelist
+ spacing="compact">
+ <title>Bonding Interface Parameters</title>
+ <varlistentry>
+ <term>
+ <literal>arp_interval=<replaceable><time_in_milliseconds></replaceable>
+ </literal>
+ </term>
+ <listitem>
+ <para>Specifies (in milliseconds) how often ARP monitoring occurs.</para>
+ <important>
+ <title>Important</title>
+ <para>It is essential that both <literal>arp_interval</literal> and <literal>arp_ip_target</literal> parameters are specified, or, alternatively, the <literal>miimon</literal> parameter is specified. Failure to do so can cause degradation of network performance in the event that a link fails.</para>
+ </important>
+ <para>If using this setting while in <literal>mode=0</literal> or <literal>mode=1</literal> (the two load-balancing modes), the network switch must be configured to distribute packets evenly across the NICs. For more information on how to accomplish this, refer to <filename>/usr/share/doc/kernel-doc-<replaceable><kernel_version></replaceable>/Documentation/networking/bonding.txt</filename>
+ </para>
+ <para>The value is set to <userinput>0</userinput> by default, which disables it.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>arp_ip_target=<replaceable><ip_address></replaceable><optional>,<replaceable><ip_address_2></replaceable>,…<replaceable><ip_address_16></replaceable></optional>
+ </literal>
+ </term>
+ <listitem>
+ <para>Specifies the target IP address of ARP requests when the <literal>arp_interval</literal> parameter is enabled. Up to 16 IP addresses can be specified in a comma separated list.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>arp_validate=<replaceable><value></replaceable>
+ </literal>
+ </term>
+ <listitem>
+ <para>Validate source/distribution of ARP probes; default is <userinput>none</userinput>. Other valid values are <userinput>active</userinput>, <userinput>backup</userinput>, and <userinput>all</userinput>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>debug=<replaceable><number></replaceable>
+ </literal>
+ </term>
+ <listitem>
+ <para>Enables debug messages. Possible values are:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <userinput>0</userinput> — Debug messages are disabled. This is the default.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>1</userinput> — Debug messages are enabled.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>downdelay=<replaceable><time_in_milliseconds></replaceable>
+ </literal>
+ </term>
+ <listitem>
+ <para>Specifies (in milliseconds) how long to wait after link failure before disabling the link. The value must be a multiple of the value specified in the <literal>miimon</literal> parameter. The value is set to <userinput>0</userinput> by default, which disables it.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>lacp_rate=<replaceable><value></replaceable>
+ </term>
+ <listitem>
+ <para>Specifies the rate at which link partners should transmit LACPDU packets in 802.3ad mode. Possible values are:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <userinput>slow</userinput> or <userinput>0</userinput> — Default setting. This specifies that partners should transmit LACPDUs every 30 seconds.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>fast</userinput> or <userinput>1</userinput> — Specifies that partners should transmit LACPDUs every 1 second.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>miimon=<replaceable><time_in_milliseconds></replaceable>
+ </literal>
+ </term>
+ <listitem>
+ <para>Specifies (in milliseconds) how often MII link monitoring occurs. This is useful if high availability is required because MII is used to verify that the NIC is active. To verify that the driver for a particular NIC supports the MII tool, type the following command as root:</para>
+ <screen>~]# <command>ethtool <replaceable><interface_name></replaceable> | grep "Link detected:"</command>
+ </screen>
+ <para>In this command, replace <replaceable><interface_name</replaceable>> with the name of the device interface, such as <userinput>eth0</userinput>, not the bond interface. If MII is supported, the command returns:</para>
+ <screen>Link detected: yes</screen>
+ <para>If using a bonded interface for high availability, the module for each NIC must support MII. Setting the value to <userinput>0</userinput> (the default), turns this feature off. When configuring this setting, a good starting point for this parameter is <userinput>100</userinput>.</para>
+ <important>
+ <title>Important</title>
+ <para>It is essential that both <literal>arp_interval</literal> and <literal>arp_ip_target</literal> parameters are specified, or, alternatively, the <literal>miimon</literal> parameter is specified. Failure to do so can cause degradation of network performance in the event that a link fails.</para>
+ </important>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>mode=<replaceable><value></replaceable>
+ </literal>
+ </term>
+ <listitem>
+ <para>...where <replaceable><value></replaceable> is one of:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <userinput>balance-rr</userinput> or <userinput>0</userinput> — Sets a round-robin policy for fault tolerance and load balancing. Transmissions are received and sent out sequentially on each bonded slave interface beginning with the first one available.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>active-backup</userinput> or <userinput>1</userinput> — Sets an active-backup policy for fault tolerance. Transmissions are received and sent out via the first available bonded slave interface. Another bonded slave interface is only used if the active bonded slave interface fails.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>balance-xor</userinput> or <userinput>2</userinput> — Sets an XOR (exclusive-or) policy for fault tolerance and load balancing. Using this method, the interface matches up the incoming request's MAC address with the MAC address for one of the slave NICs. Once this link is established, transmissions are sent out sequentially beginning with the first available interface.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>broadcast</userinput> or <userinput>3</userinput> — Sets a broadcast policy for fault tolerance. All transmissions are sent on all slave interfaces.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>802.3ad</userinput> or <userinput>4</userinput> — Sets an IEEE 802.3ad dynamic link aggregation policy. Creates aggregation groups that share the same speed and duplex settings. Transmits and receives on all slaves in the active aggregator. Requires a switch that is 802.3ad compliant.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>balance-tlb</userinput> or <userinput>5</userinput> — Sets a Transmit Load Balancing (TLB) policy for fault tolerance and load balancing. The outgoing traffic is distributed according to the current load on each slave interface. Incoming traffic is received by the current slave. If the receiving slave fails, another slave takes over the MAC address of the failed slave.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>balance-alb</userinput> or <userinput>6</userinput> — Sets an Active Load Balancing (ALB) policy for fault tolerance and load balancing. Includes transmit and receive load balancing for IPV4 traffic. Receive load balancing is achieved through ARP negotiation.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>num_unsol_na=<replaceable><number></replaceable>
+ </literal>
+ </term>
+ <listitem>
+ <para>Specifies the number of unsolicited IPv6 Neighbor Advertisements to be issued after a failover event. One unsolicited NA is issued immediately after the failover.</para>
+ <para>The valid range is <userinput>0 - 255</userinput>; the default value is <userinput>1</userinput>. This parameter affects only the active-backup mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>primary=<replaceable><interface_name></replaceable>
+ </literal>
+ </term>
+ <listitem>
+ <para>Specifies the interface name, such as <userinput>eth0</userinput>, of the primary device. The <literal>primary</literal> device is the first of the bonding interfaces to be used and is not abandoned unless it fails. This setting is particularly useful when one NIC in the bonding interface is faster and, therefore, able to handle a bigger load.</para>
+ <para>This setting is only valid when the bonding interface is in <userinput>active-backup</userinput> mode. Refer to <filename> /usr/share/doc/kernel-doc-<replaceable><kernel-version></replaceable>/Documentation/networking/bonding.txt</filename> for more information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>primary_reselect=<replaceable><value></replaceable>
+ </literal>
+ </term>
+ <listitem>
+ <para>Specifies the reselection policy for the primary slave. This affects how the primary slave is chosen to become the active slave when failure of the active slave or recovery of the primary slave occurs. This parameter is designed to prevent flip-flopping between the primary slave and other slaves. Possible values are:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <userinput>always</userinput> or <userinput>0</userinput> (default) — The primary slave becomes the active slave whenever it comes back up.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>better</userinput> or <userinput>1</userinput> — The primary slave becomes the active slave when it comes back up, if the speed and duplex of the primary slave is better than the speed and duplex of the current active slave.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>failure</userinput> or <userinput>2</userinput> — The primary slave becomes the active slave only if the current active slave fails and the primary slave is up.</para>
+ </listitem>
+ </itemizedlist>
+ <para>The <literal>primary_reselect</literal> setting is ignored in two cases:</para>
+ <itemizedlist>
+ <listitem>
+ <para>If no slaves are active, the first slave to recover is made the active slave.</para>
+ </listitem>
+ <listitem>
+ <para>When initially enslaved, the primary slave is always made the active slave.</para>
+ </listitem>
+ </itemizedlist>
+ <!-- <para>If no slaves are active, the first slave to recover is made the active slave.</para>
+ <para>When initially enslaved, the primary slave is always made the active slave.</para>-->
+ <para>Changing the <literal>primary_reselect</literal> policy via <systemitem
+ class="filesystem">sysfs</systemitem> will cause an immediate selection of the best active slave according to the new policy. This may or may not result in a change of the active slave, depending upon the circumstances</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>updelay=<replaceable><time_in_milliseconds></replaceable>
+ </literal>
+ </term>
+ <listitem>
+ <para>Specifies (in milliseconds) how long to wait before enabling a link. The value must be a multiple of the value specified in the <literal>miimon</literal> parameter. The value is set to <userinput>0</userinput> by default, which disables it.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>use_carrier=<replaceable><number></replaceable>
+ </literal>
+ </term>
+ <listitem>
+ <para>Specifies whether or not <literal>miimon</literal> should use MII/ETHTOOL ioctls or <function>netif_carrier_ok()</function> to determine the link state. The <function>netif_carrier_ok()</function> function relies on the device driver to maintains its state with <literal>netif_carrier_<replaceable>on/off</replaceable>
+ </literal>; most device drivers support this function.</para>
+ <para>The MII/ETHROOL ioctls tools utilize a deprecated calling sequence within the kernel. However, this is still configurable in case your device driver does not support <literal>netif_carrier_<replaceable>on/off</replaceable>
+ </literal>.</para>
+ <para>Valid values are:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <userinput>1</userinput> — Default setting. Enables the use of <function>netif_carrier_ok()</function>.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>0</userinput> — Enables the use of MII/ETHTOOL ioctls.</para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <title>Tip</title>
+ <para>If the bonding interface insists that the link is up when it should not be, it is possible that your network device driver does not support <literal>netif_carrier_<replaceable>on/off</replaceable>
+ </literal>.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>xmit_hash_policy=<replaceable><value></replaceable>
+ </literal>
+ </term>
+ <listitem>
+ <para>Selects the transmit hash policy used for slave selection in <userinput>balance-xor</userinput> and <userinput>802.3ad</userinput> modes. Possible values are:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <userinput>0</userinput> or <userinput>layer2</userinput> — Default setting. This parameter uses the XOR of hardware MAC addresses to generate the hash. The formula used is:</para>
+ <screen>(<replaceable><source_MAC_address></replaceable> XOR <replaceable><destination_MAC></replaceable>) MODULO <replaceable><slave_count></replaceable>
+ </screen>
+ <para>This algorithhm will place all traffic to a particular network peer on the same slave, and is 802.3ad compliant.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>1</userinput> or <userinput>layer3+4</userinput> — Uses upper layer protocol information (when available) to generate the hash. This allows for traffic to a particular network peer to span multiple slaves, although a single connection will not span multiple slaves.</para>
+ <para>The formula for unfragmented TCP and UDP packets used is:</para>
+ <screen>((<replaceable><source_port></replaceable> XOR <replaceable><dest_port></replaceable>) XOR
+ ((<replaceable><source_IP></replaceable> XOR <replaceable><dest_IP></replaceable>) AND <constant>0xffff</constant>)
+ MODULO <replaceable><slave_count></replaceable>
+ </screen>
+ <para>For fragmented TCP or UDP packets and all other IP protocol traffic, the source and destination port information is omitted. For non-IP traffic, the formula is the same as the <command>layer2</command> transmit hash policy.</para>
+ <para>This policy intends to mimic the behavior of certain switches; particularly, Cisco switches with PFC2 as well as some Foundry and IBM products.</para>
+ <para>The algorithm used by this policy is not 802.3ad compliant.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <userinput>2</userinput> or <userinput>layer2+3</userinput> — Uses a combination of layer2 and layer3 protocol information to generate the hash.</para>
+ <para>Uses XOR of hardware MAC addresses and IP addresses to generate the hash. The formula is:</para>
+ <screen>(((<replaceable><source_IP></replaceable> XOR <replaceable><dest_IP></replaceable>) AND <constant>0xffff</constant>) XOR
+ ( <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>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
</section>
</section>
<section
More information about the docs-commits
mailing list