Bug 513330 - DM Multipath docs are wrong: removing features "1 queue_if_no_path" from multipath.conf is not sufficient to disable option for all SANs
Summary: DM Multipath docs are wrong: removing features "1 queue_if_no_path" from mult...
Keywords:
Status: CLOSED NOTABUG
Alias: None
Product: Red Hat Cluster Suite
Classification: Retired
Component: rh-cs-en
Version: 4
Hardware: All
OS: Linux
low
medium
Target Milestone: ---
Assignee: Steven J. Levine
QA Contact: Content Services Development
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2009-07-23 04:29 UTC by John Brier
Modified: 2013-08-14 23:05 UTC (History)
6 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Last Closed: 2009-09-03 16:49:12 UTC
Embargoed:


Attachments (Terms of Use)

Description John Brier 2009-07-23 04:29:31 UTC
Description of problem:

Quoting from DM Multipath Configuration and Administration:

http://www.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5/html/DM_Multipath/queueifnopath_issues.html

===
5.3. Issues with queue_if_no_path feature
If features "1 queue_if_no_path" is specified in the /etc/multipath.conf file, then any process that issues I/O will hang until one or more paths are restored. To avoid this, set the no_path_retry N parameter in the /etc/multipath.conf file (where N is the number of times the system should retry a path). When you do, remove the features "1 queue_if_no_path" option from the /etc/multipath.conf as well. 
===

It is not sufficient to add no_path_retry and remove the features "1 queue_if_no_path" option from /etc/multipath.conf to disable queue_if_no_path for SANs which have this option set as a default compiled into device-mapper-multipath. In this case it is also required to explicitly add features "0" to override this compiled in default.

The documentation should be updated to reflect this.

As of device-mapper-multipath-0.4.7-23.el5_3.4 the /usr/share/doc/device-mapper-multipath-0.4.7/multipath.conf.defaults shows 10 SANs which use this compiled in default. 


Version-Release number of selected component (if applicable):

DM Multipath Configuration and Administration

Edition 3

Bugzilla component: Documentation-cluster
Book identifier: DM_Multipath(EN)-5 (2009-01-06T15:35)

Note this text is also incorrect in the release notes (in fact I think this text originally came from the release notes)
http://www.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5/html/Release_Notes/sect-Release_Notes-Known_Issues.html#id808732

Should another bug be opened on that as well?

Comment 2 Steven J. Levine 2009-08-10 21:29:12 UTC
I sent the following note to Ben Marzinski on August 7, since he is my main contact and reviewer for this project:

Ben:

Please look at Bug 513330 -- it indicates that some information in the multipath manual (which came from the release notes) is not complete.

I don't know if we can update the release notes at this point, but if you can verify this I can get it into the manual next week.

https://bugzilla.redhat.com/show_bug.cgi?id=513330

-Steven

Comment 3 Ben Marzinski 2009-08-12 20:15:34 UTC
The original comment is correct.  If you would like to change the features parameter for a device that has a compiled in default configuration where the  features option is set to

"1 queue_if_no_path"

You must add your override the compiled in devices section for your device with your own. This is usually done by copying the existing devices section for your device from /usr/share/doc/device-mapper-multipath-0.4.7/multipath.conf.defaults into /etc/multipath.conf, and editting it to suit your needs.

Comment 4 Steven J. Levine 2009-08-14 19:48:10 UTC
Ben:

How does this look, then, as a rewrite of the section in question:

--------------------------

5.3. Issues with queue_if_no_path feature

If features "1 queue_if_no_path" is specified in the /etc/multipath.conf file, then any process that issues I/O will hang until one or more paths are restored. To avoid this, set the no_path_retry N parameter in the /etc/multipath.conf file (where N is the number of times the system should retry a path). 

When you set the no_path_retry parameter, remove the
features "1 queue_if_no_path" option from the /etc/multipath.conf
file as well. If, however, you are using a multipathed device for which the
features "1 queue_if_no_path" option is set as a compiled-in default, as it is 
for many SAN devices, you must explicitly add features "0"
to override this default. You can do this by copying the existing devices
section for your device from
/usr/share/doc/device-mapper-multipath-0.4.7/multipath.conf.defaults 
into /etc/multipath.conf and editing it to suit your needs.  

If you need to use the features "1 queue_if_no_path" option and you experience the issue noted here, use the dmsetup command to edit the policy at runtime for a particular LUN (that is, for which all the paths are unavailable). For example, if you want to change the policy on the multipath device mpath2 from "queue_if_no_path" to "fail_if_no_path", execute the following command.

dmsetup message mpath2 0 "fail_if_no_path"

Note that you must specify the mpathn alias rather than the path.

Comment 5 Ben Marzinski 2009-08-14 22:31:26 UTC
Looks great.

Comment 6 Steven J. Levine 2009-09-03 16:49:12 UTC
With the release of RHEL 5.4, I am closing this bug.


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