1MULTIPATH.CONF(5) File Formats Manual MULTIPATH.CONF(5)
2
6 multipath.conf - multipath daemon configuration file
7
9 multipath.conf is the configuration file for the multipath daemon. It
10 is used to overwrite the built-in configuration table of multipathd.
11 Any line whose first non-white-space character is a '#' is considered a
12 comment line. Empty lines are ignored.
13
15 The configuration file contains entries of the form:
16 <section> {
18 <attribute> <value>
19 ...
20 <subsection> {
21 <attribute> <value>
22 ...
23 }
24 }
25 Each section contains one or more attributes or subsections. The recog‐
27 nized keywords for attributes or subsections depend on the section in
28 which they occor.
29 The following section keywords are recognized:
31 defaults This section defines default values for attributes
33 which are used whenever no values are given in the
34 appropriate device or multipath sections.
35 blacklist This section defines which devices should be excluded
37 from the multipath topology discovery.
38 blacklist_exceptions
40 This section defines which devices should be included
41 in the multipath topology discovery, despite being
42 listed in the blacklist section.
43 multipaths This section defines the multipath topologies. They
45 are indexed by a World Wide Identifier(wwid), which is
46 taken to be the value of the udev attribute given by
47 the uid_attribute keyword.
48 devices This section defines the device-specific settings.
50
52 The defaults section recognizes the following keywords:
53 polling_interval interval between two path checks in seconds. For prop‐
55 erly functioning paths, the interval between checks
56 will gradually increase to max_polling_interval;
57 default is 5
58 max_polling_interval
60 maximal interval between two path checks in seconds;
61 default is 4 * polling_interval
62 multipath_dir directory where the dynamic shared objects are stored;
64 default is system dependent, commonly /lib/multipath
65 find_multipaths If set to yes , instead of trying to create a multi‐
67 path device for every non-blacklisted path, multipath
68 will only create a device if one of three condidions
69 are met. 1 There are at least two non-blacklisted
70 paths with the same wwid, 2 the user manually forces
71 the creation, by specifying a device with the multi‐
72 path command, or 3 a path has the same WWID as a mul‐
73 tipath device that was previously created while
74 find_multipaths was set (even if that multipath device
75 doesn't currently exist). Whenever a multipath device
76 is created with find_multipaths set, multipath will
77 remeber the WWID of the device, so that it will auto‐
78 matically create the device again, as soon as it sees
79 a path with that WWID. This should allow most users to
80 have multipath automatically choose the correct paths
81 to make into multipath devices, without having to edit
82 the blacklist; Default is no
83 verbosity default verbosity. Higher values increase the ver‐
85 bosity level. Valid levels are between 0 and 6;
86 default is 2
87 reassign_maps enable reassigning of device-mapper maps. With this
89 option multipathd will remap existing device-mapper
90 maps to always point to multipath device, not the
91 underlying block devices. Possible values are yes and
92 no. Default is yes
93 path_selector The default path selector algorithm to use; they are
95 offered by the kernel multipath target. There are
96 three selector algorithms.
97 round-robin 0
99 Loop through every path in the path group,
100 sending the same amount of IO to each.
101 queue-length 0
103 Send the next bunch of IO down the path
104 with the least amount of outstanding IO.
105 service-time 0
107 Choose the path for the next bunch of IO
108 based on the amount of outstanding IO to
109 the path and its relative throughput.
110 path_grouping_policy
112 The default path grouping policy to apply to unspeci‐
113 fied multipaths. Possible values are
114 failover 1 path per priority group
116 multibus all paths in 1 priority group
118 group_by_serial
120 1 priority group per serial number
121 group_by_prio
123 1 priority group per priority value. Pri‐
124 orities are determined by callout programs
125 specified as a global, per-controller or
126 per-multipath option in the configuration
127 file.
128 group_by_node_name
130 1 priority group per target node name.
131 Target node names are fetched in
132 /sys/class/fc_transport/target*/node_name.
133 Default value is failover.
135 uid_attribute The udev attribute providing a unique path identifier.
137 Default value is ID_SERIAL
138 prio The name of the path priority routine. The specified
140 routine should return a numeric value specifying the
141 relative priority of this path. Higher number have a
142 higher priority. none is a valid value. Currently the
143 following path priority routines are implemented:
144 const Return a constant priority of 1.
146 emc Generate the path priority for EMC arrays.
148 alua Generate the path priority based on the
150 SCSI-3 ALUA settings. This prioritizer
151 accepts the optional prio_arg exclu‐
152 sive_pref_bit
153 ontap Generate the path priority for NetApp
155 arrays.
156 rdac Generate the path priority for LSI/Enge‐
158 nio/NetApp E-Series RDAC controller.
159 hp_sw Generate the path priority for Compaq/HP
161 controller in active/standby mode.
162 hds Generate the path priority for Hitachi HDS
164 Modular storage arrays.
165 random Generate a random priority between 1 and
167 10.
168 weightedpath
170 Generate the path priority based on the
171 regular expression and the priority pro‐
172 vided as argument. requires prio_args key‐
173 word.
174 Default value is const.
176 prio_args Arguments to pass to to the prio function. This only
178 applies to certain prioritizers
179 weighted Needs a value of the form <hbtl|dev‐
181 name|wwn> <regex1> <prio1> <regex2>
182 <prio2> ... hbtl regex can be of SCSI
183 H:B:T:L format Ex: 1:0:.:. , *:0:0:.
184 devname regex can be of device name format
185 Ex: sda , sd.e wwn regex can be of the
186 form host_wwnn:host_wwpn:target_wwnn:tar‐
187 get_wwpn these values can be looked up
188 through sysfs or by running mulitpathd
189 show paths format %N:%R:%n:%r Ex:
190 0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.*
191 , .*:.*:iqn.2009-10.com.red‐
192 hat.msp.lab.ask-06:.*
193 alua If exclusive_pref_bit is set, paths with
195 the TPGS pref bit set will always be in
196 their own path group.
197 features Specify any device-mapper features to be used. Syntax
199 is num list where num is the number, between 0 and 6,
200 of features in list. Possible values for the feature
201 list are:
202 queue_if_no_path
204 Queue IO if no path is active; identical
205 to the no_path_retry keyword.
206 pg_init_retries
208 Number of times to retry pg_init, it must
209 be between 1 and 50.
210 pg_init_delay_msecs
212 Number of msecs before pg_init retry, it
213 must be between 0 and 60000.
214 path_checker The default method used to determine the paths state.
216 Possible values are
217 readsector0 (Deprecated) Read the first sector of the
219 device. This checker is being deprecated,
220 please use directio instead
221 tur Issue a TEST UNIT READY command to the
223 device.
224 emc_clariion
226 Query the EMC Clariion specific EVPD page
227 0xC0 to determine the path state.
228 hp_sw Check the path state for HP storage arrays
230 with Active/Standby firmware.
231 rdac Check the path state for LSI/Enge‐
233 nio/NetApp E-Series RDAC storage con‐
234 troller.
235 directio Read the first sector with direct I/O.
237 none Do not check the device, fallback to use
239 the values retrieved from sysfs
240 Default value is directio.
242 failback Tell multipathd how to manage path group failback.
244 immediate Immediately failback to the highest prior‐
246 ity pathgroup that contains active paths.
247 manual Do not perform automatic failback.
249 followover Only perform automatic failback when the
251 first path of a pathgroup becomes active.
252 This keeps a node from automatically fail‐
253 ing back when another node requested the
254 failover.
255 values > 0 deferred failback (time to defer in sec‐
257 onds)
258 Default value is manual.
260 rr_min_io The number of IO to route to a path before switching
262 to the next in the same path group. This is only for
263 BIO based multipath. Default is 1000
264 rr_min_io_rq The number of IO requests to route to a path before
266 switching to the next in the same path group. This is
267 only for request based multipath. Default is 1
268 rr_weight If set to priorities the multipath configurator will
270 assign path weights as "path prio * rr_min_io". Possi‐
271 ble values are priorities or uniform. Default is uni‐
272 form.
273 no_path_retry Specify the number of retries until disable queueing,
275 or fail for immediate failure (no queueing), queue for
276 never stop queueing. Default is 0.
277 user_friendly_names
279 If set to yes , using the bindings file /etc/multi‐
280 path/bindings to assign a persistent and unique alias
281 to the multipath, in the form of mpath<n>. If set to
282 no use the WWID as the alias. In either case this be
283 will be overridden by any specific aliases in the mul‐
284 tipaths section. Default is no
285 flush_on_last_del
287 If set to yes , multipathd will disable queueing when
288 the last path to a device has been deleted. Default is
289 no
290 max_fds Specify the maximum number of file descriptors that
292 can be opened by multipath and multipathd. This is
293 equivalent to ulimit -n. A value of max will set this
294 to the system limit from /proc/sys/fs/nr_open. If this
295 is not set, the maximum number of open fds is taken
296 from the calling process. It is usually 1024. To be
297 safe, this should be set to the maximum number of
298 paths plus 32, if that number is greated than 1024.
299 checker_timeout Specify the timeout to use for path checkers and pri‐
301 oritizers that issue scsi commands with an explicit
302 timeout, in seconds; default taken from
303 /sys/block/sd<x>/device/timeout
304 fast_io_fail_tmo Specify the number of seconds the scsi layer will wait
306 after a problem has been detected on a FC remote port
307 before failing IO to devices on that remote port.
308 This should be smaller than dev_loss_tmo. Setting this
309 to off will disable the timeout.
310 dev_loss_tmo Specify the number of seconds the scsi layer will wait
312 after a problem has been detected on a FC remote port
313 before removing it from the system. This can be set to
314 "infinity" which sets it to the max value of
315 2147483647 seconds, or 68 years. It will be automati‐
316 cally adjusted to the overall retry interval
317 no_path_retry * polling_interval if a number of
318 retries is given with no_path_retry and the overall
319 retry interval is longer than the specified
320 dev_loss_tmo value. The linux kernel will cap this
321 value to 600 if fast_io_fail_tmo is not set.
322 queue_without_daemon
324 If set to no , when multipathd stops, queueing will be
325 turned off for all devices. This is useful for
326 devices that set no_path_retry. If a machine is shut
327 down while all paths to a device are down, it is pos‐
328 sible to hang waiting for IO to return from the device
329 after multipathd has been stopped. Without multipathd
330 running, access to the paths cannot be restored, and
331 the kernel cannot be told to stop queueing IO. Setting
332 queue_without_daemon to no , avoids this problem.
333 Default is no
334 bindings_file The full pathname of the binding file to be used when
336 the user_friendly_names option is set. Defaults to
337 /etc/multipath/bindings
338 wwids_file The full pathname of the wwids file, which is used by
340 multipath to keep track of the wwids for LUNs it has
341 created multipath devices on in the past. Defaults to
342 /etc/multipath/wwids
343 prkeys_file The full pathname of the prkeys file, which is used by
345 multipathd to keep track of the reservation key used
346 for a specific WWID, when reservation_key is set to
347 file. Defaults to /etc/multipath/prkeys
348 log_checker_err If set to once , multipathd logs the first path
350 checker error at logging level 2. Any later errors are
351 logged at level 3 until the device is restored. If set
352 to always , multipathd always logs the path checker
353 error at logging level 2. Default is always
354 reservation_key This is the service action reservation key used by
356 mpathpersist. It must be set for all multipath
357 devices using persistent reservations, and it must be
358 the same as the RESERVATION KEY field of the PERSIS‐
359 TENT RESERVE OUT parameter list which contains an
360 8-byte value provided by the application client to the
361 device server to identify the I_T nexus. If the
362 --param-aptpl option is used when registering the key
363 with mpathpersist, :aptpl must be appended to the end
364 of the reservation key.
365 Alternatively, this can be set to file, which will
368 store the RESERVATION KEY registered by mpathpersist
369 in the prkeys_file. multipathd will then use this key
370 to register additional paths as they appear. When the
371 registration is removed, the RESERVATION KEY is
372 removed from the prkeys_file. The prkeys file will
373 automatically keep track of whether the key was regis‐
374 tered with --param-aptpl. It is unset by default.
375 all_tg_pt This must be set to yes to successfully use mpathper‐
377 sist on arrays that automatically set and clear regis‐
378 tration keys on all target ports from a host, instead
379 of per target port per host. Default is no
380 retain_attached_hw_handler
382 If set to yes and the scsi layer has already attached
383 a hardware_handler to the device, multipath will not
384 force the device to use the hardware_handler specified
385 by mutipath.conf. If the scsi layer has not attached a
386 hardware handler, multipath will continue to use its
387 configured hardware handler. Default is no
388 detect_prio If set to yes , multipath will try to detect if the
390 device supports ALUA. If so, the device will automati‐
391 cally use the alua prioritizer. If not, the priori‐
392 tizer will be selected as usual. Default is no
393 detect_checker If set to yes , multipath will try to detect if the
395 device supports ALUA. If so, the device will automati‐
396 cally use the tur checker. If not, the prioritizer
397 will be selected as ususal. Default is no
398 hw_str_match If set to yes , the vendor, product, and revision
400 parameters of user device configs will be string
401 matched against the built-in device configs to deter‐
402 mine if they should modify an existing config, or cre‐
403 ate a new one. If set to no , the user device configs
404 will be regular expression matched against the built-
405 in configs instead. Default is no
406 force_sync If set to yes , multipathd will call the path checkers
408 in sync mode only. This means that only one checker
409 will run at a time. This is useful in the case where
410 many multipathd checkers running in parallel causes
411 significant CPU pressure. The Default is no
412 deferred_remove If set to yes , multipathd will do a deferred remove
414 instead of a regular remove when the last path device
415 has been deleted. This means that if the multipath
416 device is still in use, it will be freed when the last
417 user closes it. If path is added to the multipath
418 device before the last user closes it, the deferred
419 remove will be canceled. Default is no
420 config_dir If set to anything other than "", multipath will
422 search this directory alphabetically for file ending
423 in ".conf" and it will read configuration information
424 from them, just as if it was in /etc/multipath.conf.
425 config_dir must either be "" or a fully qualified
426 directory name. Default is /etc/multipath/conf.d
427 delay_watch_checks
429 If set to a value greater than 0, multipathd will
430 watch paths that have recently become valid for this
431 many checks. If they fail again while they are being
432 watched, when they next become valid, they will not be
433 used until they have stayed up for delay_wait_checks
434 checks. Default is no
435 delay_wait_checks
437 If set to a value greater than 0, when a device that
438 has recently come back online fails again within
439 delay_watch_checks checks, the next time it comes back
440 online, it will marked and delayed, and not used until
441 it has passed delay_wait_checks checks. Default is no
442 missing_uev_wait_timeout
444 Controls how many seconds multipathd will wait, after
445 a new multipath device is created, to receive a change
446 event from udev for the device, before automatically
447 enabling device reloads. Usually multipathd will delay
448 reloads on a device until it receives a change uevent
449 from the initial table load. The default is 30
450 skip_kpartx If set to yes , kpartx will not automatically create
452 partitions on the device. The default is no
453 ignore_new_boot_devs
455 If set to yes , multipath will never attempt to create
456 a multipath device whose wwid is not listed in
457 /etc/multipath/wwids, while running in the initramfs.
458 This keeps multipath from adding new devices during
459 the initramfs portion of bootup. The default is no
460 retrigger_tries This sets how many times multipathd will reissue
462 change uevents on block devices that are not black‐
463 listed, but have no wwid set by udev. Multipath
464 assumes that any devices that should not report a wwid
465 are blacklisted. This means that if a non-blacklisted
466 device has no wwid, it is likely that udev timed out
467 while processing it. Multipathd will wait for a
468 while, and then reissue a change uevent to give udev
469 another chance to set the wwid. The default is 3
470 retrigger_delay This sets how long multipathd should wait, after
472 receiving a uevent for a non-blacklisted device with‐
473 out a wwid set by udev, before reissuing a change
474 uevent. The goal of this delay is to give udev a
475 chance to finish processing its current batch of
476 uevents before sending more, to hopefully avoid it
477 timing out. The default is 10
478 new_bindings_in_boot
480 If set to yes , multipath will allow new
481 user_friendly_names bindings to be created while run‐
482 ning in the initramfs. Otherwise, multipath will not
483 create user_friendly_names bindings while running in
484 the initramfs. Instead, it will use the WWID for the
485 name of a device that was configured to use
486 user_friendly_names. When multipathd is restarted
487 later in boot on the regular filesystem, the device
488 will be renamed to a user_friendly_name. The default
489 is no
490 disable_changed_wwids
492 If set to yes, multipathd will check the path wwid on
493 change events, and if it has changed from the wwid of
494 the multipath device, multipathd will disable access
495 to the path until the wwid changes back. The default
496 is no
497 remove_retries This sets how may times multipath will retry removing
499 a device that is in-use. Between each attempt, multi‐
500 path will sleep 1 second. The default is 0
501 max_sectors_kb Sets the max_sectors_kb device parameter on all path
503 devices and the multipath device to the specified
504 value. Default is device dependent.
505 unpriv_sgio If set to yes, multipath will set upriv_sgio on the
507 multipath device and all its paths, when it is created
508 or reloaded. The default is no
509 ghost_delay Sets the number of seconds that multipath will wait
511 after creating a device with only ghost paths before
512 marking it ready for use in systemd. This gives the
513 active paths time to appear before the multipath runs
514 the hardware handler to switch the ghost paths to
515 active ones. Setting this to 0 or off makes multipath
516 immediately mark a device with only ghost paths as
517 ready. The default is off
518
520 The blacklist section is used to exclude specific device from inclusion
521 in the multipath topology. It is most commonly used to exclude local
522 disks or LUNs for the array controller.
523 The following keywords are recognized:
525 wwid The World Wide Identification of a device.
527 devnode Regular expression of the device nodes to be excluded.
529 property Regular expresion of the udev property to be excluded.
531 protocol Regular expression of the protocol to be excluded. See
533 below for a list of recognized protocols
534 device Subsection for the device description. This subsection
536 recognizes the vendor and product keywords. For a full
537 description of these keywords please see the devices
538 section description.
539 The protocol strings that multipath recognizes are scsi:fcp, scsi:spi,
541 scsi:ssa, scsi:sbp, scsi:srp, scsi:iscsi, scsi:sas, scsi:adt, scsi:ata,
542 scsi:unspec, ccw, cciss, nvme, and undef. The protocol that a path is
543 using can be viewed by running multipathd show paths format "%d %P"
544
546 The blacklist_exceptions section is used to revert the actions of the
547 blacklist section, ie to include specific device in the multipath
548 topology. This allows one to selectively include devices which would
549 normally be excluded via the blacklist section.
550 The following keywords are recognized:
552 wwid The World Wide Identification of a device.
554 property Regular expresion of the udev property to be
556 whitelisted.
557 protocol Regular expression of the protocol to be whitelisted.
559 See the blacklist section for a list of recognized
560 protocols
561 devnode Regular expression of the device nodes to be
563 whitelisted.
564 device Subsection for the device description. This subsection
566 recognizes the vendor and product keywords. For a full
567 description of these keywords please see the devices
568 section description.
569 The property blacklist and whitelist handling is different from the
571 usual handling in the sense that if the whitelist is set, it has to
572 match, otherwise the device will be blacklisted. In these cases the
573 message blacklisted, udev property missing will be displayed. For exam‐
574 ple settting the property blacklist_exception to (SCSI_IDENT_|ID_WWN)
575 will blacklist all devices that have no udev property whose name regex
576 matches either SCSI_IDENT_ or ID_WWN. This works to exclude most non-
577 multipathable devices.
578
580 The only recognized attribute for the multipaths section is the multi‐
581 path subsection.
582 The multipath subsection recognizes the following attributes:
584 wwid Index of the container. Mandatory for this subsection.
586 alias (Optional) symbolic name for the multipath map.
588 The following attributes are optional; if not set the default values
590 are taken from the defaults or devices section:
591 path_grouping_policy
593 path_selector
594 prio
595 prio_args
596 failback
597 rr_weight
598 flush_on_last_del
599 user_friendly_names
600 no_path_retry
601 rr_min_io
602 rr_min_io_q
603 features
604 reservation_key
605 deferred_remove
606 delay_watch_checks
607 delay_wait_checks
608 skip_kpartx
609 max_sectors_kb
610 unpriv_sgio
611 ghost_delay
612
614 The only recognized attribute for the devices section is the device
615 subsection.
616 The device subsection recognizes the following attributes:
618 vendor (Mandatory) Vendor identifier
620 product (Mandatory) Product identifier
622 revision (Optional) Revision identfier
624 product_blacklist
626 (Optional) Product strings to blacklist for this ven‐
627 dor
628 alias_prefix (Optional) The user_friendly_names prefix to use for
630 this device type, instead of the default "mpath"
631 hardware_handler (Optional) The hardware handler to use for this device
633 type. The following hardware handler are implemented:
634 1 emc Hardware handler for EMC storage arrays.
636 1 rdac Hardware handler for LSI/Engenio/NetApp E-
638 Series RDAC storage controller.
639 1 hp_sw Hardware handler for Compaq/HP storage
641 arrays in active/standby mode.
642 1 alua Hardware handler for SCSI-3 ALUA compati‐
644 ble arrays.
645 The following attributes are optional; if not set the default values
647 are taken from the defaults section:
648 path_grouping_policy
650 uid_attribute
651 path_selector
652 path_checker
653 prio
654 prio_args
655 features
656 failback
657 rr_weight
658 no_path_retry
659 user_friendly_names
660 rr_min_io
661 rr_min_io_rq
662 fast_io_fail_tmo
663 dev_loss_tmo
664 flush_on_last_del
665 retain_attached_hw_handler
666 detect_prio
667 deferred_remove
668 delay_watch_checks
669 delay_wait_checks
670 skip_kpartx
671 max_sectors_kb
672 unpriv_sgio
673 ghost_delay
674
676 The usage of queue_if_no_path option can lead to D state processes
677 being hung and not killable in situations where all the paths to the
678 LUN go offline. It is advisable to use the no_path_retry option
679 instead.
680 The use of queue_if_no_path or no_path_retry might lead to a deadlock
682 if the dev_loss_tmo setting results in a device being removed while I/O
683 is still queued. The multipath daemon will update the dev_loss_tmo
684 setting accordingly to avoid this deadlock. Hence if both values are
685 specified the order of precedence is no_path_retry, queue_if_no_path,
686 dev_loss_tmo
687
690 udev(8), dmsetup(8) multipath(8) multipathd(8)
691
693 multipath was developed by Christophe Varoqui, <christophe.varo‐
694 qui@opensvc.com> and others.
695 30 November 2006 MULTIPATH.CONF(5)