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