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