7ed62de2ea6ba8fa85276d2ac20665178146bc9b
[multipath-tools/.git] / multipath.conf.annotated
1 ##
2 ## This is a template multipath-tools configuration file
3 ## Uncomment the lines relevent to your environment
4 ##
5 #
6 ##
7 ## name  : defaults
8 ## desc  : multipath-tools default settings
9 ##
10 #defaults {
11 #       #
12 #       # name    : udev_dir
13 #       # desc    : directory where udev creates its device nodes
14 #       # default : /dev
15 #       #
16 #       udev_dir        /dev
17 #
18 #       #
19 #       # name    : polling_interval
20 #       # scope   : multipathd
21 #       # desc    : interval between two path checks in seconds. For
22 #       #           properly functioning paths, the interval between checks
23 #       #           will gradually increase to (4 * polling_interval).
24 #       # values  : n > 0
25 #       # default : 5
26 #       #
27 #       polling_interval 10
28 #
29 #       #
30 #       # name    : path_selector
31 #       # scope   : multipath & multipathd
32 #       # desc    : the default path selector algorithm to use
33 #       #           these algorithms are offered by the kernel multipath target
34 #       # values  : "round-robin 0"  = Loop through every path in the path group,
35 #       #                              sending the same amount of IO to each.
36 #       #           "queue-length 0" = Send the next bunch of IO down the path
37 #       #                              with the least amount of outstanding IO.
38 #       #           "service-time 0" = Choose the path for the next bunch of IO
39 #       #                              based on the amount of outstanding IO to
40 #       #                              the path and its relative throughput.
41 #       # default : "service-time 0"
42 #       #
43 #       path_selector   "service-time 0"
44 #
45 #       #
46 #       # name    : path_grouping_policy
47 #       # scope   : multipath & multipathd
48 #       # desc    : the default path grouping policy to apply to unspecified
49 #       #           multipaths
50 #       # values  : failover           = 1 path per priority group
51 #       #           multibus           = all valid paths in 1 priority group
52 #       #           group_by_serial    = 1 priority group per detected serial
53 #       #                                number
54 #       #           group_by_prio      = 1 priority group per path priority
55 #       #                                value
56 #       #           group_by_node_name = 1 priority group per target node name
57 #       # default : failover
58 #       #
59 #       path_grouping_policy    multibus
60 #
61 #       #
62 #       # name    : uid_attribute
63 #       # scope   : multipath & multipathd
64 #       # desc    : the default udev attribute from which the path
65 #       #           identifier should be generated.
66 #       # default : ID_SERIAL
67 #       #
68 #       uid_attribute   "ID_SERIAL"
69 #
70 #       #
71 #       # name    : getuid_callout
72 #       # scope   : multipath & multipathd
73 #       # desc    : the default program and args to callout to obtain a unique 
74 #       #           path identifier. This parameter is deprecated.
75 #       #           This parameter is deprecated, superseded by uid_attribute
76 #       # default : /lib/udev/scsi_id --whitelisted --device=/dev/%n
77 #       #
78 #       getuid_callout  "/lib/udev/scsi_id --whitelisted --device=/dev/%n"
79 #
80 #       #
81 #       # name    : prio
82 #       # scope   : multipath & multipathd
83 #       # desc    : the default function to call to obtain a path 
84 #       #           priority value. The ALUA bits in SPC-3 provide an
85 #       #           exploitable prio value for example.
86 #       # default : const
87 #       #
88 #       prio    "alua"
89 #
90 #       #
91 #       # name    : prio_args
92 #       # scope   : multipath & multipathd
93 #       # desc    : The arguments string passed to the prio function
94 #       #           Most prio functions do not need arguments. The
95 #       #           datacore prioritizer need one.
96 #       # default : (null)
97 #       #
98 #       prio_args       "timeout=1000 preferredsds=foo"
99 #
100 #       #
101 #       # name    : features
102 #       # scope   : multipath & multipathd
103 #       # desc    : The default extra features of multipath devices.
104 #       #           Syntax is "num[ feature_0 feature_1 ...]", where `num' is the
105 #       #           number of features in the following (possibly empty) list of
106 #       #           features.
107 #       # values  : queue_if_no_path = Queue IO if no path is active; consider
108 #       #                              using the `no_path_retry' keyword instead.
109 #       #           no_partitions    = Disable automatic partitions generation via
110 #       #                              kpartx.
111 #       # default : "0"
112 #       #
113 #       features        "0"
114 #       features        "1 queue_if_no_path"
115 #       features        "1 no_partitions"
116 #       features        "2 queue_if_no_path no_partitions"
117 #
118 #       #
119 #       # name    : path_checker, checker
120 #       # scope   : multipath & multipathd
121 #       # desc    : the default method used to determine the paths' state
122 #       # values  : readsector0|tur|emc_clariion|hp_sw|directio|rdac|cciss_tur
123 #       # default : directio
124 #       #
125 #       path_checker    directio
126 #
127 #       #
128 #       # name    : rr_min_io
129 #       # scope   : multipath & multipathd
130 #       # desc    : the number of IO to route to a path before switching
131 #       #           to the next in the same path group for the bio-based
132 #       #           multipath implementation. This parameter is used for
133 #       #           kernels version up to 2.6.31; newer kernel version
134 #       #           use the parameter rr_min_io_rq
135 #       # default : 1000
136 #       #
137 #       rr_min_io       1000
138 #
139 #       #
140 #       # name    : rr_min_io_rq
141 #       # scope   : multipath & multipathd
142 #       # desc    : the number of IO to route to a path before switching
143 #       #           to the next in the same path group for the request-based
144 #       #           multipath implementation. This parameter is used for
145 #       #           kernels versions later than 2.6.31.
146 #       # default : 1
147 #       #
148 #       rr_min_io_rq    1
149 #
150 #       #
151 #       # name    : flush_on_last_del
152 #       # scope   : multipathd
153 #       # desc    : If set to "yes", multipathd will disable queueing when the
154 #       #           last path to a device has been deleted.
155 #       # values  : yes|no
156 #       # default : no
157 #       #
158 #       flush_on_last_del       yes
159 #
160 #       #
161 #       # name    : max_fds
162 #       # scope   : multipathd
163 #       # desc    : Sets the maximum number of open file descriptors for the
164 #       #           multipathd process.
165 #       # values  : max|n > 0
166 #       # default : None
167 #       #
168 #       max_fds         8192
169 #
170 #       #
171 #       # name    : rr_weight
172 #       # scope   : multipath & multipathd
173 #       # desc    : if set to priorities the multipath configurator will assign
174 #       #           path weights as "path prio * rr_min_io"
175 #       # values  : priorities|uniform
176 #       # default : uniform
177 #       #
178 #       rr_weight       priorities
179 #
180 #       #
181 #       # name    : failback
182 #       # scope   : multipathd
183 #       # desc    : tell the daemon to manage path group failback, or not to.
184 #       #           0 means immediate failback, values >0 means deffered
185 #       #           failback expressed in seconds.
186 #       # values  : manual|immediate|n > 0
187 #       # default : manual
188 #       #
189 #       failback        immediate
190 #
191 #       #
192 #       # name    : no_path_retry
193 #       # scope   : multipath & multipathd
194 #       # desc    : tell the number of retries until disable queueing, or
195 #       #           "fail" means immediate failure (no queueing),
196 #       #           "queue" means never stop queueing
197 #       # values  : queue|fail|n (>0)
198 #       # default : (null)
199 #       #
200 #       no_path_retry  queue
201 #
202 #       #
203 #       # name    : queue_without_daemon
204 #       # scope   : multipathd
205 #       # desc    : If set to "no", multipathd will disable queueing for all
206 #       #           devices when it is shut down.
207 #       # values  : yes|no
208 #       # default : yes
209 #       queue_without_daemon    no
210 #
211 #       #
212 #       # name    : user_friendly_names
213 #       # scope   : multipath & multipathd
214 #       # desc    : If set to "yes", using the bindings file
215 #       #           /etc/multipath/bindings to assign a persistent and
216 #       #           unique alias to the multipath, in the form of mpath<n>.
217 #       #           If set to "no" use the WWID as the alias. In either case
218 #       #           this be will be overriden by any specific aliases in this
219 #       #           file.
220 #       # values  : yes|no
221 #       # default : no
222 #       user_friendly_names no
223 #
224 #       #
225 #       # name    : mode
226 #       # scope   : multipath & multipathd
227 #       # desc    : The mode to use for the multipath device nodes, in octal.
228 #       # values  : 0000 - 0777
229 #       # default : determined by the process
230 #       mode 0644
231 #
232 #       #
233 #       # name    : uid
234 #       # scope   : multipath & multipathd
235 #       # desc    : The user id to use for the multipath device nodes. You
236 #       #           may use either the numeric or symbolic uid
237 #       # values  : <user_id>
238 #       # default : determined by the process
239 #       uid 0
240 #
241 #       #
242 #       # name    : gid
243 #       # scope   : multipath & multipathd
244 #       # desc    : The group id to user for the multipath device nodes. You
245 #       #           may use either the numeric or symbolic gid
246 #       # values  : <group_id>
247 #       # default : determined by the process
248 #       gid disk
249 #
250 #       #
251 #       # name    : checker_timeout
252 #       # scope   : multipath & multipathd
253 #       # desc    : The timeout to use for path checkers that issue scsi
254 #       #           commands with an explicit timeout, in seconds.
255 #       # values  : n > 0
256 #       # default : taken from /sys/block/sd<x>/device/timeout
257 #       checker_timeout 60
258 #
259 #       #
260 #       # name    : fast_io_fail_tmo
261 #       # scope   : multipath & multipathd
262 #       # desc    : The number of seconds the scsi layer will wait after a
263 #       #           problem has been detected on a FC remote port before failing
264 #       #           IO to devices on that remote port.
265 #       # values  : off | n >= 0 (smaller than dev_loss_tmo)
266 #       # default : determined by the OS
267 #       fast_io_fail_tmo 5
268 #
269 #       #
270 #       # name    : dev_loss_tmo
271 #       # scope   : multipath & multipathd
272 #       # desc    : The number of seconds the scsi layer will wait after a
273 #       #           problem has been detected on a FC remote port before
274 #       #           removing it from the system.
275 #       # values  : infinity | n > 0
276 #       # default : determined by the OS
277 #       dev_loss_tmo 600
278 #
279 #       # name    : bindings_file
280 #       # scope   : multipath
281 #       # desc    : The location of the bindings file that is used with
282 #       #           the user_friendly_names option.
283 #       # values  : <full_pathname>
284 #       # default : "/var/lib/multipath/bindings"
285 #       bindings_file "/etc/multipath_bindings"
286 #
287 #}
288 #       
289 ##
290 ## name    : blacklist
291 ## scope   : multipath & multipathd
292 ## desc    : list of device names to discard as not multipath candidates
293 ##           Devices can be identified by their device node name "devnode",
294 ##           their WWID "wwid", or their vender and product strings
295 ##           "device"
296 ## default : fd, hd, md, dm, sr, scd, st, ram, raw, loop, dcssblk
297 ##
298 #blacklist {
299 #       wwid 26353900f02796769
300 #       devnode "^(ram|raw|loop|fd|md|dm-|sr|scd|st)[0-9]*"
301 #       devnode "^hd[a-z]"
302 #       devnode "^dcssblk[0-9]*"
303 #       device {
304 #               vendor DEC.*
305 #               product MSA[15]00
306 #       }
307 #}
308 ##
309 ## name    : blacklist_exceptions
310 ## scope   : multipath & multipathd
311 ## desc    : list of device names to be treated as multipath candidates
312 ##           even if they are on the blacklist.
313 ##           Note: blacklist exceptions are only valid in the same class.
314 ##           It is not possible to blacklist devices using the devnode keyword
315 ##           and to exclude some devices of them using the wwid keyword.
316 ## default : -
317 ##
318 #blacklist_exceptions {
319 #       devnode "^dasd[c-d]+[0-9]*"
320 #       wwid    "IBM.75000000092461.4d00.34"
321 #       wwid    "IBM.75000000092461.4d00.35"
322 #       wwid    "IBM.75000000092461.4d00.36"
323 #}
324 #
325 ##
326 ## name    : multipaths
327 ## scope   : multipath & multipathd
328 ## desc    : list of multipaths finest-grained settings
329 ##
330 #multipaths {
331 #       #
332 #       # name  : multipath
333 #       # scope : multipath & multipathd
334 #       # desc  : container for settings that apply to one specific multipath
335 #       #
336 #       multipath {
337 #               #
338 #               # name  : wwid
339 #               # scope : multipath & multipathd
340 #               # desc  : index of the container
341 #               #
342 #               wwid                    3600508b4000156d700012000000b0000
343 #
344 #               #
345 #               # name    : alias
346 #               # scope   : multipath & multipathd
347 #               # desc    : symbolic name for the multipath. If you are using
348 #               #           user_friendly_names, do not set the alias to
349 #               #           mpath<n>. This may conflict with an automatically
350 #               #           assigned user friendly name, and give you
351 #               #           incorrect device node names.
352 #               #
353 #               alias                   yellow
354 #
355 #               #
356 #               # name    : path_grouping_policy
357 #               # scope   : multipath & multipathd
358 #               # desc    : path grouping policy to apply to this multipath
359 #               # values  : failover, multibus, group_by_serial
360 #               # values  : failover           = 1 path per priority group
361 #               #           multibus           = all valid paths in 1 priority
362 #               #                                group
363 #               #           group_by_serial    = 1 priority group per detected
364 #               #                                serial number
365 #               #           group_by_prio      = 1 priority group per path
366 #               #                                priority value
367 #               #           group_by_node_name = 1 priority group per target
368 #               #                                node name
369 #               #
370 #               path_grouping_policy    failover
371 #
372 #               #
373 #               # name    : path_selector
374 #               # scope   : multipath & multipathd
375 #               # desc    : the path selector algorithm to use for this mpath
376 #               #           these algo are offered by the kernel mpath target
377 #               # values  : "round-robin 0"
378 #               #
379 #               path_selector           "round-robin 0"
380 #
381 #               #
382 #               # name    : failback
383 #               # scope   : multipathd
384 #               # desc    : tell the daemon to manage path group failback, or
385 #               #           not to. 0 means immediate failback, values >0 means
386 #               #           deffered failback expressed in seconds.
387 #               # values  : manual|immediate|n > 0
388 #               #
389 #               failback                manual
390 #
391 #               #
392 #               # name    : rr_weight
393 #               # scope   : multipath & multipathd
394 #               # desc    : if set to priorities the multipath configurator will
395 #               #           assign path weights as "path prio * rr_min_io"
396 #               # values  : priorities|uniform
397 #               #
398 #               rr_weight       priorities
399 #
400 #               #
401 #               # name    : no_path_retry
402 #               # scope   : multipath & multipathd
403 #               # desc    : tell the number of retries until disable queueing,
404 #               #           or "fail" means immediate failure (no queueing),
405 #               #           "queue" means never stop queueing
406 #               # values  : queue|fail|n (>0)
407 #               #
408 #               no_path_retry  queue
409 #
410 #               #
411 #               # name    : rr_min_io
412 #               # scope   : multipath & multipathd
413 #               # desc    : the number of IO to route to a path before switching
414 #               #           to the next in the same path group
415 #               #
416 #               rr_min_io       100
417 #
418 #               #
419 #               # name    : flush_on_last_del
420 #               # scope   : multipathd
421 #               # desc    : If set to "yes", multipathd will disable queueing
422 #               #           when the last path to a device has been deleted.
423 #               # values  : yes|no
424 #               # default : no
425 #               #
426 #               flush_on_last_del       yes
427 #
428 #               #
429 #               # name    : mode
430 #               # scope   : multipath & multipathd
431 #               # desc    : The mode to use for the multipath device nodes, in
432 #               #           octal.
433 #               # values  : 0000 - 0777
434 #               # default : determined by the process
435 #               mode 0644
436 #
437 #               #
438 #               # name    : uid
439 #               # scope   : multipath & multipathd
440 #               # desc    : The user id to use for the multipath device nodes.
441 #               #           You may use either the numeric or symbolic uid
442 #               # values  : <user_id>
443 #               # default : determined by the process
444 #               uid 0
445 #
446 #               #
447 #               # name    : gid
448 #               # scope   : multipath & multipathd
449 #               # desc    : The group id to user for the multipath device nodes.
450 #               #           You may use either the numeric or symbolic gid
451 #               # values  : <group_id>
452 #               # default : determined by the process
453 #               gid 0
454 #
455 #       }
456 #       multipath {
457 #               wwid    1DEC_____321816758474
458 #               alias   red
459 #               rr_weight               priorities
460 #       }
461 #}
462 #
463 ##
464 ## name  : devices
465 ## scope : multipath & multipathd
466 ## desc  : list of per storage controller settings
467 ##        overrides default settings (device_maps block)
468 ##         overriden by per multipath settings (multipaths block)
469 ##
470 #devices {
471 #       #
472 #       # name  : device
473 #       # scope : multipath & multipathd
474 #       # desc  : settings for this specific storage controller
475 #       #
476 #       device {
477 #               #
478 #               # name  : vendor, product
479 #               # scope : multipath & multipathd
480 #               # desc  : index for the block
481 #               #
482 #               vendor                  "COMPAQ  "
483 #               product                 "HSV110 (C)COMPAQ"
484 #
485 #               #
486 #               # name    : path_grouping_policy
487 #               # scope   : multipath & multipathd
488 #               # desc    : path grouping policy to apply to this multipath
489 #               # values  : failover, multibus, group_by_serial
490 #               # values  : failover           = 1 path per priority group
491 #               #           multibus           = all valid paths in 1 priority
492 #               #                                group
493 #               #           group_by_serial    = 1 priority group per detected
494 #               #                                serial number
495 #               #           group_by_prio      = 1 priority group per path
496 #               #                                priority value
497 #               #           group_by_node_name = 1 priority group per target
498 #               #                                node name
499 #               #
500 #               path_grouping_policy    failover
501 #
502 #               #
503 #               # name    : getuid_callout
504 #               # scope   : multipath & multipathd
505 #               # desc    : the program and args to callout to obtain a unique 
506 #               #           path identifier. Absolute path required
507 #               #
508 #               getuid_callout          "/lib/udev/scsi_id --whitelisted --device=/dev/%n"
509 #
510 #               #
511 #               # name    : prio
512 #               # scope   : multipath & multipathd
513 #               # desc    : the function to call to obtain a path 
514 #               #           weight. Weights are summed for each path group to
515 #               #           determine the next PG to use case of failure.
516 #               # default : no callout, all paths equals
517 #               #
518 #               prio          "hp_sw"
519 #
520 #               #
521 #               # name    : prio_args
522 #               # scope   : multipath & multipathd
523 #               # desc    : The arguments string passed to the prio function
524 #               #           Most prio functions do not need arguments. The
525 #               #           datacore prioritizer need one.
526 #               # default : (null)
527 #               #
528 #               prio_args       "timeout=1000 preferredsds=foo"
529 #
530 #               # name    : path_checker, checker
531 #               # scope   : multipathd & multipathd
532 #               # desc    : path checking algorithm to use to check path state
533 #               # values  : readsector0|tur|emc_clariion|hp_sw|directio|rdac|
534 #               #           cciss_tur
535 #               #
536 #               path_checker            directio
537 #
538 #               # as already described
539 #               path_selector           "service-time 0"
540 #
541 #               # as already described
542 #               features        "0"
543 #
544 #               #
545 #               # name    : hardware_handler
546 #               # scope   : multipath & multipathd
547 #               # desc    : If set, it specifies a module that will be used to
548 #               #           perform hardware specific actions when switching
549 #               #           path groups or handling IO errors
550 #               # values  : "0"|"1 emc"
551 #               # default : "0"
552 #               #
553 #               hardware_handler "1 emc"
554 #
555 #               #
556 #               # name    : failback
557 #               # scope   : multipathd
558 #               # desc    : tell the daemon to manage path group failback, or
559 #               #           not to. 0 means immediate failback, values >0 means
560 #               #           deffered failback expressed in seconds.
561 #               # values  : manual|immediate|n > 0
562 #               #
563 #               failback                30
564 #
565 #               #
566 #               # name    : rr_weight
567 #               # scope   : multipath & multipathd
568 #               # desc    : if set to priorities the multipath configurator will
569 #               #           assign path weights as "path prio * rr_min_io"
570 #               # values  : priorities|uniform
571 #               #
572 #               rr_weight       priorities
573 #
574 #               #
575 #               # name    : no_path_retry
576 #               # scope   : multipath & multipathd
577 #               # desc    : tell the number of retries until disable queueing,
578 #               #           or "fail" means immediate failure (no queueing),
579 #               #           "queue" means never stop queueing
580 #               # values  : queue|fail|n (>0)
581 #               #
582 #               no_path_retry  queue
583 #
584 #               #
585 #               # name    : rr_min_io
586 #               # scope   : multipath & multipathd
587 #               # desc    : the number of IO to route to a path before switching
588 #               #           to the next in the same path group
589 #               #
590 #               rr_min_io       100
591 #
592 #               #
593 #               # name    : flush_on_last_del
594 #               # scope   : multipathd
595 #               # desc    : If set to "yes", multipathd will disable queueing
596 #               #           when the last path to a device has been deleted.
597 #               # values  : yes|no
598 #               #
599 #               flush_on_last_del       yes
600 #
601 #               #
602 #               # name    : product_blacklist
603 #               # scope   : multipath & multipathd
604 #               # desc    : product strings to blacklist for this vendor
605 #               #
606 #               product_blacklist       LUN_Z
607 #
608 #               #
609 #               # name    : fast_io_fail_tmo
610 #               # scope   : multipath & multipathd
611 #               # desc    : The number of seconds the scsi layer will wait after
612 #               #           a problem has been detected on a FC remote port
613 #               #           before failing IO to devices on that remote port.
614 #               # values  : off | n >= 0 (smaller than dev_loss_tmo)
615 #               fast_io_fail_tmo 5
616 #
617 #               #
618 #               # name    : dev_loss_tmo
619 #               # scope   : multipath & multipathd
620 #               # desc    : The number of seconds the scsi layer will wait after
621 #               #           a problem has been detected on a FC remote port
622 #               #           before removing it from the system.
623 #               # values  : n > 0
624 #               dev_loss_tmo 600
625 #       }
626 #       device {
627 #               vendor                  "COMPAQ  "
628 #               product                 "MSA1000         "
629 #               path_grouping_policy    multibus
630 #               path_checker            tur
631 #               rr_weight               priorities
632 #       }
633 #}