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