Bug 856681 - Inappropriate use of "must" where "can" is OK
Inappropriate use of "must" where "can" is OK
Status: CLOSED CURRENTRELEASE
Product: Red Hat Enterprise Linux 6
Classification: Red Hat
Component: doc-Cluster_Administration (Show other bugs)
6.3
Unspecified Unspecified
unspecified Severity unspecified
: rc
: ---
Assigned To: Steven J. Levine
ecs-bugs
: Documentation
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2012-09-12 10:54 EDT by Jan Pokorný
Modified: 2013-02-25 12:03 EST (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2013-02-25 12:03:10 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Jan Pokorný 2012-09-12 10:54:30 EDT
5.10. Adding a Cluster Service to the Cluster

To verify the existence of the IP service resource used in a cluster
service, you >>must<< use the /sbin/ip addr list command on a cluster
node.

This is not true as this information should be available, e.g., via
(admittedly obsolete) ifconfig command.  Hence, "can" is more
approriate here.
Comment 1 Jan Pokorný 2012-09-12 14:19:08 EDT
OK, ifconfig is not an option, but "hostname -I" is.
Comment 2 Jan Pokorný 2012-09-13 05:21:40 EDT
Re comment 1:

Maybe adding a parenthesised
--
obsoleted <code>ifconfig</code> is not capable of listing such IP
--
to the end of the referenced sentence would be suitable to prevent
confusion for people still using this instead of current "ip" tool.

References:
- http://arstechnica.com/civis/viewtopic.php?p=22890577#p22890577
- man ifconfig ("This program is obsolete!")
- own experience (with RHEL 6.3, IP configured within the cluster's
  service group will not show up, unlike with "ip addr")
Comment 3 Jan Pokorný 2012-09-13 05:29:47 EDT
Another point, please consider using canonical "ip addr show" instead
of "ip addr list".  Admittedly, both is treated equally by the tool.

References:
- man ip
- ip help, ip addr help
Comment 4 Jan Pokorný 2012-09-13 05:32:41 EDT
Please note there is another instance of using ip addr list,
3.10. Adding a Cluster Service to the Cluster.
Comment 5 Steven J. Levine 2012-09-26 16:41:23 EDT
In my current 6.4 draft, I have updated all 4 occurences of "ip addr list" to "ip addr show". I have also changed the word "must" to "can" in both places.

As to calling out the obsoleted ifconfig, I'm not sure about that yet. The manuals document the current state of the software, rather than what we used to support and what we may support in the future, so I'm cautious about calling out a no-longer-supported command. I'm guessing that whoever originally wrote this section used the word "must" to indicate that you use "ip addr" rather than "ifconfig", but even with changing that to "can" you still are using this section to indicate that this is the command you use to verify the existence of an IP service, which should address the issue.

So I'm considering what to do here.
Comment 6 Steven J. Levine 2012-09-26 16:42:32 EDT
Hmmm...

Maybe:

To verify the existence of the IP service resource used in a
cluster service, you can use the <command>/sbin/ip addr
show</command> command on a cluster node (rather than the obsoleted
<command>ifconfig</command>.

Would that address this?
Comment 7 Jan Pokorný 2012-09-27 14:45:42 EDT
Technical point is that ifconfig is capable to show only primary
IP address while ip addr shows all configured IP aliases.

My intention was to keep the idea not to use ifconfig (which was
why "must" was used, I guess), while making clear it is not the
only way to get other than primary IP address (e.g., mentioned
hostname command).

Being careful about marking something as obsolete is absolutely
correct approach, but looking into my RHCE book for RHEL 6
(dated 2011-07-29), at the end of section about IP aliases,
I read:

> Important
> Avoid using the obsolete ifconfig command. [...]

This probably makes it clear and proposal in [comment 6] is
completely right, then.
Comment 8 Steven J. Levine 2012-10-11 03:13:53 EDT
I have made the changes noted in comment 6 both places the sentence occurs in the document. I have checked this in to the svn repository and will move this to ON_QA at the next build.

Note You need to log in before you can comment on or make changes to this bug.