[deployment-guide] Added "Consistent Network Device Naming" as an appendix.
Jaromir Hradilek
jhradile at fedoraproject.org
Tue Oct 18 16:31:45 UTC 2011
commit 3eb278e1c772d074e098245c89ab02ca38ec57e3
Author: Jaromir Hradilek <jhradile at redhat.com>
Date: Tue Oct 18 18:26:00 2011 +0200
Added "Consistent Network Device Naming" as an appendix.
en-US/Consistent_Network_Device_Naming.xml | 121 ++++++++++++++++++++++++++++
en-US/Deployment_Guide.xml | 1 +
en-US/Network_Interfaces.xml | 13 +++-
en-US/Preface.xml | 8 ++
4 files changed, 140 insertions(+), 3 deletions(-)
---
diff --git a/en-US/Consistent_Network_Device_Naming.xml b/en-US/Consistent_Network_Device_Naming.xml
new file mode 100644
index 0000000..4ccd7d3
--- /dev/null
+++ b/en-US/Consistent_Network_Device_Naming.xml
@@ -0,0 +1,121 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<appendix id="appe-Consistent_Network_Device_Naming">
+ <title>Consistent Network Device Naming</title>
+ <para>
+ &MAJOROSVER; provides consistent network device naming for network interfaces. This feature changes the name of network interfaces on a system in order to make locating and differentiating the interfaces easier.
+ </para>
+ <para>
+ Traditionally, network interfaces in Linux are enumerated as <interfacename>eth[0123…]</interfacename>, but these names do not necessarily correspond to actual labels on the chassis. Modern server platforms with multiple network adapters can encounter non-deterministic and counter-intuitive naming of these interfaces. This affects both network adapters embedded on the motherboard (<firstterm>Lan-on-Motherboard</firstterm>, or <firstterm><acronym>LOM</acronym></firstterm>) and add-in (single and multiport) adapters.
+ </para>
+ <para>
+ The new naming convention assigns names to network interfaces based on their physical location, whether embedded or in PCI slots. By converting to this naming convention, system administrators will no longer have to guess at the physical location of a network port, or modify each system to rename them into some consistent order.
+ </para>
+ <para>
+ This feature, implemented via the <application>biosdevname</application> program, will change the name of all embedded network interfaces, PCI card network interfaces, and virtual function network interfaces from the existing <interfacename>eth[0123…]</interfacename> to the new naming convention as shown in <xref linkend="tabl-Consistent_Network_Device_Naming" />.
+ </para>
+ <table id="tabl-Consistent_Network_Device_Naming">
+ <title>The new naming convention</title>
+ <tgroup cols="3">
+ <colspec colname="device" colnum="1" colwidth="35*" />
+ <colspec colname="old" colnum="2" colwidth="15*" />
+ <colspec colname="new" colnum="3" colwidth="50*" />
+ <thead>
+ <row>
+ <entry>
+ Device
+ </entry>
+ <entry>
+ Old Name
+ </entry>
+ <entry>
+ New Name
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ Embedded network interface (LOM)
+ </entry>
+ <entry>
+ <interfacename>eth[0123…]</interfacename>
+ </entry>
+ <entry>
+ <interfacename>em[1234…]</interfacename><footnote><para>New enumeration starts at <literal>1</literal>.</para></footnote>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ PCI card network interface
+ </entry>
+ <entry>
+ <interfacename>eth[0123…]</interfacename>
+ </entry>
+ <entry>
+ <interfacename>p<<replaceable>slot</replaceable>>p<<replaceable>ethernet port</replaceable>></interfacename><footnote><para>For example: <interfacename>p3p4</interfacename></para></footnote>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ Virtual function
+ </entry>
+ <entry>
+ <interfacename>eth[0123…]</interfacename>
+ </entry>
+ <entry>
+ <interfacename>p<<replaceable>slot</replaceable>>p<<replaceable>ethernet port</replaceable>>_<<replaceable>virtual interface</replaceable>></interfacename><footnote><para>For example: <interfacename>p3p4_1</interfacename></para></footnote>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ System administrators may continue to write rules in <filename>/etc/udev/rules.d/70-persistent-net.rules</filename> to change the device names to anything desired; those will take precedence over this physical location naming convention.
+ </para>
+ <section id="sect-Consistent_Network_Device_Naming-Affected_Systems">
+ <title>Affected Systems</title>
+ <para>
+ Consistent network device naming is enabled by default for all systems that meet the requirements in <xref linkend="sect-Consistent_Network_Device_Naming-System_Requirements" />.
+ </para>
+ <para>
+ Regardless of the type of system, Fedora guests will not have devices renamed unless the virtual machine BIOS provides the SMBIOS information outlined in <xref linkend="sect-Consistent_Network_Device_Naming-System_Requirements" />. Also, upgrades from prior releases that did not use this naming convention (that is, Fedora 14 and older) are unaffected, and the old naming convention will continue to be used.
+ </para>
+ </section>
+ <section id="sect-Consistent_Network_Device_Naming-System_Requirements">
+ <title>System Requirements</title>
+ <para>
+ The <application>biosdevname</application> program uses information from the system's BIOS, specifically the <emphasis>type 9</emphasis> (System Slot) and <emphasis>type 41</emphasis> (Onboard Devices Extended Information) fields contained within the SMBIOS. If the system's BIOS does not have SMBIOS version 2.6 or higher and this data, the new naming convention will not be used. Most older hardware does not support this feature because of a lack of BIOSes with the correct SMBIOS version and field information. For BIOS or SMBIOS version information, contact your hardware vendor.
+ </para>
+ <para>
+ For this feature to take effect, the <package>biosdevname</package> package must also be installed. The <package>biosdevname</package> package is part of the <literal>base</literal> package group in &MAJOROSVER;. All install options, except for <guimenuitem>Minimal Install</guimenuitem>, include this package.
+ </para>
+ </section>
+ <section id="sect-Consistent_Network_Device_Naming-Enabling_and_Disabling">
+ <title>Enabling and Disabling the Feature</title>
+ <para>
+ To disable the consistent network device naming on Dell systems that would normally have it on by default, pass the following option on the boot command line, both during and after installation:
+ </para>
+ <screen><option>biosdevname=0</option></screen>
+ <para>
+ To enable this feature on other system types that meet the minimum requirements (see <xref linkend="sect-Consistent_Network_Device_Naming-System_Requirements" />), pass the following option on the boot command line, both during and after installation:
+ </para>
+ <screen><option>biosdevname=1</option></screen>
+ <para>
+ Unless the system meets the minimum requirements, this option will be ignored and the system will boot with the traditional network interface name format.
+ </para>
+ <para>
+ If the <option>biosdevname</option> install option is specified, it must remain as a boot option for the lifetime of the system.
+ </para>
+ </section>
+ <section id="sect-Consistent_Network_Device_Naming-Notes">
+ <title>Notes for Administrators</title>
+ <para>
+ Many system customization files can include network interface names, and thus will require updates if moving a system from the old convention to the new convention. If you use the new naming convention, you will also need to update network interface names in areas such as custom iptables rules, scripts altering irqbalance, and other similar configuration files. Also, enabling this change for installation will require modification to existing kickstart files that use device names via the <option>ksdevice</option> parameter; these kickstart files will need to be updated to use the network device's MAC address or the network device's new name.
+ </para>
+ <para>
+ &OSORG; strongly recommends that you consider this feature to be an install-time choice; enabling or disabling the feature post-install, while technically possible, can be complicated and is not recommended. For those system administrators who wish to do so, on a system that meets the minimum requirements, remove the <filename>/etc/udev/rules.d/70-persistent-net.rules</filename> file and the <option>HWADDR</option> lines from all <filename>/etc/sysconfig/network-scripts/ifcfg-*</filename> files. In addition, rename those <filename>ifcfg-*</filename> files to use this new naming convention. The new names will be in effect after reboot. Remember to update any custom scripts, iptables rules, and service configuration files that might include network interface names.
+ </para>
+ </section>
+</appendix>
diff --git a/en-US/Deployment_Guide.xml b/en-US/Deployment_Guide.xml
index 1b6869d..45ac172 100644
--- a/en-US/Deployment_Guide.xml
+++ b/en-US/Deployment_Guide.xml
@@ -89,6 +89,7 @@
<xi:include href="The_kdump_Crash_Recovery_Service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</part>
<!-- APPENDIXES -->
+ <xi:include href="Consistent_Network_Device_Naming.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="RPM.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="The_X_Window_System.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="The_sysconfig_Directory.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
diff --git a/en-US/Network_Interfaces.xml b/en-US/Network_Interfaces.xml
index 18ae396..b1d015e 100644
--- a/en-US/Network_Interfaces.xml
+++ b/en-US/Network_Interfaces.xml
@@ -108,10 +108,17 @@
</listitem>
</orderedlist>
--><!-- RHEL5: ddomingo at redhat.com: changed title from "Caution"; minor edits -->
+ <important>
+ <title>Network interface names</title>
+ <para>
+ Network interface names may be different on different hardware types. Refer to <xref linkend="appe-Consistent_Network_Device_Naming" /> for more information.
+ </para>
+ </important>
<warning>
- <title>Warning</title>
- <para>The <filename>/etc/sysconfig/networking/</filename> directory is used by the <application>Network Administration Tool</application> (<command>system-config-network</command>) and its contents should <emphasis
- role="bold">not</emphasis> be edited manually. <!-- RHEL5: ddomingo at redhat.com: string removed as per Harald Hoyer <string> In addition, any use of the <application>Network Administration Tool</application> (even launching the application) will override any directives previously set in <filename>/etc/sysconfig/network-scripts</filename>.</string> -->Using only one method for network configuration is strongly encouraged, due to the risk of configuration deletion.</para>
+ <title>The /etc/sysconfig/networking/ directory</title>
+ <para>
+ The <filename>/etc/sysconfig/networking/</filename> directory is used by the <application>Network Administration Tool</application> (<command>system-config-network</command>) and its contents should <emphasis role="bold">not</emphasis> be edited manually. Using only one method for network configuration is strongly encouraged, due to the risk of configuration deletion.
+ </para>
<!-- jhradilek: TBD F15: Uncomment this as soon as the NetworkManager chapter is updated.
<para>
For more information about configuring network interfaces using the <application>Network Administration Tool</application>, refer to <xref
diff --git a/en-US/Preface.xml b/en-US/Preface.xml
index 55a46ff..dadb5cd 100644
--- a/en-US/Preface.xml
+++ b/en-US/Preface.xml
@@ -179,6 +179,14 @@
</listitem>
</varlistentry>
<varlistentry>
+ <term><xref linkend="appe-Consistent_Network_Device_Naming" /></term>
+ <listitem>
+ <para>
+ This appendix covers consistent network device naming for network interfaces, a feature that changes the name of network interfaces on a system in order to make locating and differentiating the interfaces easier. Read this appendix to learn more about this feature and how to enable or disable it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><xref linkend="ch-RPM" /></term>
<listitem>
<para>
More information about the docs-commits
mailing list