Bug 492539

Summary:	Deployment Guide should REQUIRE HWADDR field for persistent ethernet device naming
Product:	Red Hat Enterprise Linux 5	Reporter:	Prarit Bhargava <prarit>
Component:	doc-Deployment_Guide	Assignee:	Douglas Silas <dhensley>
Status:	CLOSED CURRENTRELEASE	QA Contact:	Content Services Development <ecs-dev-list>
Severity:	high	Docs Contact:
Priority:	high
Version:	5.4	CC:	dzickus, notting, prarit, syeghiay
Target Milestone:	rc	Keywords:	Documentation
Target Release:	---
Hardware:	All
OS:	Linux
Whiteboard:
Fixed In Version:		Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2009-09-03 16:55:37 UTC	Type:	---
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Prarit Bhargava 2009-03-27 11:01:02 UTC

From http://www.redhat.com/docs/manuals/enterprise/RHEL-5-manual/Deployment_Guide-en-US/s2-networkscripts-interfaces-eth0.html

"  HWADDR=<MAC-address>

    where <MAC-address> is the hardware address of the Ethernet device in the form AA:BB:CC:DD:EE:FF. This directive is useful for machines with multiple NICs to ensure that the interfaces are assigned the correct device names regardless of the configured load order for each NIC's module. This directive should not be used in conjunction with MACADDR.
"

should read

"  HWADDR=<MAC-address>

    where <MAC-address> is the hardware address of the Ethernet device in the form AA:BB:CC:DD:EE:FF. This directive is required for machines with multiple NICs to ensure that the interfaces are assigned the correct device names regardless of the configured load order for each NIC's module. This directive should not be used in conjunction with MACADDR.
"

While there is a Knowledge Base article on this, it seems to me that we get at least one or two BZ reports of flipped ethernet ports every release.  Inevitably, when shown the above comment, the reporter responds with "It only says it is useful, not required."

It would really be nice to be able to point them at the Deployment Guide which has a definitive statement that the HWADDR field is *REQUIRED* for systems with multiple ethernet ports.

A single word change will go a long way here.

P.

Comment 1 Douglas Silas 2009-06-28 04:16:01 UTC

Relevant KBase article is here: http://kbase.redhat.com/faq/docs/DOC-15331

Relevant extract is:

<snip>In order to prevent a system's NICs from being enumerated out of a specific order, it is necessary to use the *HWADDR=* parameter. For example, the following line can be added to any /etc/sysconfig/network-scripts/ifcfg-ethN:

HWADDR=<mac address>

If the "HWADDR=" parameter is not used, intermittent device renaming could occur across reboots.</snip>

Therefore I have changed:

"This directive is useful for machines with multiple NICs to ensure..."

TO:

"This directive should be used in machines containing more than one NIC to ensure..."

...in 5.4.

Comment 2 Prarit Bhargava 2009-06-28 20:59:34 UTC

Can we change it to

"This directive must be used in machines containing more than one NIC to ensure ..." ?

I know I'm being pedantic but I'd rather be as blunt as possible here.  We've seen many BZs from people who seem to think this is optional.

P.

Comment 5 Douglas Silas 2009-09-03 16:55:37 UTC

Prarit, the text in the current Deployment Guide on redhat.com/docs reads"

"This directive should be used..."

http://www.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5.4/html/Deployment_Guide/s1-networkscripts-interfaces.html#s2-networkscripts-interfaces-eth0

Because I agreed with you that little harm, and probably much good, could come from strengthening it to "must", I have changed it again. The next update to the online copy will pick this up.

I am therefore closing this bug.