adec743309a9d760521e06ab4a6a7692e4062007
[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.
337 .TP
338 .B queue_without_daemon
339 If set to
340 .I no
341 , when multipathd stops, queueing will be turned off for all devices.
342 This is useful for devices that set no_path_retry.  If a machine is
343 shut down while all paths to a device are down, it is possible to hang waiting
344 for IO to return from the device after multipathd has been stopped. Without
345 multipathd running, access to the paths cannot be restored, and the kernel
346 cannot be told to stop queueing IO. Setting queue_without_daemon to
347 .I no
348 , avoids this problem. Default is
349 .I yes
350 .TP
351 .B bindings_file
352 The full pathname of the binding file to be used when the user_friendly_names option is set. Defaults to
353 .I /var/lib/multipath/bindings
354 .TP
355 .B log_checker_err
356 If set to
357 .I once
358 , multipathd logs the first path checker error at logging level 2. Any later
359 errors are logged at level 3 until the device is restored. If set to
360 .I always
361 , multipathd always logs the path checker error at logging level 2. Default is
362 .I always
363 .
364 .SH "blacklist section"
365 The
366 .I blacklist
367 section is used to exclude specific device from inclusion in the
368 multipath topology. It is most commonly used to exclude local disks or
369 LUNs for the array controller.
370 .LP
371 The following keywords are recognized:
372 .TP 17
373 .B wwid
374 The \fIWorld Wide Identification\fR of a device.
375 .TP
376 .B devnode
377 Regular expression of the device nodes to be excluded.
378 .TP
379 .B device
380 Subsection for the device description. This subsection recognizes the
381 .I vendor
382 and
383 .I product
384 keywords. For a full description of these keywords please see the
385 .I devices
386 section description.
387 .SH "blacklist_exceptions section"
388 The
389 .I blacklist_exceptions
390 section is used to revert the actions of the
391 .I blacklist
392 section, ie to include specific device in the
393 multipath topology. This allows to selectively include devices which
394 would normally be excluded via the
395 .I blacklist
396 section.
397 .LP
398 The following keywords are recognized:
399 .TP 17
400 .B wwid
401 The \fIWorld Wide Identification\fR of a device.
402 .TP
403 .B devnode
404 Regular expression of the device nodes to be excluded.
405 .TP
406 .B device
407 Subsection for the device description. This subsection recognizes the
408 .I vendor
409 and
410 .I product
411 keywords. For a full description of these keywords please see the
412 .I devices
413 section description.
414 .SH "multipaths section"
415 The only recognized attribute for the
416 .B multipaths
417 section is the
418 .I multipath
419 subsection.
420 .LP
421 The
422 .B multipath
423 subsection recognizes the following attributes:
424 .TP 17
425 .B wwid
426 Index of the container. Mandatory for this subsection.
427 .TP
428 .B alias
429 (Optional) symbolic name for the multipath map.
430 .LP
431 The following attributes are optional; if not set the default values
432 are taken from the
433 .I defaults
434 or
435 .I devices
436 section:
437 .sp 1
438 .PD .1v
439 .RS
440 .TP 18
441 .B path_grouping_policy
442 .TP
443 .B path_selector
444 .TP
445 .B prio
446 .TP
447 .B prio_args
448 .TP
449 .B failback
450 .TP
451 .B rr_weight
452 .TP
453 .B flush_on_last_del
454 .TP
455 .B no_path_retry
456 .TP
457 .B rr_min_io
458 .TP
459 .B rr_min_io_q
460 .TP
461 .B features
462 .RE
463 .PD
464 .LP
465 .SH "devices section"
466 The only recognized attribute for the
467 .B devices
468 section is the
469 .I device
470 subsection.
471 .LP
472 The
473 .I device
474 subsection recognizes the following attributes:
475 .TP 17
476 .B vendor
477 (Mandatory) Vendor identifier
478 .TP
479 .B product
480 (Mandatory) Product identifier
481 .TP
482 .B revision
483 (Optional) Revision identfier
484 .TP
485 .B product_blacklist
486 (Optional) Product strings to blacklist for this vendor
487 .TP
488 .B alias_prefix
489 (Optional) The user_friendly_names prefix to use for this
490 device type, instead of the default "mpath"
491 .TP
492 .B hardware_handler
493 (Optional) The hardware handler to use for this device type.
494 The following hardware handler are implemented:
495 .RS
496 .TP 12
497 .B 1 emc
498 Hardware handler for EMC storage arrays.
499 .TP
500 .B 1 rdac
501 Hardware handler for LSI/Engenio/NetApp E-Series RDAC storage controller.
502 .TP
503 .B 1 hp_sw
504 Hardware handler for Compaq/HP storage arrays in active/standby
505 mode.
506 .TP
507 .B 1 alua
508 Hardware handler for SCSI-3 ALUA compatible arrays.
509 .RE
510 .LP
511 The following attributes are optional; if not set the default values
512 are taken from the
513 .I defaults
514 section:
515 .sp 1
516 .PD .1v
517 .RS
518 .TP 18
519 .B path_grouping_policy
520 .TP
521 .B getuid_callout
522 .TP
523 .B path_selector
524 .TP
525 .B path_checker
526 .TP
527 .B prio
528 .TP
529 .B prio_args
530 .TP
531 .B features
532 .TP
533 .B failback
534 .TP
535 .B rr_weight
536 .TP
537 .B no_path_retry
538 .TP
539 .B rr_min_io
540 .TP
541 .B rr_min_io_rq
542 .TP
543 .B fast_io_fail_tmo
544 .TP
545 .B dev_loss_tmo
546 .TP
547 .B flush_on_last_del
548 .RE
549 .PD
550 .LP
551 .SH "KNOWN ISSUES"
552 The usage of
553 .B queue_if_no_path
554 option can lead to
555 .B D state
556 processes being hung and not killable in situations where all the paths to the LUN go offline.
557 It is advisable to use the
558 .B no_path_retry
559 option instead.
560 .P
561 The use of
562 .B queue_if_no_path
563 or
564 .B no_path_retry
565 might lead to a deadlock if the
566 .B dev_loss_tmo
567 setting results in a device being removed while I/O is still queued.
568 The multipath daemon will update the
569 .B dev_loss_tmo
570 setting accordingly to avoid this deadlock. Hence if both values are
571 specified the order of precedence is
572 .I no_path_retry, queue_if_no_path, dev_loss_tmo
573
574 .SH "SEE ALSO"
575 .BR udev (8),
576 .BR dmsetup (8)
577 .BR multipath (8)
578 .BR multipathd (8)
579 .SH AUTHORS
580 .B multipath
581 was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com> and others.