]>
Commit | Line | Data |
---|---|---|
519561f7 NB |
1 | .\" Copyright Neil Brown and others. |
2 | .\" This program is free software; you can redistribute it and/or modify | |
3 | .\" it under the terms of the GNU General Public License as published by | |
4 | .\" the Free Software Foundation; either version 2 of the License, or | |
5 | .\" (at your option) any later version. | |
6 | .\" See file COPYING in distribution for details. | |
56eb10c0 NB |
7 | .TH MDADM.CONF 5 |
8 | .SH NAME | |
93e790af | 9 | mdadm.conf \- configuration for management of Software RAID with mdadm |
56eb10c0 NB |
10 | .SH SYNOPSIS |
11 | /etc/mdadm.conf | |
12 | .SH DESCRIPTION | |
13 | .PP | |
51ac42e3 | 14 | .I mdadm |
11a3e71d | 15 | is a tool for creating, managing, and monitoring RAID devices using the |
56eb10c0 NB |
16 | .B md |
17 | driver in Linux. | |
18 | .PP | |
19 | Some common tasks, such as assembling all arrays, can be simplified | |
2d465520 | 20 | by describing the devices and arrays in this configuration file. |
56eb10c0 NB |
21 | |
22 | .SS SYNTAX | |
23 | The file should be seen as a collection of words separated by white | |
24 | space (space, tab, or newline). | |
11a3e71d | 25 | Any word that beings with a hash sign (#) starts a comment and that |
2d465520 | 26 | word together with the remainder of the line is ignored. |
56eb10c0 | 27 | |
2d465520 | 28 | Any line that starts with white space (space or tab) is treated as |
56eb10c0 NB |
29 | though it were a continuation of the previous line. |
30 | ||
31 | Empty lines are ignored, but otherwise each (non continuation) line | |
2d465520 | 32 | must start with a keyword as listed below. The keywords are case |
e0d19036 | 33 | insensitive and can be abbreviated to 3 characters. |
56eb10c0 NB |
34 | |
35 | The keywords are: | |
36 | .TP | |
37 | .B DEVICE | |
38 | A | |
39 | .B device | |
40 | line lists the devices (whole devices or partitions) that might contain | |
41 | a component of an MD array. When looking for the components of an | |
42 | array, | |
51ac42e3 | 43 | .I mdadm |
2d465520 | 44 | will scan these devices (or any devices listed on the command line). |
56eb10c0 NB |
45 | |
46 | The | |
47 | .B device | |
48 | line may contain a number of different devices (separated by spaces) | |
49 | and each device name can contain wild cards as defined by | |
50 | .BR glob (7). | |
51 | ||
52 | Also, there may be several device lines present in the file. | |
53 | ||
5787fa49 NB |
54 | Alternatively, a |
55 | .B device | |
8fd8d9c4 N |
56 | line can contain either of both of the words |
57 | .B containers | |
58 | and | |
5787fa49 | 59 | .BR partitions . |
8fd8d9c4 N |
60 | The word |
61 | .B containers | |
62 | will cause | |
63 | .I mdadm | |
64 | to look for assembled CONTAINER arrays and included them as a source | |
65 | for assembling further arrays. | |
66 | .PP | |
67 | The word | |
68 | .I partitions | |
69 | will cause | |
5787fa49 NB |
70 | .I mdadm |
71 | to read | |
72 | .I /proc/partitions | |
35cc5be4 | 73 | and include all devices and partitions found therein. |
5787fa49 NB |
74 | .I mdadm |
75 | does not use the names from | |
76 | .I /proc/partitions | |
77 | but only the major and minor device numbers. It scans | |
78 | .I /dev | |
79 | to find the name that matches the numbers. | |
80 | ||
8fd8d9c4 | 81 | If no DEVICE line is present, then "DEVICE partitions containers" is assumed. |
a99d6b66 | 82 | |
11a3e71d NB |
83 | For example: |
84 | .IP | |
85 | DEVICE /dev/hda* /dev/hdc* | |
86 | .br | |
87 | DEV /dev/sd* | |
88 | .br | |
89 | DEVICE /dev/discs/disc*/disc | |
5787fa49 NB |
90 | .br |
91 | DEVICE partitions | |
11a3e71d | 92 | |
56eb10c0 NB |
93 | .TP |
94 | .B ARRAY | |
11a3e71d | 95 | The ARRAY lines identify actual arrays. The second word on the line |
8fd8d9c4 | 96 | may be the name of the device where the array is normally |
11a3e71d | 97 | assembled, such as |
db2d001c N |
98 | .B /dev/md1 |
99 | or | |
100 | .BR /dev/md/backup . | |
101 | If the name does not start with a slash | |
102 | .RB (' / '), | |
103 | it is treated as being in | |
104 | .BR /dev/md/ . | |
112cace6 N |
105 | Alternately the word |
106 | .B <ignore> | |
107 | (complete with angle brackets) can be given in which case any array | |
108 | which matches the rest of the line will never be automatically assembled. | |
8fd8d9c4 N |
109 | If no device name is given, |
110 | .I mdadm | |
db2d001c | 111 | will use various heuristics to determine an appropriate name. |
8fd8d9c4 | 112 | .PP |
e0d19036 NB |
113 | Subsequent words identify the array, or identify the array as a member |
114 | of a group. If multiple identities are given, | |
2d465520 NB |
115 | then a component device must match ALL identities to be considered a |
116 | match. Each identity word has a tag, and equals sign, and some value. | |
117 | The tags are: | |
11a3e71d NB |
118 | |
119 | .RS 4 | |
120 | .TP | |
121 | .B uuid= | |
122 | The value should be a 128 bit uuid in hexadecimal, with punctuation | |
123 | interspersed if desired. This must match the uuid stored in the | |
124 | superblock. | |
125 | .TP | |
947fd4dd NB |
126 | .B name= |
127 | The value should be a simple textual name as was given to | |
128 | .I mdadm | |
129 | when the array was created. This must match the name stored in the | |
130 | superblock on a device for that device to be included in the array. | |
35cc5be4 | 131 | Not all superblock formats support names. |
947fd4dd | 132 | .TP |
7e23fc43 | 133 | .B super\-minor= |
11a3e71d NB |
134 | The value is an integer which indicates the minor number that was |
135 | stored in the superblock when the array was created. When an array is | |
136 | created as /dev/mdX, then the minor number X is stored. | |
137 | .TP | |
138 | .B devices= | |
56eedc1a NB |
139 | The value is a comma separated list of device names or device name |
140 | patterns. | |
141 | Only devices with names which match one entry in the list will be used | |
142 | to assemble the array. Note that the devices | |
11a3e71d NB |
143 | listed there must also be listed on a DEVICE line. |
144 | .TP | |
145 | .B level= | |
146 | The value is a raid level. This is not normally used to | |
147 | identify an array, but is supported so that the output of | |
148 | ||
7e23fc43 | 149 | .B "mdadm \-\-examine \-\-scan" |
11a3e71d NB |
150 | |
151 | can be use directly in the configuration file. | |
152 | .TP | |
7e23fc43 | 153 | .B num\-devices= |
b83d95f3 | 154 | The value is the number of devices in a complete active array. As with |
11a3e71d NB |
155 | .B level= |
156 | this is mainly for compatibility with the output of | |
56eb10c0 | 157 | |
7e23fc43 | 158 | .BR "mdadm \-\-examine \-\-scan" . |
e0d19036 | 159 | |
058574b1 NB |
160 | .TP |
161 | .B spares= | |
162 | The value is a number of spare devices to expect the array to have. | |
7e23fc43 | 163 | .B mdadm \-\-monitor |
058574b1 NB |
164 | will report an array if it is found to have fewer than this number of |
165 | spares when | |
7e23fc43 | 166 | .B \-\-monitor |
058574b1 | 167 | starts or when |
7e23fc43 | 168 | .B \-\-oneshot |
058574b1 NB |
169 | is used. |
170 | ||
e0d19036 | 171 | .TP |
7e23fc43 | 172 | .B spare\-group= |
e0d19036 NB |
173 | The value is a textual name for a group of arrays. All arrays with |
174 | the same | |
7e23fc43 | 175 | .B spare\-group |
e0d19036 NB |
176 | name are considered to be part of the same group. The significance of |
177 | a group of arrays is that | |
51ac42e3 | 178 | .I mdadm |
e0d19036 NB |
179 | will, when monitoring the arrays, move a spare drive from one array in |
180 | a group to another array in that group if the first array had a failed | |
181 | or missing drive but no spare. | |
dd0781e5 NB |
182 | |
183 | .TP | |
184 | .B auto= | |
185 | This option declares to | |
51ac42e3 | 186 | .I mdadm |
dd0781e5 NB |
187 | that it should try to create the device file of the array if it |
188 | doesn't already exist, or exists but with the wrong device number. | |
189 | ||
190 | The value of this option can be "yes" or "md" to indicate that a | |
191 | traditional, non-partitionable md array should be created, or "mdp", | |
192 | "part" or "partition" to indicate that a partitionable md array (only | |
193 | available in linux 2.6 and later) should be used. This later set can | |
194 | also have a number appended to indicate how many partitions to create | |
195 | device files for, e.g. | |
196 | .BR auto=mdp5 . | |
197 | The default is 4. | |
7ef02d01 NB |
198 | |
199 | .TP | |
200 | .B bitmap= | |
201 | The option specifies a file in which a write-intent bitmap should be | |
202 | found. When assembling the array, | |
203 | .I mdadm | |
204 | will provide this file to the | |
205 | .B md | |
206 | driver as the bitmap file. This has the same function as the | |
7e23fc43 | 207 | .B \-\-bitmap\-file |
7ef02d01 | 208 | option to |
7e23fc43 | 209 | .BR \-\-assemble . |
058574b1 NB |
210 | |
211 | .TP | |
212 | .B metadata= | |
213 | Specify the metadata format that the array has. This is mainly | |
214 | recognised for comparability with the output of | |
7e23fc43 | 215 | .BR "mdadm \-Es" . |
058574b1 | 216 | |
8fd8d9c4 N |
217 | .TP |
218 | .B container= | |
219 | Specify that this array is a member array of some container. The | |
220 | value given can be either a path name in /dev, or a UUID of the | |
221 | container array. | |
222 | ||
223 | .IP | |
224 | .B member= | |
225 | Specify that this array is a member array of some container. Each | |
226 | type of container has some way to enumerate member arrays, often a | |
227 | simple sequence number. The value identifies which member of a | |
228 | container the array is. It will usually accompany a 'container=' word. | |
11a3e71d | 229 | .RE |
e0d19036 NB |
230 | |
231 | .TP | |
232 | .B MAILADDR | |
233 | The | |
234 | .B mailaddr | |
235 | line gives an E-mail address that alerts should be | |
236 | sent to when | |
51ac42e3 | 237 | .I mdadm |
e0d19036 | 238 | is running in |
7e23fc43 | 239 | .B \-\-monitor |
e0d19036 | 240 | mode (and was given the |
7e23fc43 | 241 | .B \-\-scan |
e0d19036 NB |
242 | option). There should only be one |
243 | .B MAILADDR | |
244 | line and it should have only one address. | |
245 | ||
246 | ||
4948b8f7 NB |
247 | .TP |
248 | .B MAILFROM | |
249 | The | |
250 | .B mailfrom | |
93e790af | 251 | line (which can only be abbreviated to at least 5 characters) gives an |
4948b8f7 NB |
252 | address to appear in the "From" address for alert mails. This can be |
253 | useful if you want to explicitly set a domain, as the default from | |
254 | address is "root" with no domain. All words on this line are | |
255 | catenated with spaces to form the address. | |
256 | ||
257 | Note that this value cannot be set via the | |
258 | .I mdadm | |
259 | commandline. It is only settable via the config file. | |
260 | ||
e0d19036 NB |
261 | .TP |
262 | .B PROGRAM | |
263 | The | |
264 | .B program | |
265 | line gives the name of a program to be run when | |
7e23fc43 | 266 | .B "mdadm \-\-monitor" |
e0d19036 NB |
267 | detects potentially interesting events on any of the arrays that it |
268 | is monitoring. This program gets run with two or three arguments, they | |
269 | being the Event, the md device, and possibly the related component | |
270 | device. | |
271 | ||
272 | There should only be one | |
273 | .B program | |
274 | line and it should be give only one program. | |
275 | ||
5bbb4842 NB |
276 | |
277 | .TP | |
278 | .B CREATE | |
279 | The | |
280 | .B create | |
058574b1 | 281 | line gives default values to be used when creating arrays and device entries for |
5bbb4842 NB |
282 | arrays. |
283 | These include: | |
284 | ||
285 | .RS 4 | |
286 | .TP | |
287 | .B owner= | |
288 | .TP | |
289 | .B group= | |
290 | These can give user/group ids or names to use instead of system | |
291 | defaults (root/wheel or root/disk). | |
292 | .TP | |
293 | .B mode= | |
294 | An octal file mode such as 0660 can be given to override the default | |
295 | of 0600. | |
296 | .TP | |
297 | .B auto= | |
298 | This corresponds to the | |
7e23fc43 | 299 | .B \-\-auto |
5bbb4842 NB |
300 | flag to mdadm. Give |
301 | .BR yes , | |
302 | .BR md , | |
303 | .BR mdp , | |
304 | .B part | |
b3f1c093 | 305 | \(em possibly followed by a number of partitions \(em to indicate how |
5bbb4842 NB |
306 | missing device entries should be created. |
307 | ||
058574b1 NB |
308 | .TP |
309 | .B metadata= | |
310 | The name of the metadata format to use if none is explicitly given. | |
311 | This can be useful to impose a system-wide default of version-1 superblocks. | |
312 | ||
38098016 NB |
313 | .TP |
314 | .B symlinks=no | |
315 | Normally when creating devices in | |
316 | .B /dev/md/ | |
317 | .I mdadm | |
318 | will create a matching symlink from | |
319 | .B /dev/ | |
320 | with a name starting | |
321 | .B md | |
322 | or | |
323 | .BR md_ . | |
324 | Give | |
16c4849b | 325 | .B symlinks=no |
38098016 | 326 | to suppress this symlink creation. |
5bbb4842 NB |
327 | .RE |
328 | ||
6d6de2ee NB |
329 | .TP |
330 | .B HOMEHOST | |
331 | The | |
332 | .B homehost | |
333 | line gives a default value for the | |
334 | .B --homehost= | |
335 | option to mdadm. There should be exactly one other word on the line. | |
336 | It should either exactly | |
337 | .B <system> | |
338 | or a host name. | |
339 | If | |
340 | .B <system> | |
341 | is given, then the | |
342 | .BR gethostname ( 2 ) | |
343 | systemcall is used to get the host name. | |
344 | When arrays are created, this host name will be stored in the | |
345 | metadata. When arrays are assembled using auto-assembly, only arrays | |
346 | with this host name stored in the metadata will be considered. | |
5bbb4842 | 347 | |
31015d57 N |
348 | .TP |
349 | .B AUTO | |
350 | A list of names of metadata format can be given, each preceded by a | |
351 | plus or minus sign. Also the word | |
352 | .I all | |
353 | preceded by plus or minus is allowed and is usually last. | |
354 | ||
355 | When | |
356 | .I mdadm | |
357 | is auto-assembling an array, with via | |
358 | .I --assemble | |
359 | or | |
360 | .I --incremental | |
361 | and it finds metadata of a given type, it checks that metadata type | |
362 | against those listed in this line. The first match wins, where | |
363 | .I all | |
364 | matches anything. | |
365 | If a match is found that was preceded by a plus sign, the auto | |
366 | assembly is allowed. If the match was preceded by a minus sign, the | |
367 | auto assembly is disallowed. If no match is found, the auto assembly | |
368 | is allowed. | |
369 | ||
370 | This can be used to disable all auto-assembly (so that only arrays | |
371 | explicitly listed in mdadm.conf or on the command line are assembled), | |
372 | or to disable assembly of certain metadata types which might be | |
373 | handled by other software. | |
374 | ||
375 | The known metadata types are | |
376 | .BR 0.90 , | |
377 | .BR 1.x , | |
378 | .BR ddf , | |
379 | .BR imsm . | |
380 | ||
2d465520 NB |
381 | .SH EXAMPLE |
382 | DEVICE /dev/sd[bcdjkl]1 | |
383 | .br | |
384 | DEVICE /dev/hda1 /dev/hdb1 | |
385 | ||
0e69da72 | 386 | # /dev/md0 is known by its UUID. |
2d465520 NB |
387 | .br |
388 | ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371 | |
389 | .br | |
390 | # /dev/md1 contains all devices with a minor number of | |
391 | .br | |
392 | # 1 in the superblock. | |
393 | .br | |
394 | ARRAY /dev/md1 superminor=1 | |
395 | .br | |
93e790af | 396 | # /dev/md2 is made from precisely these two devices |
2d465520 | 397 | .br |
a9d69660 | 398 | ARRAY /dev/md2 devices=/dev/hda1,/dev/hdb1 |
2d465520 NB |
399 | |
400 | # /dev/md4 and /dev/md5 are a spare-group and spares | |
401 | .br | |
402 | # can be moved between them | |
403 | .br | |
404 | ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df | |
405 | .br | |
7e23fc43 | 406 | spare\-group=group1 |
2d465520 NB |
407 | .br |
408 | ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977 | |
409 | .br | |
7e23fc43 | 410 | spare\-group=group1 |
dd0781e5 NB |
411 | .br |
412 | # /dev/md/home is created if need to be a partitionable md array | |
413 | .br | |
414 | # any spare device number is allocated. | |
415 | .br | |
416 | ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b | |
417 | .br | |
418 | auto=part | |
2d465520 NB |
419 | |
420 | MAILADDR root@mydomain.tld | |
421 | .br | |
7e23fc43 | 422 | PROGRAM /usr/sbin/handle\-mdadm\-events |
5bbb4842 | 423 | .br |
7e23fc43 | 424 | CREATE group=system mode=0640 auto=part\-8 |
41a3b72a NB |
425 | .br |
426 | HOMEHOST <system> | |
31015d57 N |
427 | .br |
428 | AUTO +1.x -all | |
e0d19036 | 429 | |
56eb10c0 | 430 | .SH SEE ALSO |
11a3e71d NB |
431 | .BR mdadm (8), |
432 | .BR md (4). | |
56eb10c0 | 433 |