[gentoo-doc-cvs] gentoo commit in xml/htdocs/doc/en/handbook: hb-install-config.xml hb-install-network.xml hb-net-advanced.xml hb-net-start.xml

[Sven Vermeulen (swift)]

swift       13/05/06 14:24:20

  Modified:             hb-install-config.xml hb-install-network.xml
                        hb-net-advanced.xml hb-net-start.xml
  Log:
  Fix bug #466262 - Document predictable naming of interfaces

Revision  Changes    Path
1.119                xml/htdocs/doc/en/handbook/hb-install-config.xml

file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-install-config.xml?rev=1.119&view=markup
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-install-config.xml?rev=1.119&content-type=text/plain
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-install-config.xml?r1=1.118&r2=1.119

Index: hb-install-config.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-config.xml,v
retrieving revision 1.118
retrieving revision 1.119
diff -u -r1.118 -r1.119
--- hb-install-config.xml	23 Feb 2013 18:38:22 -0000	1.118
+++ hb-install-config.xml	6 May 2013 14:24:20 -0000	1.119
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-config.xml,v 1.118 2013/02/23 18:38:22 swift Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-config.xml,v 1.119 2013/05/06 14:24:20 swift Exp $ -->
 
 <sections>
 
@@ -14,8 +14,8 @@
 proceed.
 </abstract>
 
-<version>24</version>
-<date>2013-02-23</date>
+<version>25</version>
+<date>2013-05-06</date>
 
 <section>
 <title>Filesystem Information</title>
@@ -298,6 +298,13 @@
 to set both <c>config_eth0</c> and <c>routes_eth0</c>:
 </p>
 
+<note>
+This assumes that your network interface will be called eth0. This is, however,
+very system dependent. It is recommended to assume that the interface is named
+the same as the interface name when booted from the installation media <e>if</e>
+the installation media is sufficiently recent. 
+</note>
+
 <pre caption="Manually setting IP information for eth0">
 config_eth0="192.168.0.2 netmask 255.255.255.0 brd 192.168.0.255"
 routes_eth0="default via 192.168.0.1"
@@ -345,10 +352,33 @@
 
 <p>
 If you have several network interfaces, you need to create the appropriate
-<path>net.eth1</path>, <path>net.eth2</path> etc. just like you did with
-<path>net.eth0</path>.
+<path>net.*</path> files just like you did with <path>net.eth0</path>.
 </p>
 
+<p>
+If you later find out the assumption about the network interface name (which we
+currently document as eth0) was wrong, then
+</p>
+
+<ol>
+<li>
+update the <path>/etc/conf.d/net</path> file with the correct interface name (like enp3s0
+instead of eth0),
+</li>
+<li>
+create new symbolic link (like <path>/etc/init.d/net.enp3s0</path>),
+</li>
+<li>
+remove the old symbolic link (<c>rm /etc/init.d/net.eth0</c>), 
+</li>
+<li>
+add the new one to the default runlevel, and
+</li>
+<li>
+remove the old one using <c>rc-update del net.eth0 default</c>.
+</li>
+</ol>
+
 </body>
 </subsection>
 <subsection>



1.57                 xml/htdocs/doc/en/handbook/hb-install-network.xml

file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-install-network.xml?rev=1.57&view=markup
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-install-network.xml?rev=1.57&content-type=text/plain
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-install-network.xml?r1=1.56&r2=1.57

Index: hb-install-network.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-network.xml,v
retrieving revision 1.56
retrieving revision 1.57
diff -u -r1.56 -r1.57
--- hb-install-network.xml	14 Jan 2013 06:00:45 -0000	1.56
+++ hb-install-network.xml	6 May 2013 14:24:20 -0000	1.57
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-network.xml,v 1.56 2013/01/14 06:00:45 nightmorph Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-network.xml,v 1.57 2013/05/06 14:24:20 swift Exp $ -->
 
 <sections>
 
@@ -13,8 +13,8 @@
 networking.
 </abstract>
 
-<version>6</version>
-<date>2013-01-12</date>
+<version>7</version>
+<date>2013-05-06</date>
 
 <section>
 <title>Automatic Network Detection</title>
@@ -50,6 +50,18 @@
           Interrupt:11 Base address:0xe800 
 </pre>
 
+<p>
+The interface name on your system can be quite different from eth0. Recent
+installation media might show regular network interfaces names like eno0, ens1
+or enp5s0. Just seek the interface in the <c>ifconfig</c> output that has an IP
+address related to your local network.
+</p>
+
+<p>
+In the remainder of this document, we will assume that the interface is called
+eth0.
+</p>
+
 </body>
 </subsection>
 <subsection>
@@ -291,7 +303,8 @@
 
 <p>
 To check if your network card is now detected, use <c>ifconfig</c>. A
-detected network card would result in something like this:
+detected network card would result in something like this (again, eth0 here is
+just an example):
 </p>
 
 <pre caption="Testing availability of your network card, successful">
@@ -315,10 +328,18 @@
 </pre>
 
 <p>
-If you have multiple network cards in your system they are named <e>eth0</e>,
-<e>eth1</e>, etc. Make sure that the network card you want to use works well and
-remember to use the correct naming throughout this document. We will assume that
-the network card <e>eth0</e> is used.
+The available network interface names on your system can be listed through the
+<path>/sys</path> file system:
+</p>
+
+<pre caption="Viewing the available network interfaces">
+# <i>ls /sys/class/net</i>
+dummy0  eth0  lo  sit0  tap0  wlan0
+</pre>
+
+<p>
+In the above example, 6 interfaces are found. The eth0 one is most likely the
+(wired) Ethernet adapter whereas wlan0 is the wireless one. 
 </p>
 
 <p>



1.19                 xml/htdocs/doc/en/handbook/hb-net-advanced.xml

file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-net-advanced.xml?rev=1.19&view=markup
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-net-advanced.xml?rev=1.19&content-type=text/plain
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-net-advanced.xml?r1=1.18&r2=1.19

Index: hb-net-advanced.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-advanced.xml,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- hb-net-advanced.xml	19 Aug 2011 16:07:30 -0000	1.18
+++ hb-net-advanced.xml	6 May 2013 14:24:20 -0000	1.19
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-advanced.xml,v 1.18 2011/08/19 16:07:30 swift Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-advanced.xml,v 1.19 2013/05/06 14:24:20 swift Exp $ -->
 
 <sections>
 
@@ -13,8 +13,8 @@
 before we learn about modular networking.
 </abstract>
 
-<version>11</version>
-<date>2011-08-19</date>
+<version>12</version>
+<date>2013-05-06</date>
 
 <section>
 <title>Advanced Configuration</title>
@@ -229,4 +229,134 @@
 
 </body>
 </section>
+<section>
+<title>Network Interface Naming</title>
+<subsection>
+<title>How It Works</title>
+<body>
+
+<p>
+Network interface names are not chosen arbitrarily: the Linux kernel and the
+device manager (most sytems have udev as their device manager although others
+are available as well) choose the interface name through a fixed set of rules.
+</p>
+
+<p>
+When an interface card is detected on a system, the Linux kernel gathers the
+necessary data about this card. This includes:
+</p>
+
+<ol>
+  <li>
+    the onboard (on the interface itself) registered name of the network card,
+    which is later seen through the <c>ID_NET_NAME_ONBARD</c> parameter;
+  </li>
+  <li>
+    the slot in which the network card is plugged in, which is later seen
+    through the <c>ID_NET_NAME_SLOT</c> parameter; 
+  </li>
+  <li>
+    the path through which the network card device can be accessed, which is
+    later seen through the <c>ID_NET_NAME_PATH</c> parameter;
+  </li>
+  <li>
+    the (vendor-provided) MAC address of the card, which is later seen through
+    the <c>ID_NET_NAME_MAC</c> parameter;
+  </li>
+</ol>
+
+<p>
+Based on this information, the device manager decides how to name the interface
+on the system. By default, it uses the first hit of the above three parameters.
+For instance, if <c>ID_NET_NAME_ONBARD</c> is found and set to <c>eno1</c>, then
+the interface will be called eno1.
+</p>
+
+<p>
+If you know your interface name, you can see the values of the provided
+parameters using <c>udevadm</c>:
+</p>
+
+<pre caption="Reading the network interface card information">
+# <i>udevadm test-builtin net_id /sys/class/net/enp3s0 2>/dev/null</i>
+ID_NET_NAME_MAC=enxc80aa9429d76
+ID_OUI_FROM_DATABASE=Quanta Computer Inc.
+ID_NET_NAME_PATH=enp3s0
+</pre>
+
+<p>
+As the first (and actually only) hit of the top three parameters is the
+<c>ID_NET_NAME_PATH</c> one, its value is used as the interface name. If none of
+the parameters is found, then the system reverts back to the kernel-provided
+naming (eth0, eth1, etc.)
+</p>
+
+</body>
+</subsection>
+<subsection>
+<title>Using the Old-style Kernel Naming</title>
+<body>
+
+<p>
+Before this change, network interface cards were named by the Linux kernel
+itself, depending on the order that drivers are loaded (amongst other, possibly
+more obscure reasons). This behavior can still be enabled by setting the
+<c>net.ifnames=0</c> boot option in the boot loader.
+</p>
+
+<p>
+Another way of disabling this behavior (and thus reverting back to the
+kernel-provided naming) is to create an empty udev rule named
+<path>80-net-name-slot.rules</path> which will then override the default
+provided one (with the same name) that is responsible for taking care of network
+interface naming.
+</p>
+
+<pre caption="Overriding the network naming scheme">
+# <i>ln -s /dev/null /etc/udev/rules.d/80-net-name-slot.rules</i>
+</pre>
+
+</body>
+</subsection>
+<subsection>
+<title>Using your Own Names</title>
+<body>
+
+<p>
+The entire idea behind the change in naming is not to confuse people, but to
+make changing the names easier. Suppose you have two interfaces that are
+otherwise called eth0 and eth1. One is meant to access the network through a
+wire, the other one is for wireless access. With the support for interface
+naming, you can have these called lan0 (wired) and wifi0 (wireless - it is best
+to avoid using the previously well-known names like eth* and wlan* as those can
+still collide with your suggested names).
+</p>
+
+<p>
+All you need to do is to find out what the parameters are for the cards and then
+use this information to set up your own naming rule:
+</p>
+
+<pre caption="Setting the lan0 name for the current eth0 interface">
+# <i>udevadm test-builtin net_id /sys/class/net/eth0 2>/dev/null</i>
+ID_NET_NAME_MAC=enxc80aa9429d76
+ID_OUI_FROM_DATABASE=Quanta Computer Inc.
+
+# <i>vim /etc/udev/rules.d/70-net-name-use-custom.rules</i>
+<comment># First one uses MAC information</comment>
+SUBSYSTEM=="net", ACTION=="add", ENV{ID_NET_NAME_MAC}=="enxc80aa9429d76", NAME="lan0"
+<comment># Second one uses ID_NET_NAME_PATH information</comment>
+SUBSYSTEM=="net", ACTION=="add", ENV{ID_NET_NAME_PATH}=="enp3s0", NAME="wifi0"
+</pre>
+
+<p>
+Because the rules are triggered before the default one (rules are triggered in
+alphanumerical order, so 70 comes before 80) the names provided in the rule file
+will be used instead of the default ones.
+</p>
+
+</body>
+</subsection>
+</section>
+
 </sections>



1.12                 xml/htdocs/doc/en/handbook/hb-net-start.xml

file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-net-start.xml?rev=1.12&view=markup
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-net-start.xml?rev=1.12&content-type=text/plain
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-net-start.xml?r1=1.11&r2=1.12

Index: hb-net-start.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-start.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- hb-net-start.xml	29 Jun 2012 15:32:13 -0000	1.11
+++ hb-net-start.xml	6 May 2013 14:24:20 -0000	1.12
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-start.xml,v 1.11 2012/06/29 15:32:13 swift Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-start.xml,v 1.12 2013/05/06 14:24:20 swift Exp $ -->
 
 <sections>
 
@@ -13,8 +13,8 @@
 environments.
 </abstract>
 
-<version>10</version>
-<date>2012-06-29</date>
+<version>11</version>
+<date>2013-05-06</date>
 
 <section>
 <title>Getting started</title>
@@ -24,13 +24,14 @@
 This document assumes that you have correctly configured your kernel, its
 modules for your hardware and you know the interface name of your hardware.
 We also assume that you are configuring <c>eth0</c>, but it could also be
-<c>eth1</c>, <c>wlan0</c>, etc.
+<c>eno0</c>, <c>ens1</c>, <c>wlan0</c>, <c>enp1s0</c> etc.
 </note>
 
 <p>
 To get started configuring your network card, you need to tell the Gentoo RC
 system about it. This is done by creating a symbolic link from
-<path>net.lo</path> to <path>net.eth0</path> in <path>/etc/init.d</path>.
+<path>net.lo</path> to <path>net.eth0</path> (or whatever the network interface
+name is on your system) in <path>/etc/init.d</path>.
 </p>
 
 <pre caption="Symlinking net.eth0 to net.lo">