View source for Changing the ethX to Ethernet Device Mapping in EL6

{{howto_header}}

'''Note''': This paper is written for Red Hat Enterprise Linux 6, but should be directly adaptable to derivative distributions like [[CentOS]] 6 and [[Scientific Linux]] 6.

= Overview =

It is very difficult to configure which physical network cards get what network device names during installation . This document will show you how to change the <span class="code">ethX</span> device name assigned to each physical network interface using [[MAC]] addresses.

This is desirable in cases where specific network cards need to be used on specific networks, and you are interested in maintaining common <span class="code">ethX</span> names across servers. A practical example is found in the [[Red Hat Cluster Service 3 Tutorial]].

= For the Impatient =

Assuming that <span class="code">NetworkManager</span> is already disabled.

Stop the existing network. This is critical as you must stop the network using it's existing configuration '''before''' making changes. If you skip this step you may need to restart your server when you are done.

<source lang="bash">
/etc/init.d/network stop
</source>

Edit each network configuration file and comment out the <span class="code">HWADDR="..."</span> and, if it exists, the <span class="code">UUID="..."</span> lines.

<source lang="bash">
vim /etc/sysconfig/network-scripts/ifcfg-eth*
</source>

Edit the <span class="code">[[udev]]</span> network rules file and change the <span class="code">NAME="..."</span> entries to the <span class="code">ethX</span> name you want for the relevant entries.

<source lang="bash">
vim /etc/udev/rules.d/70-persistent-net.rules
</source>

Reload <span class="code">udev</span> and start networking.

<source lang="bash">
start_udev
/etc/init.d/network start
</source>

= Example =

I find it easier to follow instructions when I have an example to follow, so let me provide one here:

I've got the same hardware in the same configuration in both of my [[Red Hat Cluster Service 3 Tutorial#Hardware|storage nodes]]. To keep things simple, I want to make sure that both nodes use the same <span class="code">ethX</span> name for the network devices on each of the given networks. 

== Desired Mapping ==

Let's assume that you want the following configuration. The comments are meant to help you follow the devices as they move and are of no inherent value.

* <span class="code">eth0</span>
** Type: <span class="code"># Realtek onboard NIC</span>
** MAC: <span class="code">90:E6:BA:71:82:EA</span>
* <span class="code">eth1</span>
** Type: <span class="code"># D-Link PCIe gigabit, center</span>
** MAC: <span class="code">00:21:91:19:96:53</span>
* <span class="code">eth2</span>
** Type: <span class="code"># Intel PCI gigabit, left-most</span>
** MAC: <span class="code">00:0E:0C:59:46:E4</span>

== Initial Mapping ==

When the Fedora install finished, you may have gotten this:

* <span class="code">eth0</span>
** Type: <span class="code"># D-Link PCIe gigabit, center</span>
** MAC: <span class="code">00:21:91:19:96:53</span>
* <span class="code">eth1</span>
** Type: <span class="code"># Realtek onboard NIC</span>
** MAC: <span class="code">90:E6:BA:71:82:EA</span>
* <span class="code">eth2</span>
** Type: <span class="code"># Intel PCI gigabit, left-most</span>
** MAC: <span class="code">00:0E:0C:59:46:E4</span>

== The Problem ==

In the above example, <span class="code">eth0</span> and <span class="code">eth1</span> are reversed. The <span class="code">eth2</span> interface is where we want it, so we leave it alone.

== The Fix ==

Traditionally, the <span class="code">ethX</span> to physical ethernet device was linked via the <span class="code">HWADDR="..."</span> argument in each NIC's <span class="code">ifcfg-ethX</span> configuration file. With the introduction of [http://en.wikipedia.org/wiki/Udev udev], the <span class="code">HWADDR="..."</span> is no longer needed. Instead, this mapping is now made in the <span class="code">70-persistent-net.rules</span> udev configuration file. 

So the trick then is to remove or comment-out the <span class="code">HWADDR="..."</span> and <span class="code">UUID="..."</span> argument(s) in each NIC's <span class="code">ifcfg-ethX</span> configuration file, then, change the <span class="code">NAME="ethX"</span> in the udev configuration file to match the MAC address you want.

== Stopping the Network ==

First, stop the <span class="code">network</span>. This is important because if you change the MAC address to <span class="code">ethX</span> mapping while the network is still up, the <span class="code">init.d</span> script will fail to bring down the network devices and you will need to reboot for the changes to take effect.

<source lang="bash">
/etc/init.d/network stop
</source>
<source lang="text">
Shutting down interface eth0:                              [  OK  ]
Shutting down interface eth1:                              [  OK  ]
Shutting down loopback interface:                          [  OK  ]
</source>

'''Note''': The <span class="code">eth2</span> interface is not yet set to start with the system, so didn't need to be stopped.

== Interface Configuration ==

'''Note''': Though technically fine, I personally find the default configuration of the network interfaces to be sloppy and inconsistent. I like to take this step to also clean up these files and set them to the values I want. In this step I will set the interfaces to match <span class="code">[[Red_Hat_Cluster_Service_3_Tutorial#Node_IP_Addresses|an-node01]]</span> from the [[Red Hat Cluster Service 3 Tutorial]]. Feel free to adapt the configurations to suit your needs and networks.

Go to the <span class="code">/etc/sysconfig/network-scripts/</span> directory and then edit the <span class="code">ifcfg-eth*</span> network configuration files. Below are examples of the interface configurations "before" and "after" the changes. Note that the only edit that really matters is that the <span class="code">HWADDR="..."</span> lines are commented out. In my case, there were no <span class="code">UUID="..."</span> entries.

=== Network Config File Syntax ===

For an exhaustive list of available options in <span class="code">ifcfg-ethX</span> files, please [http://docs.fedoraproject.org/en-US/Fedora/12/html/Deployment_Guide/s1-networkscripts-interfaces.html see the Fedora documentation]. 

For a fully up to date, if somewhat sparse, list of available options, please consult the <span class="code">sysconfig</span> documentation shipped with your distribution. For Red Hat Enterprise Linux 6.0, this can be found at <span class="code">/usr/share/doc/initscripts-9.03.17/sysconfig.txt</span> under the <span class="code">Files in /etc/sysconfig/network-scripts/</span> section. Specifically, look at the <span class="code">/etc/sysconfig/network-scripts/ifcfg-<interface-name></span> sub-section.

=== /etc/sysconfig/network-scripts/ifcfg-eth0 ===

First up, <span class="code">eth0</span>.

<source lang="bash">
vim /etc/sysconfig/network-scripts/ifcfg-eth0
</source>

The file original looked like this: 

<source lang="text">
DEVICE="eth0"
BOOTPROTO="dhcp"
DHCP_HOSTNAME="an-node01.alteeve.ca"
HWADDR="00:21:91:19:96:53"
NM_CONTROLLED="yes"
ONBOOT="yes"
</source>

I like to keep the MAC address in the file to act as a reference for when I am working with the files. For this reason, I change the <span class="code">HWADDR="..."</span> entry despite commenting it out. I also like to add a <span class="code">NAME="..."</span> entry and a descriptive comment at the head of the file. Again though, all of this is optional. All that really matters is that <span class="code">HWADDR</span> and <span class="code">UUID</span> are gone.

<source lang="text">
# Realtek onboard NIC "blue" network
#HWADDR=90:E6:BA:71:82:EA
DEVICE="eth0"
NAME="Internet Facing Network eth0"
ONBOOT="yes"
NM_CONTROLLED="no"
TYPE=Ethernet
BOOTPROTO=none
IPV4_FAILURE_FATAL=yes
IPV6INIT=no
DEFROUTE=yes
IPADDR=192.168.1.71
NETMASK=255.255.255.0
GATEWAY=192.168.1.254
DNS1=192.139.81.117
DNS2=192.139.81.1
DOMAIN=alteeve.ca
</source>

=== /etc/sysconfig/network-scripts/ifcfg-eth1 ===

As with <span class="code">eth0</span>, all that matters is that <span class="code">HWADDR</span> and <span class="code">UUID</span> are gone. As before though, I like to use this time to clean up the file. 

<source lang="bash">
vim /etc/sysconfig/network-scripts/ifcfg-eth0
</source>

The file originally looked like this:

<source lang="text">
DEVICE="eth1"
BOOTPROTO="dhcp"
DHCP_HOSTNAME="an-node01.alteeve.ca"
HWADDR="90:E6:BA:71:82:EA"
NM_CONTROLLED="yes"
ONBOOT="yes"
</source>

As before, I updated and the commented-out the <span class="code">HWADDR="..."</span> line to act as a reference.

<source lang="text">
# D-Link PCIe gigabit, center "green" network
#HWADDR=00:21:91:19:96:53
DEVICE="eth1"
NAME="Storage Network eth1"
ONBOOT="yes"
NM_CONTROLLED="no"
TYPE=Ethernet
BOOTPROTO=none
IPV4_FAILURE_FATAL=yes
IPV6INIT=no
DEFROUTE=no
IPADDR=192.168.2.71
NETMASK=255.255.255.0
</source>

=== /etc/sysconfig/network-scripts/ifcfg-eth2 ===

Technically speaking, the <span class="code">HWADDR="..."</span> doesn't need to be removed, if it agrees with the entry in <span class="code">/etc/udev/rules.d/70-persistent-net.rules</span>. For this reason, given this example, there is no strict need to edit this file. However, being somewhat [http://en.wikipedia.org/wiki/Ocd OCD]ish, I like to clean the file up to match the others. Also, in my case, this device was not set to start with the system. This is a great time to sort that out.

<source lang="bash">
vim /etc/sysconfig/network-scripts/ifcfg-eth2
</source>

The original was quite minimal.

<source lang="text">
DEVICE="eth2"
HWADDR="00:0E:0C:59:46:E4"
NM_CONTROLLED="yes"
ONBOOT="no"
</source>

Now it's in-line with the other two configuration files.

<source lang="text">
# Intel PCI gigabit, left-most "black" network
#HWADDR=00:0E:0C:59:46:E4
DEVICE="eth2"
NAME="Back Channel Network eth2"
ONBOOT="yes"
NM_CONTROLLED="no"
TYPE=Ethernet
BOOTPROTO=none
IPV4_FAILURE_FATAL=yes
IPV6INIT=no
DEFROUTE=no
IPADDR=192.168.3.71
NETMASK=255.255.255.0
</source>

== Modifying The udev Configuration ==

The user-space device manager, [http://en.wikipedia.org/wiki/Udev udev], maintains a list of configuration files that help ensure that hardware to <span class="code">/dev</span> (software) mappings stay consistent, even when hardware is hot swapped or moved between physical interfaces. For networking hardware, this mapping is recorded in the <span class="code">70-persistent-net.rules</span> file.

Here, all that needs to be done is for the <span class="code">NAME="..."</span> entry to be changed to be the <span class="code">ethX</span> device you want associated with the given MAC address seen in the corresponding <span class="code">ATTR{address}=="..."</span> entry.

'''Note''': The entries do not need to be in any particular order.

Edit the <span class="code">70-persistent-net.rules</span>.

<source lang="bash">
vim /etc/udev/rules.d/70-persistent-net.rules
</source>

The complete file originally was as follows.

<source lang="text">
# This file was automatically generated by the /lib/udev/write_net_rules
# program, run by the persistent-net-generator.rules rules file.
#
# You can modify it, as long as you keep each rule on a single
# line, and change only the value of the NAME= key.

# PCI device 0x10ec:0x8168 (r8169) (custom name provided by external tool)
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="90:e6:ba:71:82:ea", ATTR{type}=="1", KERNEL=="eth*", NAME="eth1"

# PCI device 0x8086:0x100e (e1000) (custom name provided by external tool)
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="00:0e:0c:59:46:e4", ATTR{type}=="1", KERNEL=="eth*", NAME="eth2"

# PCI device 0x1186:0x4b00 (sky2) (custom name provided by external tool)
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="00:21:91:19:96:53", ATTR{type}=="1", KERNEL=="eth*", NAME="eth0"
</source>

The only change was to the first and third entries.

<source lang="text">
# This file was automatically generated by the /lib/udev/write_net_rules
# program, run by the persistent-net-generator.rules rules file.
#
# You can modify it, as long as you keep each rule on a single
# line, and change only the value of the NAME= key.

# PCI device 0x10ec:0x8168 (r8169) (custom name provided by external tool)
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="90:e6:ba:71:82:ea", ATTR{type}=="1", KERNEL=="eth*", NAME="eth0"

# PCI device 0x8086:0x100e (e1000) (custom name provided by external tool)
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="00:0e:0c:59:46:e4", ATTR{type}=="1", KERNEL=="eth*", NAME="eth2"

# PCI device 0x1186:0x4b00 (sky2) (custom name provided by external tool)
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="00:21:91:19:96:53", ATTR{type}=="1", KERNEL=="eth*", NAME="eth1"
</source>

== Making the Changes Take Effect ==

First, you need to reload <span class="code">udev</span> so that it updates the mapping in memory. This is done using the <span class="code">start_udev</span> command.

<source lang="bash">
start_udev
</source>
<source lang="text">
Starting udev:                                             [  OK  ]
</source>

With <span class="code">udev</span> updated, the final step is to start <span class="code">network</span> back up.

<source lang="bash">
/etc/init.d/network start
</source>
<source lang="text">
Bringing up loopback interface:                            [  OK  ]
Bringing up interface eth0:                                [  OK  ]
Bringing up interface eth1:                                [  OK  ]
Bringing up interface eth2:                                [  OK  ]
</source>

Use <span class="code">ifconfig</span> to verify that the network cards are properly assigned to the specified <span class="code">ethX</span> names.

<source lang="bash">
ifconfig
</source>
<source lang="text">
eth0      Link encap:Ethernet  HWaddr 90:E6:BA:71:82:EA  
          inet addr:192.168.1.71  Bcast:192.168.1.255  Mask:255.255.255.0
          inet6 addr: fe80::92e6:baff:fe71:82ea/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:2478 errors:0 dropped:0 overruns:0 frame:0
          TX packets:1301 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:272436 (266.0 KiB)  TX bytes:245173 (239.4 KiB)
          Interrupt:28 Base address:0x6000 

eth1      Link encap:Ethernet  HWaddr 00:21:91:19:96:53  
          inet addr:192.168.2.71  Bcast:192.168.2.255  Mask:255.255.255.0
          inet6 addr: fe80::221:91ff:fe19:9653/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:53 errors:0 dropped:0 overruns:0 frame:0
          TX packets:56 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:12144 (11.8 KiB)  TX bytes:10693 (10.4 KiB)
          Interrupt:18 

eth2      Link encap:Ethernet  HWaddr 00:0E:0C:59:46:E4  
          inet addr:192.168.3.71  Bcast:192.168.3.255  Mask:255.255.255.0
          inet6 addr: fe80::20e:cff:fe59:46e4/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:83 errors:0 dropped:0 overruns:0 frame:0
          TX packets:47 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:22960 (22.4 KiB)  TX bytes:8191 (7.9 KiB)

lo        Link encap:Local Loopback  
          inet addr:127.0.0.1  Mask:255.0.0.0
          inet6 addr: ::1/128 Scope:Host
          UP LOOPBACK RUNNING  MTU:16436  Metric:1
          RX packets:8 errors:0 dropped:0 overruns:0 frame:0
          TX packets:8 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0 
          RX bytes:480 (480.0 b)  TX bytes:480 (480.0 b)
</source>

Confirm that the <span class="code">HWaddr ...</span> are where you want them.

Done!

== Caveat! ==

'''''NOTE''''': If you are using a [[VLAN]], the device facing the VLAN '''can not''' have the '''HWADDR=...''' value set! Technically speaking, the <span class="code">HWADDR="..."</span> entries may exist, as noted in the <span class="code">eth2</span> section above. However, if this is left in for the VLAN interface, the OS will not see the physical device and will fail to bring up the interface at all.

= Thanks =

* Thanks to <span class="code">fenris02</span> and <span class="code">mutk</span> on the <span class="code">#fedora</span> [[IRC]] channel for helping me sort out the <span class="code">udev</span> component.
* Thanks to <span class="code">Fiver-</span> and <span class="code">inode0</span> on the <span class="code">#rhel</span> IRC channel for helping me find the <span class="code">sysconfig</span> documentation.

{{footer}}