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