multipath: another manpage update
[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 multipath_dir
86 directory where the dynamic shared objects are stored; default is system
87 dependent, commonly
88 .I /lib/multipath
89 .TP
90 .B verbosity
91 default verbosity. Higher values increase the verbosity level. Valid
92 levels are between 0 and 6; default is
93 .I 2
94 .TP
95 .B reassign_maps
96 enable reassigning of device-mapper maps. With this option multipathd
97 will remap existing device-mapper maps to always point to multipath
98 device, not the underlying block devices. Possible values are
99 \fIyes\fR and \fIno\fR. Default is
100 .I yes
101 .TP
102 .B path_selector
103 The default path selector algorithm to use; they are offered by the
104 kernel multipath target. There are three selector algorithms.
105 .RS
106 .TP 12
107 .B "round-robin 0"
108 Loop through every path in the path group, sending the same amount of IO to
109 each.
110 .TP
111 .B "queue-length 0"
112 Send the next bunch of IO down the path with the least amount of outstanding IO.
113 .TP
114 .B "service-time 0"
115 Choose the path for the next bunch of IO based on the amount of outstanding IO
116 to the path and its relative throughput.
117 .RE
118 .TP
119 .B path_grouping_policy
120 The default path grouping policy to apply to unspecified
121 multipaths. Possible values are
122 .RS
123 .TP 12
124 .B failover
125 1 path per priority group
126 .TP
127 .B multibus
128 all paths in 1 priority group
129 .TP
130 .B group_by_serial
131 1 priority group per serial number
132 .TP
133 .B group_by_prio
134 1 priority group per priority value. Priorities are determined by
135 callout programs specified as a global, per-controller or
136 per-multipath option in the configuration file.
137 .TP
138 .B group_by_node_name
139 1 priority group per target node name. Target node names are fetched
140 in /sys/class/fc_transport/target*/node_name.
141 .TP
142 Default value is \fImultibus\fR.
143 .RE
144 .TP
145 .B getuid_callout
146 The default program and args to callout to obtain a unique path
147 identifier. Should be specified with an absolute path. Default value
148 is
149 .I /lib/udev/scsi_id --whitelisted --replace-whitespace --device=/dev/%n
150 .TP
151 .B prio
152 The name of the path priority routine. The specified routine
153 should return a numeric value specifying the relative priority
154 of this path. Higher number have a higher priority.
155 .I "none"
156 is a valid value. Currently the following path priority routines
157 are implemented:
158 .RS
159 .TP 12
160 .B const
161 Return a constant priority of \fI1\fR.
162 .TP
163 .B emc
164 Generate the path priority for EMC arrays.
165 .TP
166 .B alua
167 Generate the path priority based on the SCSI-3 ALUA settings.
168 .TP
169 .B ontap
170 Generate the path priority for NetApp arrays.
171 .TP
172 .B rdac
173 Generate the path priority for LSI/Engenio/NetApp E-Series RDAC controller.
174 .TP
175 .B hp_sw
176 Generate the path priority for Compaq/HP controller in
177 active/standby mode.
178 .TP
179 .B hds
180 Generate the path priority for Hitachi HDS Modular storage arrays.
181 .TP
182 .B random
183 Generate a random priority between 1 and 10.
184 .TP 12
185 .B weightedpath
186 Generate the path priority based on the regular expression and the 
187 priority provided as argument. requires prio_args keyword.
188 .TP
189 Default value is \fBnone\fR.
190 .RE
191 .TP
192 .B prio_args
193 Arguments to pass to to the prio function.  Currently only used with
194 .I weighted, which needs a value of the form
195 .I "<hbtl|devname> <regex1> <prio1> <regex2> <prio2> ..."
196 .I hbtl
197 regex can be of SCSI H:B:T:L format  Ex: 1:0:.:. , *:0:0:.
198 .I devname
199 regex can be of device name format  Ex: sda , sd.e
200 .TP
201 .B features
202 Specify any device-mapper features to be used. Syntax is
203 .I num list
204 where
205 .I num
206 is the number of features in
207 .I list.
208 Possible values for the feature list are
209 .RS
210 .TP 12
211 .B queue_if_no_path
212 Queue IO if no path is active; identical to the
213 .I no_path_retry
214 keyword.
215 .TP
216 .B no_partitions
217 Disable automatic partitions generation via kpartx.
218 .RE
219 .TP
220 .B path_checker
221 The default method used to determine the paths state. Possible values
222 are
223 .RS
224 .TP 12
225 .B readsector0
226 (Deprecated) Read the first sector of the device. This checker is being
227 deprecated, please use \fIdirectio\fR instead
228 .TP
229 .B tur
230 Issue a
231 .I TEST UNIT READY
232 command to the device.
233 .TP
234 .B emc_clariion
235 Query the EMC Clariion specific EVPD page 0xC0 to determine the path
236 state.
237 .TP
238 .B hp_sw
239 Check the path state for HP storage arrays with Active/Standby firmware.
240 .TP
241 .B rdac
242 Check the path state for LSI/Engenio/NetApp E-Series RDAC storage controller.
243 .TP
244 .B directio
245 Read the first sector with direct I/O.
246 .TP
247 Default value is \fIdirectio\fR.
248 .RE
249 .TP
250 .B failback
251 Tell multipathd how to manage path group failback.
252 .RS
253 .TP 12
254 .B immediate
255 Immediately failback to the highest priority pathgroup that contains
256 active paths.
257 .TP
258 .B manual
259 Do not perform automatic failback.
260 .TP
261 .B values > 0
262 deferred failback (time to defer in seconds)
263 .TP
264 Default value is \fImanual\fR.
265 .RE
266 .TP
267 .B  rr_min_io
268 The number of IO to route to a path before switching to the next in
269 the same path group. This is only for BIO based multipath. Default is
270 .I 1000
271 .TP
272 .B rr_min_io_q
273 The number of IO requests to route to a path before switching to the
274 next in the same path group. This is only for request based multipath.
275 Default is
276 .I 1
277 .TP
278 .B rr_weight
279 If set to \fIpriorities\fR the multipath configurator will assign
280 path weights as "path prio * rr_min_io". Possible values are
281 .I priorities
282 or
283 .IR uniform .
284 Default is
285 .IR uniform .
286 .TP
287 .B no_path_retry
288 Specify the number of retries until disable queueing, or
289 .I fail
290 for immediate failure (no queueing),
291 .I queue
292 for never stop queueing. Default is 0.
293 .TP
294 .B user_friendly_names
295 If set to 
296 .I yes
297 , using the bindings file
298 .I /etc/multipath/bindings
299 to assign a persistent and unique alias to the multipath, in the form of mpath<n>.
300 If set to 
301 .I no
302 use the WWID as the alias. In either case this be will
303 be overriden by any specific aliases in the \fImultipaths\fR section.
304 Default is
305 .I no
306 .TP
307 .B flush_on_last_del
308 If set to
309 .I yes
310 , multipathd will disable queueing when the last path to a device has been
311 deleted. Default is
312 .I no
313 .TP
314 .B max_fds
315 Specify the maximum number of file descriptors that can be opened by multipath
316 and multipathd.  This is equivalent to ulimit -n. A value of \fImax\fR will set
317 this to the system limit from /proc/sys/fs/nr_open. If this is not set, the
318 maximum number of open fds is taken from the calling process. It is usually
319 1024. To be safe, this should be set to the maximum number of paths plus 32,
320 if that number is greated than 1024.
321 .TP
322 .B checker_timeout
323 Specify the timeout to user for path checkers that issue scsi commands with an
324 explict timeout, in seconds; default taken from
325 .I /sys/block/sd<x>/device/timeout
326 .TP
327 .B fast_io_fail_tmo
328 Specify the number of seconds the scsi layer will wait after a problem has been
329 detected on a FC remote port before failing IO to devices on that remote port.
330 This should be smaller than dev_loss_tmo. Setting this to
331 .I off
332 will disable the timeout.
333 .TP
334 .B dev_loss_tmo
335 Specify the number of seconds the scsi layer will wait after a problem has
336 been detected on a FC remote port before removing it from the system. This
337 can be set to "infinity" which sets it to the max value of 2147483647
338 seconds, or 68 years.
339 .TP
340 .B queue_without_daemon
341 If set to
342 .I no
343 , when multipathd stops, queueing will be turned off for all devices.
344 This is useful for devices that set no_path_retry.  If a machine is
345 shut down while all paths to a device are down, it is possible to hang waiting
346 for IO to return from the device after multipathd has been stopped. Without
347 multipathd running, access to the paths cannot be restored, and the kernel
348 cannot be told to stop queueing IO. Setting queue_without_daemon to
349 .I no
350 , avoids this problem. Default is
351 .I yes
352 .TP
353 .B bindings_file
354 The full pathname of the binding file to be used when the user_friendly_names option is set. Defaults to
355 .I /var/lib/multipath/bindings
356 .TP
357 .B log_checker_err
358 If set to
359 .I once
360 , multipathd logs the first path checker error at logging level 2. Any later
361 errors are logged at level 3 until the device is restored. If set to
362 .I always
363 , multipathd always logs the path checker error at logging level 2. Default is
364 .I always
365 .
366 .SH "blacklist section"
367 The
368 .I blacklist
369 section is used to exclude specific device from inclusion in the
370 multipath topology. It is most commonly used to exclude local disks or
371 LUNs for the array controller.
372 .LP
373 The following keywords are recognized:
374 .TP 17
375 .B wwid
376 The \fIWorld Wide Identification\fR of a device.
377 .TP
378 .B devnode
379 Regular expression of the device nodes to be excluded.
380 .TP
381 .B device
382 Subsection for the device description. This subsection recognizes the
383 .I vendor
384 and
385 .I product
386 keywords. For a full description of these keywords please see the
387 .I devices
388 section description.
389 .SH "blacklist_exceptions section"
390 The
391 .I blacklist_exceptions
392 section is used to revert the actions of the
393 .I blacklist
394 section, ie to include specific device in the
395 multipath topology. This allows to selectively include devices which
396 would normally be excluded via the
397 .I blacklist
398 section.
399 .LP
400 The following keywords are recognized:
401 .TP 17
402 .B wwid
403 The \fIWorld Wide Identification\fR of a device.
404 .TP
405 .B devnode
406 Regular expression of the device nodes to be excluded.
407 .TP
408 .B device
409 Subsection for the device description. This subsection recognizes the
410 .I vendor
411 and
412 .I product
413 keywords. For a full description of these keywords please see the
414 .I devices
415 section description.
416 .SH "multipaths section"
417 The only recognized attribute for the
418 .B multipaths
419 section is the
420 .I multipath
421 subsection.
422 .LP
423 The
424 .B multipath
425 subsection recognizes the following attributes:
426 .TP 17
427 .B wwid
428 Index of the container. Mandatory for this subsection.
429 .TP
430 .B alias
431 (Optional) symbolic name for the multipath map.
432 .LP
433 The following attributes are optional; if not set the default values
434 are taken from the
435 .I defaults
436 or
437 .I devices
438 section:
439 .sp 1
440 .PD .1v
441 .RS
442 .TP 18
443 .B path_grouping_policy
444 .TP
445 .B path_selector
446 .TP
447 .B prio
448 .TP
449 .B prio_args
450 .TP
451 .B failback
452 .TP
453 .B rr_weight
454 .TP
455 .B flush_on_last_del
456 .TP
457 .B no_path_retry
458 .TP
459 .B rr_min_io
460 .TP
461 .B rr_min_io_q
462 .TP
463 .B features
464 .RE
465 .PD
466 .LP
467 .SH "devices section"
468 The only recognized attribute for the
469 .B devices
470 section is the
471 .I device
472 subsection.
473 .LP
474 The
475 .I device
476 subsection recognizes the following attributes:
477 .TP 17
478 .B vendor
479 (Mandatory) Vendor identifier
480 .TP
481 .B product
482 (Mandatory) Product identifier
483 .TP
484 .B revision
485 (Optional) Revision identfier
486 .TP
487 .B product_blacklist
488 (Optional) Product strings to blacklist for this vendor
489 .TP
490 .B alias_prefix
491 (Optional) The user_friendly_names prefix to use for this
492 device type, instead of the default "mpath"
493 .TP
494 .B hardware_handler
495 (Optional) The hardware handler to use for this device type.
496 The following hardware handler are implemented:
497 .RS
498 .TP 12
499 .B 1 emc
500 Hardware handler for EMC storage arrays.
501 .TP
502 .B 1 rdac
503 Hardware handler for LSI/Engenio/NetApp E-Series RDAC storage controller.
504 .TP
505 .B 1 hp_sw
506 Hardware handler for Compaq/HP storage arrays in active/standby
507 mode.
508 .TP
509 .B 1 alua
510 Hardware handler for SCSI-3 ALUA compatible arrays.
511 .RE
512 .LP
513 The following attributes are optional; if not set the default values
514 are taken from the
515 .I defaults
516 section:
517 .sp 1
518 .PD .1v
519 .RS
520 .TP 18
521 .B path_grouping_policy
522 .TP
523 .B getuid_callout
524 .TP
525 .B path_selector
526 .TP
527 .B path_checker
528 .TP
529 .B prio
530 .TP
531 .B prio_args
532 .TP
533 .B features
534 .TP
535 .B failback
536 .TP
537 .B rr_weight
538 .TP
539 .B no_path_retry
540 .TP
541 .B rr_min_io
542 .TP
543 .B rr_min_io_rq
544 .TP
545 .B fast_io_fail_tmo
546 .TP
547 .B dev_loss_tmo
548 .TP
549 .B flush_on_last_del
550 .RE
551 .PD
552 .LP
553 .SH "KNOWN ISSUES"
554 The usage of
555 .B queue_if_no_path
556 option can lead to
557 .B D state
558 processes being hung and not killable in situations where all the paths to the LUN go offline.
559 It is advisable to use the
560 .B no_path_retry
561 option instead.
562 .P
563 The use of
564 .B queue_if_no_path
565 or
566 .B no_path_retry
567 might lead to a deadlock if the
568 .B dev_loss_tmo
569 setting results in a device being removed while I/O is still queued.
570 The multipath daemon will update the
571 .B dev_loss_tmo
572 setting accordingly to avoid this deadlock. Hence if both values are
573 specified the order of precedence is
574 .I no_path_retry, queue_if_no_path, dev_loss_tmo
575
576 .SH "SEE ALSO"
577 .BR udev (8),
578 .BR dmsetup (8)
579 .BR multipath (8)
580 .BR multipathd (8)
581 .SH AUTHORS
582 .B multipath
583 was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com> and others.