a0bde42fb6896e4c70e86ec44b4f15b5d5a3eb90
[multipath-tools/.git] / multipath / multipath.conf.5
1 .TH MULTIPATH.CONF 5 "30 November 2006"
2 .SH NAME
3 multipath.conf \- multipath daemon configuration file
4 .SH DESCRIPTION
5 .B "multipath.conf"
6 is the configuration file for the multipath daemon. It is used to
7 overwrite the built-in configuration table of \fBmultipathd\fP.
8 Any line whose first non-white-space character is a '#' is considered
9 a comment line. Empty lines are ignored.
10 .SH SYNTAX
11 The configuration file contains entries of the form:
12 .RS
13 .nf
14 .ft B
15 .sp
16 <section> {
17 .RS
18 .ft B
19 <attribute> <value>
20 .I "..."
21 .ft B
22 <subsection> {
23 .RS
24 .ft B
25 <attribute> <value>
26 .I "..."
27 .RE
28 }
29 .RE
30 }
31 .ft R
32 .fi
33 .RE
34 .LP
35 Each \fIsection\fP contains one or more attributes or subsections. The
36 recognized keywords for attributes or subsections depend on the
37 section in which they occor.
38 .LP
39 The following \fIsection\fP keywords are recognized:
40 .TP 17
41 .B defaults
42 This section defines default values for attributes which are used
43 whenever no values are given in the appropriate device or multipath
44 sections.
45 .TP
46 .B blacklist
47 This section defines which devices should be excluded from the
48 multipath topology discovery.
49 .TP
50 .B blacklist_exceptions
51 This section defines which devices should be included in the
52 multipath topology discovery, despite being listed in the
53 .I blacklist
54 section.
55 .TP
56 .B multipaths
57 This section defines the multipath topologies. They are indexed by a
58 \fIWorld Wide Identifier\fR(wwid), which is the result of the
59 \fIgetuid_callout\fR program.
60 .TP
61 .B devices
62 This section defines the device-specific settings.
63 .RE
64 .LP
65 .SH "defaults section"
66 The
67 .B defaults
68 section recognizes the following keywords:
69 .TP 17
70 .B polling_interval
71 interval between two path checks in seconds. For properly functioning paths,
72 the interval between checks will gradually increase to
73 .B max_polling_interval;
74 default is
75 .I 5
76 .TP
77 .B max_polling_interval
78 maximal interval between two path checks in seconds; default is
79 .I 4 * polling_interval
80 .TP
81 .B udev_dir
82 directory where udev creates its device nodes; default is
83 .I /dev
84 .TP
85 .B verbosity
86 default verbosity. Higher values increase the verbosity level. Valid
87 levels are between 0 and 6; default is
88 .I 2
89 .TP
90 .B reassign_maps
91 enable reassigning of device-mapper maps. With this option multipathd
92 will remap existing device-mapper maps to always point to multipath
93 device, not the underlying block devices. Possible values are
94 \fIyes\fR and \fIno\fR. Default is
95 .I yes
96 .TP
97 .B path_selector
98 The default path selector algorithm to use; they are offered by the
99 kernel multipath target. There are three selector algorithms.
100 .RS
101 .TP 12
102 .B "round-robin 0"
103 Loop through every path in the path group, sending the same amount of IO to
104 each.
105 .TP
106 .B "queue-length 0"
107 Send the next bunch of IO down the path with the least amount of outstanding IO.
108 .TP
109 .B "service-time 0"
110 Choose the path for the next bunch of IO based on the amount of outstanding IO
111 to the path and its relative throughput.
112 .RE
113 .TP
114 .B path_grouping_policy
115 The default path grouping policy to apply to unspecified
116 multipaths. Possible values are
117 .RS
118 .TP 12
119 .B failover
120 1 path per priority group
121 .TP
122 .B multibus
123 all paths in 1 priority group
124 .TP
125 .B group_by_serial
126 1 priority group per serial number
127 .TP
128 .B group_by_prio
129 1 priority group per priority value. Priorities are determined by
130 callout programs specified as a global, per-controller or
131 per-multipath option in the configuration file.
132 .TP
133 .B group_by_node_name
134 1 priority group per target node name. Target node names are fetched
135 in /sys/class/fc_transport/target*/node_name.
136 .TP
137 Default value is \fImultibus\fR.
138 .RE
139 .TP
140 .B getuid_callout
141 The default program and args to callout to obtain a unique path
142 identifier. Should be specified with an absolute path. Default value
143 is
144 .I /lib/udev/scsi_id --whitelisted --device=/dev/%n
145 .TP
146 .B prio_callout
147 The default program and args to callout to obtain a path priority
148 value. The specified program will be executed and should return a
149 numeric value specifying the relative priority of this path. Higher
150 number have a higher priority. A '%n' in the command line will be expanded
151 to the device name, a '%b' will be expanded to the device number in
152 .I major:minor
153 format.
154 .I "none"
155 is a valid value. Currently the following path priority programs are
156 implemented:
157 .RS
158 .TP 12
159 .B mpath_prio_emc /dev/%n
160 Generate the path priority for EMC arrays
161 .TP
162 .B mpath_prio_alua /dev/%n
163 Generate the path priority based on the SCSI-3 ALUA settings.
164 .TP
165 .B mpath_prio_ontap /dev/%n
166 Generate the path priority for NetApp arrays.
167 .TP
168 .B mpath_prio_rdac /dev/%n
169 Generate the path priority for LSI/Engenio RDAC controller.
170 .TP
171 .B mpath_prio_hp_sw /dev/%n
172 Generate the path priority for Compaq/HP controller in
173 active/standby mode.
174 .TP
175 .B mpath_prio_hds_modular %b
176 Generate the path priority for Hitachi HDS Modular storage arrays.
177 .TP
178 Default value is \fBnone\fR.
179 .RE
180 .TP
181 .B features
182 Specify any device-mapper features to be used. Syntax is
183 .I num list
184 where
185 .I num
186 is the number of features in
187 .I list.
188 Possible values for the feature list are
189 .RS
190 .TP 12
191 .B queue_if_no_path
192 Queue IO if no path is active; identical to the
193 .I no_path_retry
194 keyword.
195 .TP
196 .B no_partitions
197 Disable automatic partitions generation via kpartx.
198 .RE
199 .TP
200 .B path_checker
201 The default method used to determine the paths' state. Possible values
202 are
203 .RS
204 .TP 12
205 .B readsector0
206 Read the first sector of the device
207 .TP
208 .B tur
209 Issue a
210 .I TEST UNIT READY
211 command to the device.
212 .TP
213 .B emc_clariion
214 Query the EMC Clariion specific EVPD page 0xC0 to determine the path
215 state.
216 .TP
217 .B hp_sw
218 Check the path state for HP storage arrays with Active/Standby firmware.
219 .TP
220 .B rdac
221 Check the path state for LSI/Engenio RDAC storage controller.
222 .TP
223 .B directio
224 Read the first sector with direct I/O.
225 .TP
226 Default value is \fIreadsector0\fR.
227 .RE
228 .TP
229 .B failback
230 Tell the daemon to manage path group failback, or not to. 0 or
231 .I immediate
232 means immediate failback, values >0 means deferred failback (in
233 seconds).
234 .I manual
235 means no failback. Default value is
236 .I manual
237 .TP
238 .B  rr_min_io
239 The number of IO to route to a path before switching to the next in
240 the same path group. Default is
241 .I 1000
242 .TP
243 .B rr_weight
244 If set to \fIpriorities\fR the multipath configurator will assign
245 path weights as "path prio * rr_min_io". Possible values are
246 .I priorities
247 or
248 .IR uniform .
249 Default is
250 .IR uniform .
251 .TP
252 .B no_path_retry
253 Specify the number of retries until disable queueing, or
254 .I fail
255 for immediate failure (no queueing),
256 .I queue
257 for never stop queueing. Default is 0.
258 .TP
259 .B user_friendly_names
260 If set to 
261 .I yes
262 , using the bindings file
263 .I /etc/multipath/bindings
264 to assign a persistent and unique alias to the multipath, in the form of mpath<n>.
265 If set to 
266 .I no
267 use the WWID as the alias. In either case this be will
268 be overriden by any specific aliases in the \fImultipaths\fR section.
269 Default is
270 .I no
271 .TP
272 .B max_fds
273 Specify the maximum number of file descriptors that can be opened by multipath
274 and multipathd.  This is equivalent to ulimit -n. A value of \fImax\fR will set
275 this to the system limit from /proc/sys/fs/nr_open. If this is not set, the
276 maximum number of open fds is taken from the calling process. It is usually
277 1024. To be safe, this should be set to the maximum number of paths plus 32,
278 if that number is greated than 1024.
279 .TP
280 .B checker_timeout
281 Specify the timeout to user for path checkers that issue scsi commands with an
282 explict timeout, in seconds; default taken from
283 .I /sys/block/sd<x>/device/timeout
284 .TP
285 .B fast_io_fail_tmo
286 Specify the number of seconds the scsi layer will wait after a problem has been
287 detected on a FC remote port before failing IO to devices on that remote port.
288 This should be smaller than dev_loss_tmo. Setting this to
289 .I off
290 will disable the timeout.
291 .TP
292 .B dev_loss_tmo
293 Specify the number of seconds the scsi layer will wait after a problem has
294 been detected on a FC remote port before removing it from the system.
295 .TP
296 .B queue_without_daemon
297 If set to
298 .I no
299 , when multipathd stops, queueing will be turned off for all devices.
300 This is useful for devices that set no_path_retry.  If a machine is
301 shut down while all paths to a device are down, it is possible to hang waiting
302 for IO to return from the device after multipathd has been stopped. Without
303 multipathd running, access to the paths cannot be restored, and the kernel
304 cannot be told to stop queueing IO. Setting queue_without_daemon to
305 .I no
306 , avoids this problem. Default is
307 .I yes
308 .TP
309 .B bindings_file
310 The full pathname of the binding file to be used when the user_friendly_names option is set. Defaults to
311 .I /var/lib/multipath/bindings
312 .
313 .SH "blacklist section"
314 The
315 .I blacklist
316 section is used to exclude specific device from inclusion in the
317 multipath topology. It is most commonly used to exclude local disks or
318 LUNs for the array controller.
319 .LP
320 The following keywords are recognized:
321 .TP 17
322 .B wwid
323 The \fIWorld Wide Identification\fR of a device.
324 .TP
325 .B devnode
326 Regular expression of the device nodes to be excluded.
327 .TP
328 .B device
329 Subsection for the device description. This subsection recognizes the
330 .I vendor
331 and
332 .I product
333 keywords. For a full description of these keywords please see the
334 .I devices
335 section description.
336 .SH "blacklist_exceptions section"
337 The
338 .I blacklist_exceptions
339 section is used to revert the actions of the
340 .I blacklist
341 section, ie to include specific device in the
342 multipath topology. This allows to selectively include devices which
343 would normally be excluded via the
344 .I blacklist
345 section.
346 .LP
347 The following keywords are recognized:
348 .TP 17
349 .B wwid
350 The \fIWorld Wide Identification\fR of a device.
351 .TP
352 .B devnode
353 Regular expression of the device nodes to be excluded.
354 .TP
355 .B device
356 Subsection for the device description. This subsection recognizes the
357 .I vendor
358 and
359 .I product
360 keywords. For a full description of these keywords please see the
361 .I devices
362 section description.
363 .SH "multipaths section"
364 The only recognized attribute for the
365 .B multipaths
366 section is the
367 .I multipath
368 subsection.
369 .LP
370 The
371 .B multipath
372 subsection recognizes the following attributes:
373 .TP 17
374 .B wwid
375 Index of the container. Mandatory for this subsection.
376 .TP
377 .B alias
378 (Optional) symbolic name for the multipath map.
379 .LP
380 The following attributes are optional; if not set the default values
381 are taken from the
382 .I defaults
383 or
384 .I devices
385 section:
386 .sp 1
387 .PD .1v
388 .RS
389 .TP 18
390 .B path_grouping_policy
391 .TP
392 .B path_selector
393 .TP
394 .B failback
395 .TP
396 .B no_path_retry
397 .TP
398 .B rr_min_io
399 .TP
400 .B features
401 .RE
402 .PD
403 .LP
404 .SH "devices section"
405 The only recognized attribute for the
406 .B devices
407 section is the
408 .I device
409 subsection.
410 .LP
411 The
412 .I device
413 subsection recognizes the following attributes:
414 .TP 17
415 .B vendor
416 (Mandatory) Vendor identifier
417 .TP
418 .B product
419 (Mandatory) Product identifier
420 .TP
421 .B revision
422 (Optional) Revision identfier
423 .TP
424 .B product_blacklist
425 (Optional) Product strings to blacklist for this vendor
426 .TP
427 .B hardware_handler
428 (Optional) The hardware handler to use for this device type.
429 The following hardware handler are implemented:
430 .RS
431 .TP 12
432 .B 1 emc
433 Hardware handler for EMC storage arrays.
434 .RE
435 .LP
436 The following attributes are optional; if not set the default values
437 are taken from the
438 .I defaults
439 section:
440 .sp 1
441 .PD .1v
442 .RS
443 .TP 18
444 .B path_grouping_policy
445 .TP
446 .B getuid_callout
447 .TP
448 .B path_selector
449 .TP
450 .B path_checker
451 .TP
452 .B features
453 .TP
454 .B prio_callout
455 .TP
456 .B failback
457 .TP
458 .B rr_weight
459 .TP
460 .B no_path_retry
461 .TP
462 .B rr_min_io
463 .TP
464 .B fast_io_fail_tmo
465 .TP
466 .B dev_loss_tmo
467 .RE
468 .PD
469 .LP
470 .SH "KNOWN ISSUES"
471 The usage of
472 .B queue_if_no_path
473 option can lead to
474 .B D state
475 processes being hung and not killable in situations where all the paths to the LUN go offline.
476 It is advisable to use the
477 .B no_path_retry
478 option instead.
479 .SH "SEE ALSO"
480 .BR udev (8),
481 .BR dmsetup (8)
482 .BR multipath (8)
483 .BR multipathd (8)
484 .SH AUTHORS
485 .B multipath
486 was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com> and others.