multipath-tools: clean up man pages
v2 cover multipath-tools: clean up man pages
It performs general cleanups, updates, and formatting fixes across the man pages, incorporating feedback from Martin and Ben.
Please let me know if further adjustments are needed.
v2:
- Merge "clean up man pages" and "clean up man pages II" series into one batch (requested by Martin).
- (5/8) fix typo, s/group/groups (spotted by Martin).
- (7/8) fix copy-paste typo and delete <n>, changing "\IBmpath<n>\fR" to "\fImpath\fR" (spotted by Martin).
Xose Vazquez Perez (8):
multipath-tools: delete obsolete information from multipath.conf.5
multipath-tools: remove explicit width from .TP macros in multipath.conf.5
multipath-tools: remove explicit widths from macros in the remaining man pages
multipath-tools: remove syntax check comments from man pages
multipath-tools: clarify path selector descriptions in multipath.conf.5
multipath-tools: specify file paths using variables and add FILES section in multipath.conf.5
multipath-tools: clarify user_friendly_names prefix behavior in multipath.conf.5
multipath-tools: fix mandoc errors/warnings in man pages
kpartx/kpartx.8 | 4 - libmpathpersist/mpath_persistent_reserve_in.3 | 9 +- .../mpath_persistent_reserve_out.3 | 9 +- mpathpersist/mpathpersist.8.in | 8 +- multipath/multipath.8.in | 10 +- multipath/multipath.conf.5.in | 216 ++++++++---------- multipathd/multipathc.8 | 6 +- multipathd/multipathd.8.in | 14 +- 8 files changed, 102 insertions(+), 174 deletions(-)
Signature · 1 line
2.54.0
PATCH v2 1/8 multipath-tools: delete obsolete information from multipath.conf.5
repeat_count (rr_min_io, rr_min_io_rq, rr_weight) has been unsupported since kernel 4.6 ( commits 90a4323ccfea and 21136f89d76d ).
And also clean up other deprecated entries.
--- multipath/multipath.conf.5.in | 69 +++-------------------------------- 1 file changed, 6 insertions(+), 63 deletions(-)
multipath/multipath.conf.5.in +6 -63
@@ -6,7 +6,7 @@ .\" Update the date below if you make any significant change. .\" ---------------------------------------------------------------------------- . -.TH MULTIPATH.CONF 5 2025-09-12 Linux +.TH MULTIPATH.CONF 5 2026-05-27 Linux . . .\" ----------------------------------------------------------------------------
@@ -198,9 +198,8 @@ kernel multipath target: .TP 12 .I "round-robin 0" Choose the path for the next bunch of I/O by looping through every path in the -path group, sending \fBthe same number of I/O requests\fR to each path. Some -aspects of behavior can be controlled with the attributes: \fIrr_min_io\fR, -\fIrr_min_io_rq\fR and \fIrr_weight\fR. +path group, sending \fBthe same number of I/O requests\fR to each path. + .TP .I "queue-length 0" (Since 2.6.31 kernel) Choose the path for the next bunch of I/O based on \fBthe lowest
@@ -598,24 +597,12 @@ The default is: \fBmanual\fR . .TP .B rr_min_io -Number of I/O requests to route to a path before switching to the next in the -same path group. This is only for \fIBlock I/O\fR(BIO) based multipath and -only apply to \fIround-robin\fR path_selector. -.RS -.TP -The default is: \fB1000\fR -.RE +(Deprecated since kernel 4.6) This option is not supported anymore, and will be ignored. . . .TP .B rr_min_io_rq -Number of I/O requests to route to a path before switching to the next in the -same path group. This is only for \fIRequest\fR based multipath and -only apply to \fIround-robin\fR path_selector. -.RS -.TP -The default is: \fB1\fR -.RE +(Deprecated since kernel 4.6) This option is not supported anymore, and will be ignored. . . .TP
@@ -634,16 +621,7 @@ The default is: \fBmax\fR . .TP .B rr_weight -If set to \fIpriorities\fR the multipath configurator will assign path weights -as "path prio * rr_min_io". Possible values are -.I priorities -or -.I uniform . -Only apply to \fIround-robin\fR path_selector. -.RS -.TP -The default is: \fBuniform\fR -.RE +(Deprecated since kernel 4.6) This option is not supported anymore, and will be ignored. . . .TP
@@ -821,28 +799,16 @@ The default is: \fB<unset>\fR .TP .B bindings_file (Deprecated) This option is not supported anymore, and will be ignored. -.RS -.TP -The compiled-in value is: \fB@STATE_DIR@/bindings\fR -.RE . . .TP .B wwids_file (Deprecated) This option is not supported anymore, and will be ignored. -.RS -.TP -The compiled-in value is: \fB@STATE_DIR@/wwids\fR -.RE . . .TP .B prkeys_file (Deprecated) This option is not supported anymore, and will be ignored. -.RS -.TP -The compiled-in value is: \fB@STATE_DIR@/prkeys\fR -.RE . . .TP
@@ -1008,10 +974,6 @@ The default is: \fB<unset>\fR .TP .B config_dir (Deprecated) This option is not supported anymore, and will be ignored. -.RS -.TP -The compiled-in value is: \fB@CONFIGDIR@\fR -.RE . . .TP
@@ -1324,7 +1286,6 @@ The default is: \fBno\fR .TP .B disable_changed_wwids (Deprecated) This option is not supported anymore, and will be ignored. -.RE . . .TP
@@ -1580,14 +1541,8 @@ section: .TP .B failback .TP -.B rr_weight -.TP .B no_path_retry .TP -.B rr_min_io -.TP -.B rr_min_io_rq -.TP .B flush_on_last_del .TP .B features
@@ -1769,14 +1724,8 @@ section: .TP .B failback .TP -.B rr_weight -.TP .B no_path_retry .TP -.B rr_min_io -.TP -.B rr_min_io_rq -.TP .B fast_io_fail_tmo .TP .B dev_loss_tmo
@@ -1855,14 +1804,8 @@ the values are taken from the \fIdevices\fR or \fIdefaults\fR sections: .TP .B failback .TP -.B rr_weight -.TP .B no_path_retry .TP -.B rr_min_io -.TP -.B rr_min_io_rq -.TP .B flush_on_last_del .TP .B fast_io_fail_tmo
Signature · 1 line
2.54.0
PATCH v2 2/8 multipath-tools: remove explicit width from .TP macros in multipath.conf.5
In reply to Xose Vazquez PerezThis allows man/groff to calculate the width automatically, preventing excessive whitespace and improving readability on various terminal sizes.
--- multipath/multipath.conf.5.in | 56 +++++++++++++++++------------------ 1 file changed, 28 insertions(+), 28 deletions(-)
multipath/multipath.conf.5.in +28 -28
@@ -103,7 +103,7 @@ matches, standard regular expression syntax using the special characters "^" and .LP . The following \fIsection\fP keywords are recognized: -.TP 17 +.TP .B defaults This section defines default values for attributes which are used whenever no values are given in the appropriate device or multipath
@@ -142,7 +142,7 @@ device-specific settings for all devices. The \fIdefaults\fR section recognizes the following keywords: . . -.TP 17 +.TP .B verbosity Default verbosity. Higher values increase the verbosity level. Valid levels are between 0 and 6.
@@ -195,7 +195,7 @@ The default is: \fBno\fR The default path selector algorithm to use; they are offered by the kernel multipath target: .RS -.TP 12 +.TP .I "round-robin 0" Choose the path for the next bunch of I/O by looping through every path in the path group, sending \fBthe same number of I/O requests\fR to each path.
@@ -223,7 +223,7 @@ The default is: \fBservice-time 0\fR (Hardware-dependent) The default path grouping policy to apply to unspecified multipaths. Possible values are: .RS -.TP 12 +.TP .I failover One path per priority group. .TP
@@ -333,7 +333,7 @@ of this path. Higher number have a higher priority. \fI"none"\fR is a valid value. Currently the following path priority routines are implemented: .RS -.TP 12 +.TP .I const Return a constant priority of \fI1\fR. .TP
@@ -408,12 +408,12 @@ NetAPP E/EF Series, where it is \fBalua\fR). If \fBdetect_prio\fR is Arguments to pass to to the prio function. This only applies to certain prioritizers: .RS -.TP 12 +.TP .I weighted Needs a value of the form \fI"<hbtl|devname|serial|wwn> <regex1> <prio1> <regex2> <prio2> ..."\fR .RS -.TP 8 +.TP .I hbtl Regex can be of SCSI H:B:T:L format. For example: 1:0:.:. , *:0:0:. .TP
@@ -430,11 +430,11 @@ Regex can be of the form \fI"host_wwnn:host_wwpn:target_wwnn:target_wwpn"\fR these values can be looked up through sysfs or by running \fImultipathd show paths format "%N:%R:%n:%r"\fR. For example: 0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.* , .*:.*:iqn.2009-10.com.redhat.msp.lab.ask-06:.* .RE -.TP 12 +.TP .I path_latency Needs a value of the form "io_num=\fI<20>\fR base_num=\fI<10>\fR" .RS -.TP 8 +.TP .I io_num The number of read IOs sent to the current path continuously, used to calculate the average path latency. Valid Values: Integer, [20, 200].
@@ -445,7 +445,7 @@ Double-precision floating-point, [1.1, 10]. And Max average latency value is 100 For example: If base_num=10, the paths will be grouped in priority groups with path latency <=1us, (1us, 10us], (10us, 100us], (100us, 1ms], (1ms, 10ms], (10ms, 100ms], (100ms, 1s], (1s, 10s], (10s, 100s], >100s. .RE -.TP 12 +.TP .I alua If \fIexclusive_pref_bit\fR is set, paths with the \fIpreferred path\fR bit set will always be in their own path group.
@@ -456,17 +456,17 @@ set will always be in their own path group. .TP .I datacore .RS -.TP 8 +.TP .I preferredsds (Mandatory) The preferred "SDS name". .TP .I timeout (Optional) The timeout for the INQUIRY, in ms. .RE -.TP 12 +.TP .I iet .RS -.TP 8 +.TP .I preferredip=... (Mandatory) Th preferred IP address, in dotted decimal notation, for iSCSI targets. .RE
@@ -481,7 +481,7 @@ Specify any device-mapper features to be used. Syntax is \fInum list\fR where \fInum\fR is the number, between 0 and 8, of features in \fIlist\fR. Possible values for the feature list are: .RS -.TP 12 +.TP .I queue_if_no_path (Deprecated, superseded by \fIno_path_retry\fR) Queue I/O if no path is active. Identical to the \fIno_path_retry\fR with \fIqueue\fR value. If both this
@@ -520,7 +520,7 @@ to respond. The asynchronous checkers (\fItur\fR and \fIdirectio\fR) will not pause multipathd. Instead, multipathd will check for a response once per second, until \fIchecker_timeout\fR seconds have elapsed. Possible values are: .RS -.TP 12 +.TP .I readsector0 (Deprecated) Read the first sector of the device. This checker is being deprecated, please use \fItur\fR or \fIdirectio\fR instead.
@@ -574,7 +574,7 @@ Tell multipathd how to manage path group failback. To select \fIimmediate\fR or a \fIvalue\fR, it's mandatory that the device has support for a working prioritizer. .RS -.TP 12 +.TP .I immediate Immediately failback to the highest priority pathgroup that contains active paths.
@@ -628,7 +628,7 @@ The default is: \fBmax\fR .B no_path_retry Specify what to do when all paths are down. Possible values are: .RS -.TP 12 +.TP .I value > 0 Number of retries until disable I/O queueing. .TP
@@ -1154,7 +1154,7 @@ blocked from further processing by higher layers - such as LVM - if and only if it\'s considered a valid multipath device path), and b) when multipathd detects a new device. The following values are possible: .RS -.TP 10 +.TP .I strict Both multipath and multipathd treat only such devices as multipath devices which have been part of a multipath map previously, and which are therefore
@@ -1421,7 +1421,7 @@ by multipath-tools. . The following keywords are recognized in both sections. The defaults are empty unless explicitly stated. -.TP 17 +.TP .B devnode Regular expression matching the device nodes to be excluded/included. .RS
@@ -1511,7 +1511,7 @@ from later entries take precedence. . . The \fImultipath\fR subsection recognizes the following attributes: -.TP 17 +.TP .B wwid (Mandatory) World Wide Identifier. Detected multipath maps are matched against this attribute. Note that, unlike the \fIwwid\fR attribute in the \fIblacklist\fR section,
@@ -1530,7 +1530,7 @@ section: .sp 1 .PD .1v .RS -.TP 18 +.TP .B path_grouping_policy .TP .B path_selector
@@ -1587,7 +1587,7 @@ section: .SH "devices section" .\" ---------------------------------------------------------------------------- . -.TP 4 +.TP .B Important: The built-in hardware device table of .I multipath-tools
@@ -1623,7 +1623,7 @@ for all devices in the system. .LP . The \fIdevice\fR subsection recognizes the following attributes: -.TP 17 +.TP .B vendor (Mandatory) Regular expression to match the vendor name. .RS
@@ -1666,7 +1666,7 @@ and \fImultipathd show paths format\fR commands. Currently only the The hardware handler to use for this device type. The following hardware handler are implemented: .RS -.TP 12 +.TP .I 1 emc (Hardware-dependent) Hardware handler for DGC class arrays as CLARiiON CX/AX and EMC VNX families
@@ -1707,7 +1707,7 @@ section: .sp 1 .PD .1v .RS -.TP 18 +.TP .B path_grouping_policy .TP .B uid_attribute
@@ -1785,7 +1785,7 @@ the values are taken from the \fIdevices\fR or \fIdefaults\fR sections: .sp 1 .PD .1v .RS -.TP 18 +.TP .B path_grouping_policy .TP .B uid_attribute
@@ -1899,7 +1899,7 @@ which paths belong to the same device. Each path presenting the same WWID is assumed to point to the same device. .LP The WWID is generated by four methods (in the order of preference): -.TP 17 +.TP .B uid_attrs The WWID is derived from udev attributes by matching the device node name; cf \fIuid_attrs\fR above.
@@ -1939,7 +1939,7 @@ pathgroups will not be used until all other pathgroups have been tried. At the time when the path would normally be reinstated, it will be returned to its normal pathgroup. The logic of determining \(dqshaky\(dq condition, as well as the logic when to reinstate, differs between the three methods. -.TP 8 +.TP .B \(dqdelay_checks\(dq failure tracking (Deprecated) This method is \fBdeprecated\fR and mapped to the \(dqsan_path_err\(dq method. See the \fIdelay_watch_checks\fR and \fIdelay_wait_checks\fR options above
Signature · 1 line
2.54.0
PATCH v2 3/8 multipath-tools: remove explicit widths from macros in the remaining man pages
In reply to Xose Vazquez PerezThis allows man/groff to calculate the width automatically, preventing excessive whitespace and improving readability on various terminal sizes.
--- libmpathpersist/mpath_persistent_reserve_in.3 | 4 ++-- libmpathpersist/mpath_persistent_reserve_out.3 | 4 ++-- mpathpersist/mpathpersist.8.in | 2 +- multipath/multipath.8.in | 6 +++--- multipath/multipath.conf.5.in | 10 +++++----- multipathd/multipathd.8.in | 9 ++++----- 6 files changed, 17 insertions(+), 18 deletions(-)
libmpathpersist/mpath_persistent_reserve_in.3 +2 -2
@@ -35,7 +35,7 @@ the DM device and gets the response. .TP .B Parameters: .RS -.TP 12 +.TP .I fd The file descriptor of a multipath device. Input argument. .TP
@@ -57,7 +57,7 @@ Set verbosity level. Input argument. value:[0-3]. 0->Errors, 1->Warnings, 2->Inf .SH RETURNS .\" ---------------------------------------------------------------------------- . -.TP 12 +.TP .B MPATH_PR_SUCCESS If PR command successful. .TP
libmpathpersist/mpath_persistent_reserve_out.3 +2 -2
@@ -35,7 +35,7 @@ the DM device and gets the response. .TP .B Parameters: .RS -.TP 12 +.TP .I fd The file descriptor of a multipath device. Input argument. .TP
@@ -74,7 +74,7 @@ Set verbosity level. Input argument. value: 0 to 3. 0->Errors, 1->Warnings, 2->I .SH RETURNS .\" ---------------------------------------------------------------------------- . -.TP 12 +.TP .B MPATH_PR_SUCCESS If PR command successful else returns any one of the status mentioned below. .TP
mpathpersist/mpathpersist.8.in +1 -1
@@ -50,7 +50,7 @@ various options. .BI \-verbose|\-v " level" Verbosity: .RS -.TP 5 +.TP .I 0 Critical messages. .TP
multipath/multipath.8.in +3 -3
@@ -100,7 +100,7 @@ The \fBdevice\fR argument restricts \fBmultipath\fR's operation to devices match expression. The argument may refer either to a multipath map or to its components ("paths"). The expression may be in one of the following formats: . -.TP 1.4i +.TP .B device node file name of a device node, e.g. \fI/dev/dm-10\fR or \fI/dev/sda\fR. If the node refers to an existing device mapper device representing a multipath map, this selects
@@ -195,8 +195,8 @@ creating \fI@CONFIGFILE@\fR. .BI \-v " level" Verbosity of information printed to stdout in default and "list" operation modes. The default level is \fI-v 2\fR. -.RS 1.2i -.TP 1.2i +.RS +.TP .I 0 Nothing is printed. .TP
multipath/multipath.conf.5.in +5 -5
@@ -1527,7 +1527,7 @@ the same WWID in the \fIbindings_file\fR. The following attributes are optional; if not set the default values are taken from the \fIoverrides\fR, \fIdevices\fR, or \fIdefaults\fR section: -.sp 1 +.sp .PD .1v .RS .TP
@@ -1704,7 +1704,7 @@ has no effect. The following attributes are optional; if not set the default values are taken from the \fIdefaults\fR section: -.sp 1 +.sp .PD .1v .RS .TP
@@ -1782,7 +1782,7 @@ section: . The overrides section recognizes the following optional attributes; if not set the values are taken from the \fIdevices\fR or \fIdefaults\fR sections: -.sp 1 +.sp .PD .1v .RS .TP
@@ -1878,7 +1878,7 @@ exactly. The protocol that a path is using can be viewed by running .LP The following attributes are optional; if not set, the default values are taken from the \fIoverrides\fR, \fIdevices\fR, or \fIdefaults\fR section: -.sp 1 +.sp .PD .1v .RS .TP
@@ -1969,7 +1969,7 @@ increase and the threshold is never reached. Ticks are the time between path checks by multipathd, which is variable and controlled by the \fIpolling_interval\fR and \fImax_polling_interval\fR parameters. . -.RS 8 +.RS .LP This algorithm is superseded by the \(dqmarginal_path\(dq failure tracking, but remains supported for backward compatibility.
multipathd/multipathd.8.in +4 -5
@@ -416,7 +416,7 @@ appropriate device information. The following wildcards are supported. .TP .B Multipath format wildcards .RS -.TP 12 +.TP .B %n The device name. .TP
@@ -521,7 +521,7 @@ the configured one). .TP .B Path format wildcards .RS -.TP 12 +.TP .B %w The device WWID (uuid). .TP
@@ -548,7 +548,7 @@ sysfs states, it shows "running". .B %T The multipathd path checker state of the device. The possible states are: .RS -.TP 12 +.TP .I ready The device is ready to handle IO. .TP
@@ -693,8 +693,7 @@ Overrides the \fImax_fds\fR configuration setting. . .BR multipathc (8), .BR multipath (8), -.BR kpartx (8) -.RE +.BR kpartx (8), .BR sd_notify (3), .BR systemd.service (5). .
Signature · 1 line
2.54.0
PATCH v2 4/8 multipath-tools: remove syntax check comments from man pages
In reply to Xose Vazquez PerezRemove the embedded groff/man command lines from the header comments of all man pages.
--- kpartx/kpartx.8 | 4 ---- libmpathpersist/mpath_persistent_reserve_in.3 | 4 ---- libmpathpersist/mpath_persistent_reserve_out.3 | 4 ---- mpathpersist/mpathpersist.8.in | 4 ---- multipath/multipath.8.in | 4 ---- multipath/multipath.conf.5.in | 4 ---- multipathd/multipathc.8 | 4 ---- multipathd/multipathd.8.in | 4 ---- 8 files changed, 32 deletions(-)
kpartx/kpartx.8 +0 -4
@@ -1,8 +1,4 @@ .\" ---------------------------------------------------------------------------- -.\" Make sure there are no errors with: -.\" groff -z -wall -b -e -t kpartx/kpartx.8 -.\" man --warnings -E UTF-8 -l -Tutf8 -Z kpartx/kpartx.8 > /dev/null -.\" .\" Update the date below if you make any significant change. .\" ---------------------------------------------------------------------------- .
libmpathpersist/mpath_persistent_reserve_in.3 +0 -4
@@ -1,8 +1,4 @@ .\" ---------------------------------------------------------------------------- -.\" Make sure there are no errors with: -.\" groff -z -wall -b -e -t libmpathpersist/mpath_persistent_reserve_in.3 -.\" man --warnings -E UTF-8 -l -Tutf8 -Z libmpathpersist/mpath_persistent_reserve_in.3 > /dev/null -.\" .\" Update the date below if you make any significant change. .\" ---------------------------------------------------------------------------- .
libmpathpersist/mpath_persistent_reserve_out.3 +0 -4
@@ -1,8 +1,4 @@ .\" ---------------------------------------------------------------------------- -.\" Make sure there are no errors with: -.\" groff -z -wall -b -e -t libmpathpersist/mpath_persistent_reserve_out.3 -.\" man --warnings -E UTF-8 -l -Tutf8 -Z libmpathpersist/mpath_persistent_reserve_out.3 > /dev/null -.\" .\" Update the date below if you make any significant change. .\" ---------------------------------------------------------------------------- .
mpathpersist/mpathpersist.8.in +0 -4
@@ -1,8 +1,4 @@ .\" ---------------------------------------------------------------------------- -.\" Make sure there are no errors with: -.\" groff -z -wall -b -e -t mpathpersist/mpathpersist.8 -.\" man --warnings -E UTF-8 -l -Tutf8 -Z mpathpersist/mpathpersist.8 > /dev/null -.\" .\" Update the date below if you make any significant change. .\" ---------------------------------------------------------------------------- .
multipath/multipath.8.in +0 -4
@@ -1,8 +1,4 @@ .\" ---------------------------------------------------------------------------- -.\" Make sure there are no errors with: -.\" groff -z -wall -b -e -t multipath/multipath.8 -.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipath/multipath.8 > /dev/null -.\" .\" Update the date below if you make any significant change. .\" ---------------------------------------------------------------------------- .
multipath/multipath.conf.5.in +0 -4
@@ -1,8 +1,4 @@ .\" ---------------------------------------------------------------------------- -.\" Make sure there are no errors with: -.\" groff -z -wall -b -e -t multipath/multipath.conf.5 -.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipath/multipath.conf.5 > /dev/null -.\" .\" Update the date below if you make any significant change. .\" ---------------------------------------------------------------------------- .
multipathd/multipathc.8 +0 -4
@@ -1,8 +1,4 @@ .\" ---------------------------------------------------------------------------- -.\" Make sure there are no errors with: -.\" groff -z -wall -b -e -t multipathd/multipathc.8 -.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipathd/multipathc.8 > /dev/null -.\" .\" Update the date below if you make any significant change. .\" ---------------------------------------------------------------------------- .
multipathd/multipathd.8.in +0 -4
@@ -1,8 +1,4 @@ .\" ---------------------------------------------------------------------------- -.\" Make sure there are no errors with: -.\" groff -z -wall -b -e -t multipathd/multipathd.8 -.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipathd/multipathd.8 > /dev/null -.\" .\" Update the date below if you make any significant change. .\" ---------------------------------------------------------------------------- .
Signature · 1 line
2.54.0
PATCH v2 5/8 multipath-tools: clarify path selector descriptions in multipath.conf.5
In reply to Xose Vazquez PerezSelectors operate on the next individual I/O request rather than a "bunch" of I/O.
---
v2: fix typo, s/group/groups (spotted by Martin)
multipath/multipath.conf.5.in | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-)
multipath/multipath.conf.5.in +5 -7
@@ -2,7 +2,7 @@ .\" Update the date below if you make any significant change. .\" ---------------------------------------------------------------------------- . -.TH MULTIPATH.CONF 5 2026-05-27 Linux +.TH MULTIPATH.CONF 5 2026-06-13 Linux . . .\" ----------------------------------------------------------------------------
@@ -193,20 +193,18 @@ kernel multipath target: .RS .TP .I "round-robin 0" -Choose the path for the next bunch of I/O by looping through every path in the -path group, sending \fBthe same number of I/O requests\fR to each path. - +Choose the path for the next I/O request by \fBcycling through the path groups\fR. .TP .I "queue-length 0" -(Since 2.6.31 kernel) Choose the path for the next bunch of I/O based on \fBthe lowest +(Since 2.6.31 kernel) Choose the path for the next I/O request based on \fBthe lowest number of outstanding in-flight I/O requests\fR to the path. .TP .I "service-time 0" -(Since 2.6.31 kernel) Choose the path for the next bunch of I/O based on \fBthe +(Since 2.6.31 kernel) Choose the path for the next I/O request based on \fBthe lowest total size (in bytes) of outstanding in-flight I/O requests\fR to the path. .TP .I "historical-service-time 0" -(Since 5.8 kernel) Choose the path for the next bunch of I/O with \fBa dynamic +(Since 5.8 kernel) Choose the path for the next I/O request with \fBa dynamic algorithm based on the historical service time and the number of outstanding in-flight I/O requests\fR to the path. .TP
Signature · 1 line
2.54.0
Benjamin Marzinski
maintainerRe: [PATCH v2 5/8] multipath-tools: clarify path selector descriptions in multipath.conf.5
Quoted 29 lines · Xose Vazquez Perez
Selectors operate on the next individual I/O request rather than a "bunch" of I/O.
Suggested-by Benjamin Marzinski <[email protected]>Cc Martin Wilck <[email protected]>Cc Benjamin Marzinski <[email protected]>Cc Christophe Varoqui <[email protected]>Cc DM_DEVEL-ML <[email protected]>Signed-off-by Xose Vazquez Perez <[email protected]>---
v2: fix typo, s/group/groups (spotted by Martin)multipath/multipath.conf.5.in | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-)multipath/multipath.conf.5.in +1
-1@@ -2,7 +2,7 @@ .\" Update the date below if you make any significant change. .\" ---------------------------------------------------------------------------- . -.TH MULTIPATH.CONF 5 2026-05-27 Linux +.TH MULTIPATH.CONF 5 2026-06-13 Linux . . .\" ----------------------------------------------------------------------------
multipath/multipath.conf.5.in kernel multipath target: · line 196
Quoted 7 lines
multipath/multipath.conf.5.in +1
-3@@ -193,20 +193,18 @@ kernel multipath target: .RS .TP .I "round-robin 0" -Choose the path for the next bunch of I/O by looping through every path in the -path group, sending \fBthe same number of I/O requests\fR to each path. - +Choose the path for the next I/O request by \fBcycling through the path groups\fR.
This isn't a strong objections, but personally, I'm not sure "groups" makes this better. It kind of sounds like paths are picked from multiple path groups. Perhaps:
"cycling through the paths"
or
"cycling through the paths in the path group"
I'm also o.k. with leaving it as you have it.
-Ben
Quoted 19 lines
multipath/multipath.conf.5.in +3
-3.TP .I "queue-length 0" -(Since 2.6.31 kernel) Choose the path for the next bunch of I/O based on \fBthe lowest +(Since 2.6.31 kernel) Choose the path for the next I/O request based on \fBthe lowest number of outstanding in-flight I/O requests\fR to the path. .TP .I "service-time 0" -(Since 2.6.31 kernel) Choose the path for the next bunch of I/O based on \fBthe +(Since 2.6.31 kernel) Choose the path for the next I/O request based on \fBthe lowest total size (in bytes) of outstanding in-flight I/O requests\fR to the path. .TP .I "historical-service-time 0" -(Since 5.8 kernel) Choose the path for the next bunch of I/O with \fBa dynamic +(Since 5.8 kernel) Choose the path for the next I/O request with \fBa dynamic algorithm based on the historical service time and the number of outstanding in-flight I/O requests\fR to the path. .TPSignature · 1 line
2.54.0
Re: [PATCH v2 5/8] multipath-tools: clarify path selector descriptions in multipath.conf.5
Quoted 4 lines · Benjamin Marzinski
Quoted 1 line · Xose Vazquez Perez
+Choose the path for the next I/O request by \fBcycling through the path groups\fR.
Quoted 8 lines
This isn't a strong objections, but personally, I'm not sure "groups" makes this better. It kind of sounds like paths are picked from multiple path groups. Perhaps:
"cycling through the paths"
or
"cycling through the paths in the path group"I'm also o.k. with leaving it as you have it.
You are absolutely right. Using the plural "groups" breaks the coherence of the sentence because I/O is cycled within the active path group, not between different groups.
I'll restore the singular form in v3. Thanks
Re: [PATCH v2 5/8] multipath-tools: clarify path selector descriptions in multipath.conf.5
Quoted 16 lines · Xose Vazquez Perez
Quoted 14 lines · Benjamin Marzinski
Quoted 2 lines · Xose Vazquez Perez
+Choose the path for the next I/O request by \fBcycling through the path groups\fR.
This isn't a strong objections, but personally, I'm not sure "groups"
makes this better. It kind of sounds like paths are picked from multiple
path groups. Perhaps:
"cycling through the paths"
or
"cycling through the paths in the path group"
Quoted 7 lines
Quoted 1 line
I'm also o.k. with leaving it as you have it.
You are absolutely right. Using the plural "groups" breaks the coherence
of the sentence because I/O is cycled within the active path group, not between different groups.I'll restore the singular form in v3. Thanks
Right, my bad, sorry.
PATCH v2 6/8 multipath-tools: specify file paths using variables and add FILES section in multipath.conf.5
In reply to Xose Vazquez PerezReplace hardcoded file name references with their dynamic build variables. Also, add a dedicated FILES section at the end of the man page to clearly document configuration files/dirs.
--- multipath/multipath.conf.5.in | 55 ++++++++++++++++++++++++++--------- 1 file changed, 42 insertions(+), 13 deletions(-)
multipath/multipath.conf.5.in +42 -13
@@ -27,7 +27,7 @@ or \fBmultipathd show config\fR command. . .PP Additional configuration can be made in drop-in files under -.B @CONFIGDIR@. +.BR @CONFIGDIR@/ . Files ending in \fI.conf\fR in this directory are read in alphabetical order, after reading \fI@CONFIGFILE@\fR. They use the same syntax as \fI@CONFIGFILE@\fR itself,
@@ -831,11 +831,11 @@ to the end of the reservation key. .RS .PP Alternatively, this can be set to \fBfile\fR, which will store the RESERVATION -KEY registered by mpathpersist in the \fIprkeys_file\fR. multipathd will then -use this key to register additional paths as they appear. When the +KEY registered by mpathpersist in the \fI@STATE_DIR@/prkeys\fR file. multipathd +will then use this key to register additional paths as they appear. When the registration is removed, the RESERVATION KEY is removed from the -\fIprkeys_file\fR. The prkeys file will automatically keep track of whether -the key was registered with \fI--param-aptpl\fR. +\fI@STATE_DIR@/prkeys\fR file. The prkeys file will automatically keep track of +whether the key was registered with \fI--param-aptpl\fR. .TP The default is: \fB<unset>\fR .RE
@@ -1152,9 +1152,9 @@ detects a new device. The following values are possible: .I strict Both multipath and multipathd treat only such devices as multipath devices which have been part of a multipath map previously, and which are therefore -listed in the \fBwwids_file\fR. Users can manually set up multipath maps using the -\fBmultipathd add map\fR command. Once set up manually, the map is -remembered in the wwids file and will be set up automatically in the future. +listed in the \fI@STATE_DIR@/wwids\fR file. Users can manually set up multipath +maps using the \fBmultipathd add map\fR command. Once set up manually, the map is +remembered in the WWIDs file and will be set up automatically in the future. .TP .I off Multipath behaves like \fBstrict\fR. Multipathd behaves like \fBgreedy\fR.
@@ -1513,8 +1513,8 @@ this is \fBnot\fR a regular expression or a substring; WWIDs must match exactly inside the multipaths section. .TP .B alias -Symbolic name for the multipath map. This takes precedence over a an entry for -the same WWID in the \fIbindings_file\fR. +Symbolic name for the multipath map. This takes precedence over an entry for +the same WWID in the \fI@STATE_DIR@/bindings\fR file. .LP . .
@@ -1598,9 +1598,9 @@ for more than 100 known multipath-capable storage devices. The devices section can be used to override these settings. If there are multiple matches for a given device, the attributes of all matching entries are applied to it. If an attribute is specified in several matching device subsections, -later entries take precedence. Thus, entries in files under \fIconfig_dir\fR (in -reverse alphabetical order) have the highest precedence, followed by entries -in \fI@CONFIGFILE@\fR; the built-in hardware table has the lowest +later entries take precedence. Thus, entries in files under the \fI@CONFIGDIR@/\fR +directory (in reverse alphabetical order) have the highest precedence, followed +by entries in \fI@CONFIGFILE@\fR; the built-in hardware table has the lowest precedence. Inside a configuration file, later entries have higher precedence than earlier ones. .LP
@@ -2028,6 +2028,35 @@ specified the order of precedence is \fIno_path_retry, queue_if_no_path, dev_los . . .\" ---------------------------------------------------------------------------- +.SH "FILES" +.\" ---------------------------------------------------------------------------- +. +Default paths for configuration files and directories: +.TP +.I @CONFIGFILE@ +Main configuration file. +.TP +.I @CONFIGDIR@/ +Directory for configuration drop-in files. +.TP +.I @STATE_DIR@/bindings +Bindings file, used when the \fBuser_friendly_names\fR option is set to +\fByes\fR to assign a persistent and unique alias to each multipath device. +.TP +.I @STATE_DIR@/prkeys +Persistent reservation keys file, used by multipathd to keep track of the +reservation key used for a specific WWID when \fBreservation_key\fR is set +to \fBfile\fR. +.TP +.I @STATE_DIR@/wwids +WWIDs file, used by multipath to keep track of the WWIDs of LUNs for which +multipath devices have been created in the past. +.TP +.I @RUNTIME_DIR@/multipathd.pid +PID file. +. +. +.\" ---------------------------------------------------------------------------- .SH "SEE ALSO" .\" ---------------------------------------------------------------------------- .
Signature · 1 line
2.54.0
PATCH v2 7/8 multipath-tools: clarify user_friendly_names prefix behavior in multipath.conf.5
In reply to Xose Vazquez PerezClarify that the alias prefix depends on the alias_prefix setting.
---
v2: fix copy-paste typo and delete <n>, changing "\IBmpath<n>\fR"
to "\fImpath\fR" (spotted by Martin)
multipath/multipath.conf.5.in | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-)
multipath/multipath.conf.5.in +6 -4
@@ -704,11 +704,13 @@ The default is: \fBunused\fR .B user_friendly_names If set to .I yes -, using the bindings file \fI@STATE_DIR@/bindings\fR to assign a persistent -and unique alias to the multipath, in the form of mpath<n>. If set to +, the bindings file \fI@STATE_DIR@/bindings\fR is used to assign a persistent +and unique alias to the multipath, in the form of \fIprefix\fR<n> (where +\fIprefix\fR is defined by \fIalias_prefix\fR; by default \fImpath\fR). +If set to .I no -use the WWID as the alias. In either case this be will -be overridden by any specific aliases in the \fImultipaths\fR section. +, the WWID is used as the alias. In either case, this will be overridden +by any specific aliases defined in the \fImultipaths\fR section. .RS .TP The default is: \fBno\fR
Signature · 1 line
2.54.0
PATCH v2 8/8 multipath-tools: fix mandoc errors/warnings in man pages
In reply to Xose Vazquez PerezFix the following errors and warnings reported by mandoc linting:
$ mandoc -W all -T lint man_page.X | grep -v "STYLE: input text line longer than 80 bytes"
mandoc: ./libmpathpersist/mpath_persistent_reserve_in.3:22:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./libmpathpersist/mpath_persistent_reserve_out.3:22:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./mpathpersist/mpathpersist.8.in:172:2: WARNING: skipping paragraph macro: PP after SH
mandoc: ./mpathpersist/mpathpersist.8.in:215:2: WARNING: skipping paragraph macro: PP after SH
mandoc: ./multipathd/multipathc.8:19:15: STYLE: whitespace at end of input line
mandoc: ./multipathd/multipathd.8.in:573:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./multipathd/multipathd.8.in:573:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./multipath/multipath.conf.5.in:130:2: ERROR: skipping end of block that is not open: RE
mandoc: ./multipath/multipath.conf.5.in:1979:2: ERROR: skipping end of block that is not open: RE
mandoc: ./multipath/multipath.conf.5.in:89:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./multipath/multipath.conf.5.in:131:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./multipath/multipath.conf.5.in:130:2: WARNING: skipping paragraph macro: br at the end of SH
mandoc: ./multipath/multipath.conf.5.in:1577:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./multipath/multipath.conf.5.in:1770:2: WARNING: skipping paragraph macro: PP empty
--- libmpathpersist/mpath_persistent_reserve_in.3 | 1 - libmpathpersist/mpath_persistent_reserve_out.3 | 1 - mpathpersist/mpathpersist.8.in | 2 -- multipath/multipath.conf.5.in | 6 ------ multipathd/multipathc.8 | 2 +- multipathd/multipathd.8.in | 1 - 6 files changed, 1 insertion(+), 12 deletions(-)
libmpathpersist/mpath_persistent_reserve_in.3 +0 -1
@@ -19,7 +19,6 @@ mpath_persistent_reserve_in \- send PRIN command to DM device .B #include <mpath_persist.h> .P .BI "int mpath_persistent_reserve_in" "(int fd, int rq_servact, struct prin_resp *resp, int noisy, int verbose)" -.P . . .\" ----------------------------------------------------------------------------
libmpathpersist/mpath_persistent_reserve_out.3 +0 -1
@@ -19,7 +19,6 @@ mpath_persistent_reserve_out \- send PROUT command to DM device .B #include <mpath_persist.h> .P .BI "int mpath_persistent_reserve_out" "(int fd, int rq_servact, int rq_scope, unsigned int rq_type, struct prout_param_descriptor *paramp, int noisy, int verbose)" -.P . . .\" ----------------------------------------------------------------------------
mpathpersist/mpathpersist.8.in +0 -2
@@ -169,7 +169,6 @@ PR In: maximum allocation length. LEN is a decimal number between 0 and 8192. .SH EXAMPLE .\" ---------------------------------------------------------------------------- . -.PP Register the key \(dq123abc\(dq for the /dev/mapper/mpath9 device: .RS \fBmpathpersist --out --register --param-sark=\fI123abc /dev/mapper/mpath9\fR
@@ -212,7 +211,6 @@ Remove current reservation, and unregister all registered keys from all I_T nexu .SH BATCH FILES .\" ---------------------------------------------------------------------------- . -.PP The option \fI--batch-file\fR (\fI-f\fR) sets an input file to be processed by \fBmpathpersist\fR. Grouping commands in batch files can provide a speed improvement in particular on large installments, because \fBmpathpersist\fR
multipath/multipath.conf.5.in +0 -6
@@ -88,7 +88,6 @@ the indentation shown in the above example is helpful for human readers but not mandatory. .LP . -.LP .B Note on regular expressions: The \fI@CONFIGFILE@\fR syntax allows many attribute values to be specified as POSIX Extended Regular Expressions (see \fBregex\fR(7)). These regular expressions
@@ -127,8 +126,6 @@ vendor, product, and revision. .B overrides This section defines values for attributes that should override the device-specific settings for all devices. -.RE -.LP . . .\" ----------------------------------------------------------------------------
@@ -1576,7 +1573,6 @@ section: .B ghost_delay .RE .PD -.LP . . .\" ----------------------------------------------------------------------------
@@ -1769,7 +1765,6 @@ section: .B all_tg_pt .RE .PD -.LP . . .\" ----------------------------------------------------------------------------
@@ -1978,7 +1973,6 @@ as integrity failures or congestion with so-called Fabric Performance Impact Notifications (FPINs).On receiving the fpin notifications through ELS multipathd will move the affected path and port states to marginal. . -.RE .LP See the documentation of the individual options above for details.
multipathd/multipathc.8 +1 -1
@@ -16,7 +16,7 @@ multipathc \- Interactive client for multipathd .SH SYNOPSIS .\" ---------------------------------------------------------------------------- . -.B multipathc +.B multipathc .RB [\| .IR timeout .RB \|]
multipathd/multipathd.8.in +0 -1
@@ -570,7 +570,6 @@ The device appears usable, but it being delayed for marginal path checking. .I undef The device either is not part of a multipath device, or its path checker has not yet run. -.PP .RE .TP .B %s
Signature · 1 line
2.54.0
Quoted 36 lines · Xose Vazquez Perez
It performs general cleanups, updates, and formatting fixes across the man pages, incorporating feedback from Martin and Ben.
Please let me know if further adjustments are needed.
v2:
- Merge "clean up man pages" and "clean up man pages II" series into one batch (requested by Martin).- (5/8) fix typo, s/group/groups (spotted by Martin).
- (7/8) fix copy-paste typo and delete <n>, changing "\IBmpath<n>\fR" to "\fImpath\fR" (spotted by Martin).
Xose Vazquez Perez (8):
multipath-tools: delete obsolete information from multipath.conf.5
multipath-tools: remove explicit width from .TP macros in multipath.conf.5
multipath-tools: remove explicit widths from macros in the remaining man pages
multipath-tools: remove syntax check comments from man pages
multipath-tools: clarify path selector descriptions in multipath.conf.5
multipath-tools: specify file paths using variables and add FILES section in multipath.conf.5
multipath-tools: clarifyuser_friendly_namesprefix behavior in multipath.conf.5
multipath-tools: fix mandoc errors/warnings in man pageskpartx/kpartx.8 | 4 - libmpathpersist/mpath_persistent_reserve_in.3 | 9 +- .../mpath_persistent_reserve_out.3 | 9 +- mpathpersist/mpathpersist.8.in | 8 +- multipath/multipath.8.in | 10 +- multipath/multipath.conf.5.in | 216 ++++++++---------- multipathd/multipathc.8 | 6 +- multipathd/multipathd.8.in | 14 +- 8 files changed, 102 insertions(+), 174 deletions(-)
Quoted 5 lines
Cc Martin Wilck <[email protected]>Cc Benjamin Marzinski <[email protected]>Cc Christophe Varoqui <[email protected]>Cc DM_DEVEL-ML <[email protected]>Signed-off-by Xose Vazquez Perez <[email protected]>
Notwithstanding my nitpick in patch 5,
Quoted 2 lines
Signature · 1 line
2.54.0