multipath-tools: update scsi_id arguments
[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; default is
71 .I 5
72 .TP
73 .B udev_dir
74 directory where udev creates its device nodes; default is
75 .I /dev
76 .TP
77 .B selector
78 The default path selector algorithm to use; they are offered by the
79 kernel multipath target. The only currently implemented is
80 .I "round-robin 0"
81 .TP
82 .B path_grouping_policy
83 The default path grouping policy to apply to unspecified
84 multipaths. Possible values are
85 .RS
86 .TP 12
87 .B failover
88 1 path per priority group
89 .TP
90 .B multibus
91 all paths in 1 priority group
92 .TP
93 .B group_by_serial
94 1 priority group per serial number
95 .TP
96 .B group_by_prio
97 1 priority group per priority value. Priorities are determined by
98 callout programs specified as a global, per-controller or
99 per-multipath option in the configuration file.
100 .TP
101 .B group_by_node_name
102 1 priority group per target node name. Target node names are fetched
103 in /sys/class/fc_transport/target*/node_name.
104 .TP
105 Default value is \fImultibus\fR.
106 .RE
107 .TP
108 .B getuid_callout
109 The default program and args to callout to obtain a unique path
110 identifier. Should be specified with an absolute path. Default value
111 is
112 .I /lib/udev/scsi_id --whitelisted --device=/dev/%n
113 .TP
114 .B prio_callout
115 The default program and args to callout to obtain a path priority
116 value. The specified program will be executed and should return a
117 numeric value specifying the relative priority of this path. Higher
118 number have a higher priority. A '%n' in the command line will be expanded
119 to the device name, a '%b' will be expanded to the device number in
120 .I major:minor
121 format.
122 .I "none"
123 is a valid value. Currently the following path priority programs are
124 implemented:
125 .RS
126 .TP 12
127 .B mpath_prio_emc /dev/%n
128 Generate the path priority for EMC arrays
129 .TP
130 .B mpath_prio_alua /dev/%n
131 Generate the path priority based on the SCSI-3 ALUA settings.
132 .TP
133 .B mpath_prio_netapp /dev/%n
134 Generate the path priority for NetApp arrays.
135 .TP
136 .B mpath_prio_rdac /dev/%n
137 Generate the path priority for LSI/Engenio RDAC controller.
138 .TP
139 .B mpath_prio_hp_sw /dev/%n
140 Generate the path priority for Compaq/HP controller in
141 active/standby mode.
142 .TP
143 .B mpath_prio_hds_modular %b
144 Generate the path priority for Hitachi HDS Modular storage arrays.
145 .TP
146 Default value is \fBnone\fR.
147 .RE
148 .TP
149 .B features
150 Specify any device-mapper features to be used. The most common of
151 these features is
152 .I "1 queue_if_no_path" 
153 Note that this can also be set via the
154 .I no_path_retry
155 keyword.
156 .TP
157 .B path_checker
158 The default method used to determine the paths' state. Possible values
159 are
160 .RS
161 .TP 12
162 .B readsector0
163 Read the first sector of the device
164 .TP
165 .B tur
166 Issue a
167 .I TEST UNIT READY
168 command to the device.
169 .TP
170 .B emc_clariion
171 Query the EMC Clariion specific EVPD page 0xC0 to determine the path
172 state.
173 .TP
174 .B hp_sw
175 Check the path state for HP storage arrays with Active/Standby firmware.
176 .TP
177 .B rdac
178 Check the path state for LSI/Engenio RDAC storage controller.
179 .TP
180 .B directio
181 Read the first sector with direct I/O.
182 .TP
183 Default value is \fIreadsector0\fR.
184 .RE
185 .TP
186 .B failback
187 Tell the daemon to manage path group failback, or not to. 0 or
188 .I immediate
189 means immediate failback, values >0 means deferred failback (in
190 seconds).
191 .I manual
192 means no failback. Default value is
193 .I manual
194 .TP
195 .B  rr_min_io
196 The number of IO to route to a path before switching to the next in
197 the same path group. Default is
198 .I 1000
199 .TP
200 .B rr_weight
201 If set to \fIpriorities\fR the multipath configurator will assign
202 path weights as "path prio * rr_min_io". Possible values are
203 .I priorities
204 or
205 .I uniform
206 . Default is
207 .I uniform
208 .TP
209 .B no_path_retry
210 Specify the number of retries until disable queueing, or
211 .I fail
212 for immediate failure (no queueing),
213 .I queue
214 for never stop queueing. Default is 0.
215 .TP
216 .B user_friendly_names
217 If set to 
218 .I yes
219 , using the bindings file
220 .I /var/lib/multipath/bindings
221 to assign a persistent and unique alias to the multipath, in the form of mpath<n>.
222 If set to 
223 .I no
224 use the WWID as the alias. In either case this be will
225 be overriden by any specific aliases in the \fImultipaths\fR section.
226 Default is
227 .I no
228 .
229 .SH "blacklist section"
230 The
231 .I blacklist
232 section is used to exclude specific device from inclusion in the
233 multipath topology. It is most commonly used to exclude local disks or
234 LUNs for the array controller.
235 .LP
236 The following keywords are recognized:
237 .TP 17
238 .B wwid
239 The \fIWorld Wide Identification\fR of a device.
240 .TP
241 .B devnode
242 Regular expression of the device nodes to be excluded.
243 .TP
244 .B device
245 Subsection for the device description. This subsection recognizes the
246 .I vendor
247 and
248 .I product
249 keywords. For a full description of these keywords please see the
250 .I devices
251 section description.
252 .SH "blacklist_exceptions section"
253 The
254 .I blacklist_exceptions
255 section is used to revert the actions of the
256 .I blacklist
257 section, ie to include specific device in the
258 multipath topology. This allows to selectively include devices which
259 would normally be excluded via the
260 .I blacklist
261 section.
262 .LP
263 The following keywords are recognized:
264 .TP 17
265 .B wwid
266 The \fIWorld Wide Identification\fR of a device.
267 .TP
268 .B devnode
269 Regular expression of the device nodes to be excluded.
270 .TP
271 .B device
272 Subsection for the device description. This subsection recognizes the
273 .I vendor
274 and
275 .I product
276 keywords. For a full description of these keywords please see the
277 .I devices
278 section description.
279 .SH "multipaths section"
280 The only recognized attribute for the
281 .B multipaths
282 section is the
283 .I multipath
284 subsection.
285 .LP
286 The
287 .B multipath
288 subsection recognizes the following attributes:
289 .TP 17
290 .B wwid
291 Index of the container. Mandatory for this subsection.
292 .TP
293 .B alias
294 (Optional) symbolic name for the multipath map.
295 .LP
296 The following attributes are optional; if not set the default values
297 are taken from the
298 .I defaults
299 section:
300 .sp 1
301 .PD .1v
302 .RS
303 .TP 18
304 .B path_grouping_policy
305 .TP
306 .B path_selector
307 .TP
308 .B failback
309 .TP
310 .B no_path_retry
311 .TP
312 .B rr_min_io
313 .RE
314 .PD
315 .LP
316 .SH "devices section"
317 The only recognized attribute for the
318 .B devices
319 section is the
320 .I device
321 subsection.
322 .LP
323 The
324 .I device
325 subsection recognizes the following attributes:
326 .TP 17
327 .B vendor
328 (Mandatory) Vendor identifier
329 .TP
330 .B product
331 (Mandatory) Product identifier
332 .TP
333 .B product_blacklist
334 Product strings to blacklist for this vendor
335 .TP
336 .B hardware_handler
337 (Optional) The hardware handler to use for this device type.
338 The following hardware handler are implemented:
339 .RS
340 .TP 12
341 .B 1 emc
342 Hardware handler for EMC storage arrays.
343 .RE
344 .LP
345 The following attributes are optional; if not set the default values
346 are taken from the
347 .I defaults
348 section:
349 .sp 1
350 .PD .1v
351 .RS
352 .TP 18
353 .B path_grouping_policy
354 .TP
355 .B getuid_callout
356 .TP
357 .B path_selector
358 .TP
359 .B path_checker
360 .TP
361 .B features
362 .TP
363 .B prio_callout
364 .TP
365 .B failback
366 .TP
367 .B rr_weight
368 .TP
369 .B no_path_retry
370 .TP
371 .B rr_min_io
372 .RE
373 .PD
374 .LP
375 .SH "KNOWN ISSUES"
376 The usage of
377 .B queue_if_no_path
378 option can lead to
379 .B D state
380 processes being hung and not killable in situations where all the paths to the LUN go offline.
381 It is advisable to use the
382 .B no_path_retry
383 option instead.
384 .SH "SEE ALSO"
385 .BR udev (8),
386 .BR dmsetup (8)
387 .BR multipath (8)
388 .BR multipathd (8)
389 .SH AUTHORS
390 .B multipath
391 was developed by Christophe Varoqui, <christophe.varoqui@free.fr> and others.