Update manpages
[multipath-tools/.git] / multipath / multipath.conf.5
1 .TH MULTIPATH.CONF 5 "30 November 2006"
2 .SH NAME
3 multipath.conf \- multipath daemon configuration file
4 .SH DESCRIPTION
5 .B "multipath.conf"
6 is the configuration file for the multipath daemon. It is used to
7 overwrite the built-in configuration table of \fBmultipathd\fP.
8 Any line whose first non-white-space character is a '#' is considered
9 a comment line. Empty lines are ignored.
10 .SH SYNTAX
11 The configuration file contains entries of the form:
12 .RS
13 .nf
14 .ft B
15 .sp
16 <section> {
17 .RS
18 .ft B
19 <attribute> <value>
20 .I "..."
21 .ft B
22 <subsection> {
23 .RS
24 .ft B
25 <attribute> <value>
26 .I "..."
27 .RE
28 }
29 .RE
30 }
31 .ft R
32 .fi
33 .RE
34 .LP
35 Each \fIsection\fP contains one or more attributes or subsections. The
36 recognized keywords for attributes or subsections depend on the
37 section in which they occor.
38 .LP
39 The following \fIsection\fP keywords are recognized:
40 .TP 17
41 .B defaults
42 This section defines default values for attributes which are used
43 whenever no values are given in the appropriate device or multipath
44 sections.
45 .TP
46 .B blacklist
47 This section defines which devices should be excluded from the
48 multipath topology discovery.
49 .TP
50 .B blacklist_exceptions
51 This section defines which devices should be included in the
52 multipath topology discovery, despite being listed in the
53 .I blacklist
54 section.
55 .TP
56 .B multipaths
57 This section defines the multipath topologies. They are indexed by a
58 \fIWorld Wide Identifier\fR(wwid), which is the result of the
59 \fIgetuid_callout\fR program.
60 .TP
61 .B devices
62 This section defines the device-specific settings.
63 .RE
64 .LP
65 .SH "defaults section"
66 The
67 .B defaults
68 section recognizes the following keywords:
69 .TP 17
70 .B polling_interval
71 interval between two path checks in seconds. For properly functioning paths,
72 the interval between checks will gradually increase to
73 .B max_polling_interval;
74 default is
75 .I 5
76 .TP
77 .B max_polling_interval
78 maximal interval between two path checks in seconds; default is
79 .I 4 * polling_interval
80 .TP
81 .B udev_dir
82 directory where udev creates its device nodes; default is
83 .I /dev
84 .TP
85 .B verbosity
86 default verbosity. Higher values increase the verbosity level. Valid
87 levels are between 0 and 6; default is
88 .I 2
89 .TP
90 .B reassign_maps
91 enable reassigning of device-mapper maps. With this option multipathd
92 will remap existing device-mapper maps to always point to multipath
93 device, not the underlying block devices. Possible values are
94 \fIyes\fR and \fIno\fR. Default is
95 .I yes
96 .TP
97 .B path_selector
98 The default path selector algorithm to use; they are offered by the
99 kernel multipath target. There are three selector algorithms.
100 .RS
101 .TP 12
102 .B "round-robin 0"
103 Loop through every path in the path group, sending the same amount of IO to
104 each.
105 .TP
106 .B "queue-length 0"
107 Send the next bunch of IO down the path with the least amount of outstanding IO.
108 .TP
109 .B "service-time 0"
110 Choose the path for the next bunch of IO based on the amount of outstanding IO
111 to the path and its relative throughput.
112 .RE
113 .TP
114 .B path_grouping_policy
115 The default path grouping policy to apply to unspecified
116 multipaths. Possible values are
117 .RS
118 .TP 12
119 .B failover
120 1 path per priority group
121 .TP
122 .B multibus
123 all paths in 1 priority group
124 .TP
125 .B group_by_serial
126 1 priority group per serial number
127 .TP
128 .B group_by_prio
129 1 priority group per priority value. Priorities are determined by
130 callout programs specified as a global, per-controller or
131 per-multipath option in the configuration file.
132 .TP
133 .B group_by_node_name
134 1 priority group per target node name. Target node names are fetched
135 in /sys/class/fc_transport/target*/node_name.
136 .TP
137 Default value is \fImultibus\fR.
138 .RE
139 .TP
140 .B getuid_callout
141 The default program and args to callout to obtain a unique path
142 identifier. Should be specified with an absolute path. Default value
143 is
144 .I /lib/udev/scsi_id --whitelisted --device=/dev/%n
145 .TP
146 .B prio
147 The name of the path priority routine. The specified routine
148 should return a numeric value specifying the relative priority
149 of this path. Higher number have a higher priority.
150 .I "none"
151 is a valid value. Currently the following path priority routines
152 are implemented:
153 .RS
154 .TP 12
155 .B const
156 Return a constant priority of \fI1\fR.
157 .TP
158 .B emc
159 Generate the path priority for EMC arrays.
160 .TP
161 .B alua
162 Generate the path priority based on the SCSI-3 ALUA settings.
163 .TP
164 .B ontap
165 Generate the path priority for NetApp arrays.
166 .TP
167 .B rdac
168 Generate the path priority for LSI/Engenio RDAC controller.
169 .TP
170 .B hp_sw
171 Generate the path priority for Compaq/HP controller in
172 active/standby mode.
173 .TP
174 .B hds
175 Generate the path priority for Hitachi HDS Modular storage arrays.
176 .TP
177 .B random
178 Generate a random priority between 1 and 10.
179 .TP 12
180 .B weightedpath <hbtl|devname> <regex1> <prio1> <regex2> <prio2> ...
181 .I hbtl 
182 regex can be of SCSI H:B:T:L format  Ex: 1:0:.:. , *:0:0:.
183 .I devname 
184 regex can be of device name format  Ex: sda , sd.e
185 Generate the path priority based on the regular expression and the 
186 priority provided as argument.
187 .TP
188 Default value is \fBnone\fR.
189 .RE
190 .TP
191 .B features
192 Specify any device-mapper features to be used. Syntax is
193 .I num list
194 where
195 .I num
196 is the number of features in
197 .I list.
198 Possible values for the feature list are
199 .RS
200 .TP 12
201 .B queue_if_no_path
202 Queue IO if no path is active; identical to the
203 .I no_path_retry
204 keyword.
205 .TP
206 .B no_partitions
207 Disable automatic partitions generation via kpartx.
208 .RE
209 .TP
210 .B path_checker
211 The default method used to determine the paths state. Possible values
212 are
213 .RS
214 .TP 12
215 .B readsector0
216 (Deprecated) Read the first sector of the device. This checker is being
217 deprecated, please use \fIdirectio\fR instead
218 .TP
219 .B tur
220 Issue a
221 .I TEST UNIT READY
222 command to the device.
223 .TP
224 .B emc_clariion
225 Query the EMC Clariion specific EVPD page 0xC0 to determine the path
226 state.
227 .TP
228 .B hp_sw
229 Check the path state for HP storage arrays with Active/Standby firmware.
230 .TP
231 .B rdac
232 Check the path state for LSI/Engenio RDAC storage controller.
233 .TP
234 .B directio
235 Read the first sector with direct I/O.
236 .TP
237 Default value is \fIdirectio\fR.
238 .RE
239 .TP
240 .B failback
241 Tell the daemon to manage path group failback, or not to. 0 or
242 .I immediate
243 means immediate failback, values >0 means deferred failback (in
244 seconds).
245 .I manual
246 means no failback. Default value is
247 .I manual
248 .TP
249 .B  rr_min_io
250 The number of IO to route to a path before switching to the next in
251 the same path group. Default is
252 .I 1000
253 .TP
254 .B rr_weight
255 If set to \fIpriorities\fR the multipath configurator will assign
256 path weights as "path prio * rr_min_io". Possible values are
257 .I priorities
258 or
259 .IR uniform .
260 Default is
261 .IR uniform .
262 .TP
263 .B no_path_retry
264 Specify the number of retries until disable queueing, or
265 .I fail
266 for immediate failure (no queueing),
267 .I queue
268 for never stop queueing. Default is 0.
269 .TP
270 .B user_friendly_names
271 If set to 
272 .I yes
273 , using the bindings file
274 .I /etc/multipath/bindings
275 to assign a persistent and unique alias to the multipath, in the form of mpath<n>.
276 If set to 
277 .I no
278 use the WWID as the alias. In either case this be will
279 be overriden by any specific aliases in the \fImultipaths\fR section.
280 Default is
281 .I no
282 .TP
283 .B max_fds
284 Specify the maximum number of file descriptors that can be opened by multipath
285 and multipathd.  This is equivalent to ulimit -n. A value of \fImax\fR will set
286 this to the system limit from /proc/sys/fs/nr_open. If this is not set, the
287 maximum number of open fds is taken from the calling process. It is usually
288 1024. To be safe, this should be set to the maximum number of paths plus 32,
289 if that number is greated than 1024.
290 .TP
291 .B checker_timeout
292 Specify the timeout to user for path checkers that issue scsi commands with an
293 explict timeout, in seconds; default taken from
294 .I /sys/block/sd<x>/device/timeout
295 .TP
296 .B fast_io_fail_tmo
297 Specify the number of seconds the scsi layer will wait after a problem has been
298 detected on a FC remote port before failing IO to devices on that remote port.
299 This should be smaller than dev_loss_tmo. Setting this to
300 .I off
301 will disable the timeout.
302 .TP
303 .B dev_loss_tmo
304 Specify the number of seconds the scsi layer will wait after a problem has
305 been detected on a FC remote port before removing it from the system.
306 .TP
307 .B queue_without_daemon
308 If set to
309 .I no
310 , when multipathd stops, queueing will be turned off for all devices.
311 This is useful for devices that set no_path_retry.  If a machine is
312 shut down while all paths to a device are down, it is possible to hang waiting
313 for IO to return from the device after multipathd has been stopped. Without
314 multipathd running, access to the paths cannot be restored, and the kernel
315 cannot be told to stop queueing IO. Setting queue_without_daemon to
316 .I no
317 , avoids this problem. Default is
318 .I yes
319 .B bindings_file
320 The full pathname of the binding file to be used when the user_friendly_names option is set. Defaults to
321 .I /var/lib/multipath/bindings
322 .
323 .SH "blacklist section"
324 The
325 .I blacklist
326 section is used to exclude specific device from inclusion in the
327 multipath topology. It is most commonly used to exclude local disks or
328 LUNs for the array controller.
329 .LP
330 The following keywords are recognized:
331 .TP 17
332 .B wwid
333 The \fIWorld Wide Identification\fR of a device.
334 .TP
335 .B devnode
336 Regular expression of the device nodes to be excluded.
337 .TP
338 .B device
339 Subsection for the device description. This subsection recognizes the
340 .I vendor
341 and
342 .I product
343 keywords. For a full description of these keywords please see the
344 .I devices
345 section description.
346 .SH "blacklist_exceptions section"
347 The
348 .I blacklist_exceptions
349 section is used to revert the actions of the
350 .I blacklist
351 section, ie to include specific device in the
352 multipath topology. This allows to selectively include devices which
353 would normally be excluded via the
354 .I blacklist
355 section.
356 .LP
357 The following keywords are recognized:
358 .TP 17
359 .B wwid
360 The \fIWorld Wide Identification\fR of a device.
361 .TP
362 .B devnode
363 Regular expression of the device nodes to be excluded.
364 .TP
365 .B device
366 Subsection for the device description. This subsection recognizes the
367 .I vendor
368 and
369 .I product
370 keywords. For a full description of these keywords please see the
371 .I devices
372 section description.
373 .SH "multipaths section"
374 The only recognized attribute for the
375 .B multipaths
376 section is the
377 .I multipath
378 subsection.
379 .LP
380 The
381 .B multipath
382 subsection recognizes the following attributes:
383 .TP 17
384 .B wwid
385 Index of the container. Mandatory for this subsection.
386 .TP
387 .B alias
388 (Optional) symbolic name for the multipath map.
389 .LP
390 The following attributes are optional; if not set the default values
391 are taken from the
392 .I defaults
393 or
394 .I devices
395 section:
396 .sp 1
397 .PD .1v
398 .RS
399 .TP 18
400 .B path_grouping_policy
401 .TP
402 .B path_selector
403 .TP
404 .B prio
405 .TP
406 .B failback
407 .TP
408 .B no_path_retry
409 .TP
410 .B rr_min_io
411 .TP
412 .B features
413 .RE
414 .PD
415 .LP
416 .SH "devices section"
417 The only recognized attribute for the
418 .B devices
419 section is the
420 .I device
421 subsection.
422 .LP
423 The
424 .I device
425 subsection recognizes the following attributes:
426 .TP 17
427 .B vendor
428 (Mandatory) Vendor identifier
429 .TP
430 .B product
431 (Mandatory) Product identifier
432 .TP
433 .B revision
434 (Optional) Revision identfier
435 .TP
436 .B product_blacklist
437 (Optional) Product strings to blacklist for this vendor
438 .TP
439 .B hardware_handler
440 (Optional) The hardware handler to use for this device type.
441 The following hardware handler are implemented:
442 .RS
443 .TP 12
444 .B 1 emc
445 Hardware handler for EMC storage arrays.
446 .TP
447 .B 1 rdac
448 Hardware handler for LSI/Engenio RDAC storage controller.
449 .TP
450 .B 1 hp_sw
451 Hardware handler for Compaq/HP storage arrays in active/standby
452 mode.
453 .TP
454 .B 1 alua
455 Hardware handler for SCSI-3 ALUA compatible arrays.
456 .RE
457 .LP
458 The following attributes are optional; if not set the default values
459 are taken from the
460 .I defaults
461 section:
462 .sp 1
463 .PD .1v
464 .RS
465 .TP 18
466 .B path_grouping_policy
467 .TP
468 .B getuid_callout
469 .TP
470 .B path_selector
471 .TP
472 .B path_checker
473 .TP
474 .B prio
475 .TP
476 .B features
477 .TP
478 .B prio_callout
479 .TP
480 .B failback
481 .TP
482 .B rr_weight
483 .TP
484 .B no_path_retry
485 .TP
486 .B rr_min_io
487 .TP
488 .B fast_io_fail_tmo
489 .TP
490 .B dev_loss_tmo
491 .RE
492 .PD
493 .LP
494 .SH "KNOWN ISSUES"
495 The usage of
496 .B queue_if_no_path
497 option can lead to
498 .B D state
499 processes being hung and not killable in situations where all the paths to the LUN go offline.
500 It is advisable to use the
501 .B no_path_retry
502 option instead.
503 .P
504 The use of
505 .B queue_if_no_path
506 or
507 .B no_path_retry
508 might lead to a deadlock if the
509 .B dev_loss_tmo
510 setting results in a device being removed while I/O is still queued.
511 The multipath daemon will update the
512 .B dev_loss_tmo
513 setting accordingly to avoid this deadlock. Hence if both values are
514 specified the order of precedence is
515 .I no_path_retry, queue_if_no_path, dev_loss_tmo
516
517 .SH "SEE ALSO"
518 .BR udev (8),
519 .BR dmsetup (8)
520 .BR multipath (8)
521 .BR multipathd (8)
522 .SH AUTHORS
523 .B multipath
524 was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com> and others.