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 settings for devices-map‐
33 per-multipath. These values can be overwritten by the
34 devices and multipaths 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 settings for individual mul‐
45 tipath devices. These values overwrite what is speci‐
46 fied in the defaults and devices section of the con‐
47 figuration file. The devices are identified by the
48 wwid keyword, which is a regular expression that must
49 match the result of the getuid_callout program.
50 devices This section defines the settings for individual stor‐
52 age controller types. These value overwrite what is
53 specified in the defaults section of the configuration
54 file. These controller types are identified by the
55 vendor, product, and revision keywords, which are reg‐
56 ular expressions that must match the sysfs information
57 about this device. If you are using a storage array
58 that is not supported by default, you may need to cre‐
59 ate a devices subsection for your array.
60 The priority of configuration in multipath.conf is:
62 multipaths is greater than devices is greater that defaults
63
65 The defaults section recognizes the following keywords:
66 polling_interval interval between two path checks in seconds For prop‐
68 erly functioning paths, the interval between checks
69 will gradually increase to (4 * polling_interval);
70 default is 5
71 udev_dir directory where udev creates its device nodes; default
73 is /dev
74 multipath_dir directory where the dynamic shared objects are stored;
76 default is system dependent, commonly /lib/multipath
77 find_multipaths If set to yes , instead of trying to create a multi‐
79 path device for every non-blacklisted path, multipath
80 will only create a device if one of three condidions
81 are met. 1 There are at least two non-blacklisted
82 paths with the same wwid, 2 the user manually forces
83 the creation, by specifying a device with the multi‐
84 path command, or 3 a path has the same WWID as a mul‐
85 tipath device that was previously created while
86 find_multipaths was set (even if that multipath device
87 doesn't currently exist). Whenever a multipath device
88 is created with find_multipaths set, multipath will
89 remeber the WWID of the device, so that it will auto‐
90 matically create the device again, as soon as it sees
91 a path with that WWID. This should allow most users to
92 have multipath automatically choose the correct paths
93 to make into multipath devices, without having to edit
94 the blacklist; Default is no
95 verbosity default verbosity. Higher values increase the ver‐
97 bosity level. Valid levels are between 0 and 6;
98 default is 2
99 path_selector The default path selector algorithm to use; they are
101 offered by the kernel multipath target. There are
102 three selector algorithms.
103 round-robin 0
105 Loop through every path in the path group,
106 sending the same amount of IO to each.
107 queue-length 0
109 Send the next bunch of IO down the path
110 with the least amount of outstanding IO.
111 service-time 0
113 Choose the path for the next bunch of IO
114 based on the amount of outstanding IO to
115 the path and its relative throughput.
116 path_grouping_policy
118 The default path grouping policy to apply to unspeci‐
119 fied multipaths. Possible values are
120 failover 1 path per priority group
122 multibus all paths in 1 priority group
124 group_by_serial
126 1 priority group per serial number
127 group_by_prio
129 1 priority group per priority value. Pri‐
130 orities are determined by callout programs
131 specified as a global, per-controller or
132 per-multipath option in the configuration
133 file.
134 group_by_node_name
136 1 priority group per target node name.
137 Target node names are fetched in
138 /sys/class/fc_transport/target*/node_name.
139 Default value is multibus.
141 getuid_callout The default program and args to callout to obtain a
143 unique path identifier. Should be specified with an
144 absolute path. Default value is /lib/udev/scsi_id
145 --whitelisted --device=/dev/%n
146 prio The default method used to obtain a path priority
148 value. Possible values are
149 const Set a priority of one to all paths
151 emc Generate the path priority for EMC arrays
153 alua Generate the path priority based on the
155 SCSI-3 ALUA settings. This prioritizer has
156 one optional argument exclusive_pref_bit
157 tpg_pref Generate the path prority based on the
160 SCSI-3 ALUA settings, using the preferred
161 port bit.
162 ontap Generate the path priority for NetApp
164 arrays.
165 rdac Generate the path priority for LSI/Enge‐
167 nio/NetApp E-Series RDAC controller.
168 hp_sw Generate the path priority for Compaq/HP
170 controller in active/standby mode.
171 hds Generate the path priority for Hitachi HDS
173 Modular storage arrays.
174 weighted hbtl|devname <regex1> <prio1> <regex2>
176 <prio2> ... Generate the path priority
177 base on the regular expressions and the
178 priorities provided. hbtl regexes are of
179 the SCSI H:B:T:L format. Ex: 1:0:0:1 ,
180 5:.* devname regexes are device names Ex:
181 sda , sd.e Note: These values may change
182 on reboot, or if the device is removed.
183 Using this prioritizer may require edit‐
184 ting multipath.conf after bootup to cor‐
185 rectly set the priority.
186 Default value is const.
188 features Specify any device-mapper features to be used. Syntax
190 is num list where num is the number of features in
191 list. Possible values for the feature list are
192 queue_if_no_path
194 Queue IO if no path is active; identical
195 to the no_path_retry keyword.
196 no_partitions
198 Disable automatic partitions generation
199 via kpartx.
200 path_checker The default method used to determine the paths' state.
202 Possible values are
203 readsector0 Read the first sector of the device
205 tur Issue a TEST UNIT READY command to the
207 device.
208 emc_clariion
210 Query the EMC Clariion specific EVPD page
211 0xC0 to determine the path state.
212 hp_sw Check the path state for HP storage arrays
214 with Active/Standby firmware.
215 rdac Check the path state for LSI/Enge‐
217 nio/NetApp E-Series RDAC storage con‐
218 troller.
219 directio Read the first sector with direct I/O.
221 Default value is readsector0.
223 failback Tell multipathd how to manage path group failback.
225 immediate Immediately failback to the highest prior‐
227 ity pathgroup that contains active paths.
228 manual Do not perform automatic failback.
230 followover Only perform automatic failback when the
232 first path of a pathgroup becomes active.
233 This keeps a node from automatically fail‐
234 ing back when another node requested the
235 failover.
236 values > 0 deferred failback (time to defer in sec‐
238 onds)
239 Default value is manual.
241 rr_min_io The number of IO to route to a path before switching
243 to the next in the same path group, using bio-based
244 device-mapper-multipath. This is only for systems run‐
245 ning kernels older that 2.6.31. Newer systems should
246 use rr_min_io_rq. Default is 1000
247 rr_min_io_rq The number of IO to route to a path before switching
249 to the next in the same path group, using request-
250 based device-mapper-multipath. This setting should be
251 used on systems running current kernels. On systems
252 running kernels older than 2.6.31, use rr_min_io.
253 Default is 1
254 rr_weight If set to priorities the multipath configurator will
256 assign path weights as "path prio * rr_min_io". Possi‐
257 ble values are priorities or uniform uniform
258 no_path_retry Specify the number of retries until disable queueing,
260 or fail for immediate failure (no queueing), queue for
261 never stop queueing. Default is 0.
262 user_friendly_names
264 If set to yes , using the bindings file /etc/multi‐
265 path/bindings to assign a persistent and unique alias
266 to the multipath, in the form of mpath<n>. If set to
267 no use the WWID as the alias. In either case this be
268 will be overriden by any specific aliases in the mul‐
269 tipaths section. Default is no
270 queue_without_daemon
272 If set to no , multipathd will disable queueing for
273 all devices when it is shut down. Default is no
274 flush_on_last_del
276 If set to yes , multipathd will disable queueing when
277 the last path to a device has been deleted. Default is
278 no
279 max_fds Specify the maximum number of file descriptors that
281 can be opened by multipath and multipathd. This is
282 equivalent to ulimit -n. A value of max will set this
283 to the system limit from /proc/sys/fs/nr_open. If this
284 is not set, the maximum number of open fds is taken
285 from the calling process. It is usually 1024. To be
286 safe, this should be set to the maximum number of
287 paths plus 32, if that number is greated than 1024.
288 checker_timeout Specify the timeout to user for path checkers and pri‐
290 oritizers that issue scsi commands with an explicit
291 timeout, in seconds; default taken from
292 /sys/block/sd<x>/device/timeout
293 fast_io_fail_tmo Specify the number of seconds the scsi layer will wait
295 after a problem has been detected on a FC remote port
296 before failing IO to devices on that remote port.
297 This should be smaller than dev_loss_tmo. Setting this
298 to off will disable the timeout.
299 dev_loss_tmo Specify the number of seconds the scsi layer will wait
301 after a problem has been detected on a FC remote port
302 before removing it from the system. This can be set to
303 "infinity" which sets it to the max value of
304 2147483647 seconds, or 68 years.
305 log_checker_err If set to once , multipathd logs the first path
307 checker error at logging level 2. Any later errors are
308 logged at level 3 until the device is restored. If set
309 to always , multipathd always logs the path checker
310 error at logging level 2. Default is always
311 hwtable_regex_match
313 If set to yes , user device configs will be regular
314 expression matched against the builtin configs to
315 determine if they should modify an existing config or
316 create a new one. If set to no , user device configs
317 will be string matched against the builtin configs to
318 determine if they should modify an existing config or
319 create a new one. Default is no
320 reservation_key This is the service action reservation key used by
322 mpathpersist. It must be set for all multipath
323 devices using persistent reservations, and it must be
324 the same as the RESERVATION KEY field of the PERSIS‐
325 TENT RESERVE OUT parameter list which contains an
326 8-byte value provided by the application client to the
327 device server to identify the I_T nexus. It is unset
328 by default.
329 retain_attached_hw_handler
331 If set to yes and the scsi layer has already attached
332 a hardware_handler to the device, multipath will not
333 force the device to use the hardware_handler specified
334 by mutipath.conf. If the scsi layer has not attached a
335 hardware handler, multipath will continue to use its
336 configured hardware handler. Default is no
337 detect_prio If set to yes , multipath will try to detect if the
339 device supports ALUA. If so, the device will automati‐
340 cally use the alua prioritizer. If not, the priori‐
341 tizer will be selected as usual. Default is no
342 reload_readwrite If set to yes , multipathd will monitor change events
344 on path devices. When it receives a change event for
345 a path of a readonly multipath device, it will check
346 if the path is now read/write. If so, multipathd will
347 reload the multipath device to switch it to
348 read/write. Default is no
349 replace_wwid_whitespace
351 If set to yes devices using the default getuid callout
352 (scsi_id) will add --relace-whitespace to the callout
353 line. This will cause any whitespace in the wwid to
354 be replaced with one underscore.
355 force_sync If set to yes , multipathd will call the path checkers
357 in sync mode only. This means that only one checker
358 will run at a time. This is useful in the case where
359 many multipathd checkers running in parallel causes
360 significant CPU pressure. The Default is no
361 config_dir If set to anything other than "", multipath will
363 search this directory alphabetically for file ending
364 in ".conf" and it will read configuration information
365 from them, just as if it was in /etc/multipath.conf.
366 config_dir must either be "" or a fully qualified
367 directory name. Default is /etc/multipath/conf.d
368 delay_watch_checks
370 If set to a value greater than 0, multipathd will
371 watch paths that have recently become valid for this
372 many checks. If they fail again while they are being
373 watched, when they next become valid, they will not be
374 used until they have stayed up for delay_wait_checks
375 checks. Default is no
376 delay_wait_checks
378 If set to a value greater than 0, when a device that
379 has recently come back online fails again within
380 delay_watch_checks checks, the next time it comes back
381 online, it will marked and delayed, and not used until
382 it has passed delay_wait_checks checks. Default is no
383 skip_kpartx If set to yes , kpartx will not automatically create
385 partitions on the device. The default is no
386 disable_changed_wwids
388 If set to yes and the wwid of a path device changes
389 while it is part of a multipath device, multipath will
390 disable access to the path device until the wwid of
391 the path is restored to the wwid of the multipath
392 device. Default is no
393 max_sectors_kb Sets the max_sectors_kb device parameter on all path
395 devices and the multipath device to the specified
396 value. Default is device dependent.
397
399 The blacklist section is used to exclude specific device from inclusion
400 in the multipath topology. It is most commonly used to exclude local
401 disks or LUNs for the array controller.
402 The following keywords are recognized:
404 wwid The World Wide Identification of a device.
406 devnode Regular expression of the device nodes to be excluded.
408 device Subsection for the device description. This subsection
410 recognizes the vendor and product keywords. For a full
411 description of these keywords please see the devices
412 section description.
413
415 The blacklist_exceptions section is used to revert the actions of the
416 blacklist section, ie to include specific device in the multipath
417 topology. This allows to selectively include devices which would nor‐
418 mally be excluded via the blacklist section.
419 The following keywords are recognized:
421 wwid The World Wide Identification of a device.
423 devnode Regular expression of the device nodes to be excluded.
425 device Subsection for the device description. This subsection
427 recognizes the vendor and product keywords. For a full
428 description of these keywords please see the devices
429 section description.
430
432 The only recognized attribute for the multipaths section is the multi‐
433 path subsection.
434 The multipath subsection recognizes the following attributes:
436 wwid Index of the container. Mandatory for this subsection.
438 alias (Optional) symbolic name for the multipath map.
440 The following attributes are optional; if not set the default values
442 are taken from the defaults section:
443 path_grouping_policy
445 path_selector
446 failback
447 prio
448 no_path_retry
449 rr_min_io
450 rr_min_io_rq
451 rr_weight
452 flush_on_last_del
453 reservation_key
454 delay_watch_checks
455 delay_wait_checks
456 skip_kpartx
457 max_sectors_kb
458
460 The only recognized attribute for the devices section is the device
461 subsection.
462 The device subsection recognizes the following attributes:
464 vendor (Mandatory) Vendor identifier
466 product (Mandatory) Product identifier
468 revision Revision identifier
470 product_blacklist
472 Product strings to blacklist for this vendor
473 hardware_handler (Optional) The hardware handler to use for this device
475 type. The following hardware handler are implemented:
476 1 emc Hardware handler for EMC storage arrays.
478 1 alua Hardware handler for SCSI-3 ALUA arrays.
480 1 hp_sw Hardware handler for Compaq/HP con‐
482 trollers.
483 1 rdac Hardware handler for the LSI/Enge‐
485 nio/NetApp E-Series RDAC storage con‐
486 troller.
487 The following attributes are optional; if not set the default values
489 are taken from the defaults section:
490 path_grouping_policy
492 getuid_callout
493 path_selector
494 path_checker
495 features
496 prio
497 failback
498 rr_weight
499 no_path_retry
500 rr_min_io
501 rr_min_io_rq
502 fast_io_fail_tmo
503 dev_loss_tmo
504 flush_on_last_del
505 retain_attached_hw_handler
506 detect_prio
507 reload_readwrite
508 delay_watch_checks
509 delay_wait_checks
510 skip_kpartx
511 max_sectors_kb
512
514 The usage of queue_if_no_path option can lead to D state processes
515 being hung and not killable in situations where all the paths to the
516 LUN go offline. It is advisable to use the no_path_retry option
517 instead.
518
520 udev(8), dmsetup(8) multipath(8) multipathd(8)
521
523 multipath was developed by Christophe Varoqui, <christophe.varo‐
524 qui@free.fr> and others.
525 30 November 2006 MULTIPATH.CONF(5)