]>
Commit | Line | Data |
---|---|---|
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. | |
7 | .TH MDADM.CONF 5 | |
8 | .SH NAME | |
9 | mdadm.conf \- configuration for management of Software RAID with mdadm | |
10 | .SH SYNOPSIS | |
11 | /etc/mdadm.conf | |
12 | .SH DESCRIPTION | |
13 | .PP | |
14 | .I mdadm | |
15 | is a tool for creating, managing, and monitoring RAID devices using the | |
16 | .B md | |
17 | driver in Linux. | |
18 | .PP | |
19 | Some common tasks, such as assembling all arrays, can be simplified | |
20 | by describing the devices and arrays in this configuration file. | |
21 | ||
22 | .SS SYNTAX | |
23 | The file should be seen as a collection of words separated by white | |
24 | space (space, tab, or newline). | |
25 | Any word that beings with a hash sign (#) starts a comment and that | |
26 | word together with the remainder of the line is ignored. | |
27 | ||
28 | Spaces can be included in a word using quotation characters. Either | |
29 | single quotes | |
30 | .RB ( ' ) | |
31 | or double quotes (\fB"\fP) | |
32 | may be used. All the characters from one quotation character to | |
33 | next identical character are protected and will not be used to | |
34 | separate words to start new quoted strings. To include a single quote | |
35 | it must be between double quotes. To include a double quote it must | |
36 | be between single quotes. | |
37 | ||
38 | Any line that starts with white space (space or tab) is treated as | |
39 | though it were a continuation of the previous line. | |
40 | ||
41 | Empty lines are ignored, but otherwise each (non continuation) line | |
42 | must start with a keyword as listed below. The keywords are case | |
43 | insensitive and can be abbreviated to 3 characters. | |
44 | ||
45 | The keywords are: | |
46 | .TP | |
47 | .B DEVICE | |
48 | A | |
49 | .B device | |
50 | line lists the devices (whole devices or partitions) that might contain | |
51 | a component of an MD array. When looking for the components of an | |
52 | array, | |
53 | .I mdadm | |
54 | will scan these devices (or any devices listed on the command line). | |
55 | ||
56 | The | |
57 | .B device | |
58 | line may contain a number of different devices (separated by spaces) | |
59 | and each device name can contain wild cards as defined by | |
60 | .BR glob (7). | |
61 | ||
62 | Also, there may be several device lines present in the file. | |
63 | ||
64 | Alternatively, a | |
65 | .B device | |
66 | line can contain either or both of the words | |
67 | .B containers | |
68 | and | |
69 | .BR partitions . | |
70 | The word | |
71 | .B containers | |
72 | will cause | |
73 | .I mdadm | |
74 | to look for assembled CONTAINER arrays and included them as a source | |
75 | for assembling further arrays. | |
76 | ||
77 | The word | |
78 | .I partitions | |
79 | will cause | |
80 | .I mdadm | |
81 | to read | |
82 | .I /proc/partitions | |
83 | and include all devices and partitions found therein. | |
84 | .I mdadm | |
85 | does not use the names from | |
86 | .I /proc/partitions | |
87 | but only the major and minor device numbers. It scans | |
88 | .I /dev | |
89 | to find the name that matches the numbers. | |
90 | ||
91 | If no DEVICE line is present, then "DEVICE partitions containers" is assumed. | |
92 | ||
93 | For example: | |
94 | .IP | |
95 | DEVICE /dev/hda* /dev/hdc* | |
96 | .br | |
97 | DEV /dev/sd* | |
98 | .br | |
99 | DEVICE /dev/disk/by-path/pci* | |
100 | .br | |
101 | DEVICE partitions | |
102 | ||
103 | .TP | |
104 | .B ARRAY | |
105 | The ARRAY lines identify actual arrays. The second word on the line | |
106 | may be the name of the device where the array is normally | |
107 | assembled, such as | |
108 | .B /dev/md1 | |
109 | or | |
110 | .BR /dev/md/backup . | |
111 | If the name does not start with a slash | |
112 | .RB (' / '), | |
113 | it is treated as being in | |
114 | .BR /dev/md/ . | |
115 | Alternately the word | |
116 | .B <ignore> | |
117 | (complete with angle brackets) can be given in which case any array | |
118 | which matches the rest of the line will never be automatically assembled. | |
119 | If no device name is given, | |
120 | .I mdadm | |
121 | will use various heuristics to determine an appropriate name. | |
122 | ||
123 | Subsequent words identify the array, or identify the array as a member | |
124 | of a group. If multiple identities are given, | |
125 | then a component device must match ALL identities to be considered a | |
126 | match. Each identity word has a tag, and equals sign, and some value. | |
127 | The tags are: | |
128 | .RS 4 | |
129 | .TP | |
130 | .B uuid= | |
131 | The value should be a 128 bit uuid in hexadecimal, with punctuation | |
132 | interspersed if desired. This must match the uuid stored in the | |
133 | superblock. | |
134 | .TP | |
135 | .B name= | |
136 | The value should be a simple textual name as was given to | |
137 | .I mdadm | |
138 | when the array was created. This must match the name stored in the | |
139 | superblock on a device for that device to be included in the array. | |
140 | Not all superblock formats support names. | |
141 | .TP | |
142 | .B super\-minor= | |
143 | The value is an integer which indicates the minor number that was | |
144 | stored in the superblock when the array was created. When an array is | |
145 | created as /dev/mdX, then the minor number X is stored. | |
146 | .TP | |
147 | .B devices= | |
148 | The value is a comma separated list of device names or device name | |
149 | patterns. | |
150 | Only devices with names which match one entry in the list will be used | |
151 | to assemble the array. Note that the devices | |
152 | listed there must also be listed on a DEVICE line. | |
153 | .TP | |
154 | .B level= | |
155 | The value is a RAID level. This is not normally used to | |
156 | identify an array, but is supported so that the output of | |
157 | ||
158 | .B "mdadm \-\-examine \-\-scan" | |
159 | ||
160 | can be use directly in the configuration file. | |
161 | .TP | |
162 | .B num\-devices= | |
163 | The value is the number of devices in a complete active array. As with | |
164 | .B level= | |
165 | this is mainly for compatibility with the output of | |
166 | ||
167 | .BR "mdadm \-\-examine \-\-scan" . | |
168 | ||
169 | .TP | |
170 | .B spares= | |
171 | The value is a number of spare devices to expect the array to have. | |
172 | The sole use of this keyword and value is as follows: | |
173 | .B mdadm \-\-monitor | |
174 | will report an array if it is found to have fewer than this number of | |
175 | spares when | |
176 | .B \-\-monitor | |
177 | starts or when | |
178 | .B \-\-oneshot | |
179 | is used. | |
180 | ||
181 | .TP | |
182 | .B spare\-group= | |
183 | The value is a textual name for a group of arrays. All arrays with | |
184 | the same | |
185 | .B spare\-group | |
186 | name are considered to be part of the same group. The significance of | |
187 | a group of arrays is that | |
188 | .I mdadm | |
189 | will, when monitoring the arrays, move a spare drive from one array in | |
190 | a group to another array in that group if the first array had a failed | |
191 | or missing drive but no spare. | |
192 | ||
193 | .TP | |
194 | .B auto= | |
195 | This option is rarely needed with mdadm-3.0, particularly if use with | |
196 | the Linux kernel v2.6.28 or later. | |
197 | It tells | |
198 | .I mdadm | |
199 | whether to use partitionable array or non-partitionable arrays and, | |
200 | in the absence of | |
201 | .IR udev , | |
202 | how many partition devices to create. From 2.6.28 all md array | |
203 | devices are partitionable, hence this option is not needed. | |
204 | ||
205 | The value of this option can be "yes" or "md" to indicate that a | |
206 | traditional, non-partitionable md array should be created, or "mdp", | |
207 | "part" or "partition" to indicate that a partitionable md array (only | |
208 | available in linux 2.6 and later) should be used. This later set can | |
209 | also have a number appended to indicate how many partitions to create | |
210 | device files for, e.g. | |
211 | .BR auto=mdp5 . | |
212 | The default is 4. | |
213 | ||
214 | .TP | |
215 | .B bitmap= | |
216 | The option specifies a file in which a write-intent bitmap should be | |
217 | found. When assembling the array, | |
218 | .I mdadm | |
219 | will provide this file to the | |
220 | .B md | |
221 | driver as the bitmap file. This has the same function as the | |
222 | .B \-\-bitmap\-file | |
223 | option to | |
224 | .BR \-\-assemble . | |
225 | ||
226 | .TP | |
227 | .B metadata= | |
228 | Specify the metadata format that the array has. This is mainly | |
229 | recognised for comparability with the output of | |
230 | .BR "mdadm \-Es" . | |
231 | ||
232 | .TP | |
233 | .B container= | |
234 | Specify that this array is a member array of some container. The | |
235 | value given can be either a path name in /dev, or a UUID of the | |
236 | container array. | |
237 | ||
238 | .TP | |
239 | .B member= | |
240 | Specify that this array is a member array of some container. Each | |
241 | type of container has some way to enumerate member arrays, often a | |
242 | simple sequence number. The value identifies which member of a | |
243 | container the array is. It will usually accompany a "container=" word. | |
244 | .RE | |
245 | ||
246 | .TP | |
247 | .B MAILADDR | |
248 | The | |
249 | .B mailaddr | |
250 | line gives an E-mail address that alerts should be | |
251 | sent to when | |
252 | .I mdadm | |
253 | is running in | |
254 | .B \-\-monitor | |
255 | mode (and was given the | |
256 | .B \-\-scan | |
257 | option). There should only be one | |
258 | .B MAILADDR | |
259 | line and it should have only one address. Any subsequent addresses | |
260 | are silently ignored. | |
261 | ||
262 | .TP | |
263 | .B MAILFROM | |
264 | The | |
265 | .B mailfrom | |
266 | line (which can only be abbreviated to at least 5 characters) gives an | |
267 | address to appear in the "From" address for alert mails. This can be | |
268 | useful if you want to explicitly set a domain, as the default from | |
269 | address is "root" with no domain. All words on this line are | |
270 | catenated with spaces to form the address. | |
271 | ||
272 | Note that this value cannot be set via the | |
273 | .I mdadm | |
274 | commandline. It is only settable via the config file. | |
275 | ||
276 | .TP | |
277 | .B PROGRAM | |
278 | The | |
279 | .B program | |
280 | line gives the name of a program to be run when | |
281 | .B "mdadm \-\-monitor" | |
282 | detects potentially interesting events on any of the arrays that it | |
283 | is monitoring. This program gets run with two or three arguments, they | |
284 | being the Event, the md device, and possibly the related component | |
285 | device. | |
286 | ||
287 | There should only be one | |
288 | .B program | |
289 | line and it should be give only one program. | |
290 | ||
291 | ||
292 | .TP | |
293 | .B CREATE | |
294 | The | |
295 | .B create | |
296 | line gives default values to be used when creating arrays, new members | |
297 | of arrays, and device entries for arrays. | |
298 | These include: | |
299 | ||
300 | .RS 4 | |
301 | .TP | |
302 | .B owner= | |
303 | .TP | |
304 | .B group= | |
305 | These can give user/group ids or names to use instead of system | |
306 | defaults (root/wheel or root/disk). | |
307 | .TP | |
308 | .B mode= | |
309 | An octal file mode such as 0660 can be given to override the default | |
310 | of 0600. | |
311 | .TP | |
312 | .B auto= | |
313 | This corresponds to the | |
314 | .B \-\-auto | |
315 | flag to mdadm. Give | |
316 | .BR yes , | |
317 | .BR md , | |
318 | .BR mdp , | |
319 | .B part | |
320 | \(em possibly followed by a number of partitions \(em to indicate how | |
321 | missing device entries should be created. | |
322 | ||
323 | .TP | |
324 | .B metadata= | |
325 | The name of the metadata format to use if none is explicitly given. | |
326 | This can be useful to impose a system-wide default of version-1 superblocks. | |
327 | ||
328 | .TP | |
329 | .B symlinks=no | |
330 | Normally when creating devices in | |
331 | .B /dev/md/ | |
332 | .I mdadm | |
333 | will create a matching symlink from | |
334 | .B /dev/ | |
335 | with a name starting | |
336 | .B md | |
337 | or | |
338 | .BR md_ . | |
339 | Give | |
340 | .B symlinks=no | |
341 | to suppress this symlink creation. | |
342 | ||
343 | .TP | |
344 | .B names=yes | |
345 | Since Linux 2.6.29 it has been possible to create | |
346 | .B md | |
347 | devices with a name like | |
348 | .B md_home | |
349 | rather than just a number, like | |
350 | .BR md3 . | |
351 | .I mdadm | |
352 | will use the numeric alternative by default as other tools that interact | |
353 | with md arrays may expect only numbers. | |
354 | If | |
355 | .B names=yes | |
356 | is given in | |
357 | .I mdadm.conf | |
358 | then | |
359 | .I mdadm | |
360 | will use a name when appropriate. | |
361 | If | |
362 | .B names=no | |
363 | is given, then non-numeric | |
364 | .I md | |
365 | device names will not be used even if the default changes in a future | |
366 | release of | |
367 | .IR mdadm . | |
368 | ||
369 | .TP | |
370 | .B bbl=no | |
371 | By default, | |
372 | .I mdadm | |
373 | will reserve space for a bad block list (bbl) on all devices | |
374 | included in or added to any array that supports them. Setting | |
375 | .B bbl=no | |
376 | will prevent this, so newly added devices will not have a bad | |
377 | block log. | |
378 | .RE | |
379 | ||
380 | .TP | |
381 | .B HOMEHOST | |
382 | The | |
383 | .B homehost | |
384 | line gives a default value for the | |
385 | .B \-\-homehost= | |
386 | option to mdadm. There should normally be only one other word on the line. | |
387 | It should either be a host name, or one of the special words | |
388 | .BR <system>, | |
389 | .B <none> | |
390 | and | |
391 | .BR <ignore> . | |
392 | If | |
393 | .B <system> | |
394 | is given, then the | |
395 | .BR gethostname ( 2 ) | |
396 | systemcall is used to get the host name. This is the default. | |
397 | ||
398 | If | |
399 | .B <ignore> | |
400 | is given, then a flag is set so that when arrays are being | |
401 | auto-assembled the checking of the recorded | |
402 | .I homehost | |
403 | is disabled. | |
404 | If | |
405 | .B <ignore> | |
406 | is given it is also possible to give an explicit name which will be | |
407 | used when creating arrays. This is the only case when there can be | |
408 | more that one other word on the | |
409 | .B HOMEHOST | |
410 | line. If there are other words, or other | |
411 | .B HOMEHOST | |
412 | lines, they are silently ignored. | |
413 | ||
414 | If | |
415 | .B <none> | |
416 | is given, then the default of using | |
417 | .BR gethostname ( 2 ) | |
418 | is over-ridden and no homehost name is assumed. | |
419 | ||
420 | When arrays are created, this host name will be stored in the | |
421 | metadata. When arrays are assembled using auto-assembly, arrays which | |
422 | do not record the correct homehost name in their metadata will be | |
423 | assembled using a "foreign" name. A "foreign" name alway ends with a | |
424 | digit string preceded by an underscore to differentiate it | |
425 | from any possible local name. e.g. | |
426 | .B /dev/md/1_1 | |
427 | or | |
428 | .BR /dev/md/home_0 . | |
429 | .TP | |
430 | .B AUTO | |
431 | A list of names of metadata format can be given, each preceded by a | |
432 | plus or minus sign. Also the word | |
433 | .I homehost | |
434 | is allowed as is | |
435 | .I all | |
436 | preceded by plus or minus sign. | |
437 | .I all | |
438 | is usually last. | |
439 | ||
440 | When | |
441 | .I mdadm | |
442 | is auto-assembling an array, either via | |
443 | .I \-\-assemble | |
444 | or | |
445 | .I \-\-incremental | |
446 | and it finds metadata of a given type, it checks that metadata type | |
447 | against those listed in this line. The first match wins, where | |
448 | .I all | |
449 | matches anything. | |
450 | If a match is found that was preceded by a plus sign, the auto | |
451 | assembly is allowed. If the match was preceded by a minus sign, the | |
452 | auto assembly is disallowed. If no match is found, the auto assembly | |
453 | is allowed. | |
454 | ||
455 | If the metadata indicates that the array was created for | |
456 | .I this | |
457 | host, and the word | |
458 | .I homehost | |
459 | appears before any other match, then the array is treated as a valid | |
460 | candidate for auto-assembly. | |
461 | ||
462 | This can be used to disable all auto-assembly (so that only arrays | |
463 | explicitly listed in mdadm.conf or on the command line are assembled), | |
464 | or to disable assembly of certain metadata types which might be | |
465 | handled by other software. It can also be used to disable assembly of | |
466 | all foreign arrays - normally such arrays are assembled but given a | |
467 | non-deterministic name in | |
468 | .BR /dev/md/ . | |
469 | ||
470 | The known metadata types are | |
471 | .BR 0.90 , | |
472 | .BR 1.x , | |
473 | .BR ddf , | |
474 | .BR imsm . | |
475 | ||
476 | .B AUTO | |
477 | should be given at most once. Subsequent lines are silently ignored. | |
478 | Thus an earlier config file in a config directory will over-ride | |
479 | the setting in a later config file. | |
480 | ||
481 | .TP | |
482 | .B POLICY | |
483 | This is used to specify what automatic behavior is allowed on devices | |
484 | newly appearing in the system and provides a way of marking spares that can | |
485 | be moved to other arrays as well as the migration domains. | |
486 | .I Domain | |
487 | can be defined through | |
488 | .I policy | |
489 | line by specifying a domain name for a number of paths from | |
490 | .BR /dev/disk/by-path/ . | |
491 | A device may belong to several domains. The domain of an array is a union | |
492 | of domains of all devices in that array. A spare can be automatically | |
493 | moved from one array to another if the set of the destination array's | |
494 | .I domains | |
495 | contains all the | |
496 | .I domains | |
497 | of the new disk or if both arrays have the same | |
498 | .IR spare-group . | |
499 | ||
500 | To update hot plug configuration it is necessary to execute | |
501 | .B mdadm \-\-udev\-rules | |
502 | command after changing the config file | |
503 | ||
504 | Key words used in the | |
505 | .I POLICY | |
506 | line and supported values are: | |
507 | ||
508 | .RS 7 | |
509 | .TP | |
510 | .B domain= | |
511 | any arbitrary string | |
512 | .TP | |
513 | .B metadata= | |
514 | 0.9 1.x ddf or imsm | |
515 | .TP | |
516 | .B path= | |
517 | file glob matching anything from | |
518 | .B /dev/disk/by-path | |
519 | .TP | |
520 | .B type= | |
521 | either | |
522 | .B disk | |
523 | or | |
524 | .BR part . | |
525 | .TP | |
526 | .B action= | |
527 | include, re-add, spare, spare-same-slot, or force-spare | |
528 | .TP | |
529 | .B auto= | |
530 | yes, no, or homehost. | |
531 | ||
532 | .P | |
533 | The | |
534 | .I action | |
535 | item determines the automatic behavior allowed for devices matching the | |
536 | .I path | |
537 | and | |
538 | .I type | |
539 | in the same line. If a device matches several lines with different | |
540 | .I actions | |
541 | then the most permissive will apply. The ordering of policy lines | |
542 | is irrelevant to the end result. | |
543 | .TP | |
544 | .B include | |
545 | allows adding a disk to an array if metadata on that disk matches that array | |
546 | .TP | |
547 | .B re\-add | |
548 | will include the device in the array if it appears to be a current member | |
549 | or a member that was recently removed and the array has a | |
550 | write-intent-bitmap to allow the | |
551 | .B re\-add | |
552 | functionality. | |
553 | .TP | |
554 | .B spare | |
555 | as above and additionally: if the device is bare it can | |
556 | become a spare if there is any array that it is a candidate for based | |
557 | on domains and metadata. | |
558 | .TP | |
559 | .B spare\-same\-slot | |
560 | as above and additionally if given slot was used by an array that went | |
561 | degraded recently and the device plugged in has no metadata then it will | |
562 | be automatically added to that array (or it's container) | |
563 | .TP | |
564 | .B force\-spare | |
565 | as above and the disk will become a spare in remaining cases | |
566 | .RE | |
567 | ||
568 | .SH EXAMPLE | |
569 | DEVICE /dev/sd[bcdjkl]1 | |
570 | .br | |
571 | DEVICE /dev/hda1 /dev/hdb1 | |
572 | ||
573 | # /dev/md0 is known by its UUID. | |
574 | .br | |
575 | ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371 | |
576 | .br | |
577 | # /dev/md1 contains all devices with a minor number of | |
578 | .br | |
579 | # 1 in the superblock. | |
580 | .br | |
581 | ARRAY /dev/md1 superminor=1 | |
582 | .br | |
583 | # /dev/md2 is made from precisely these two devices | |
584 | .br | |
585 | ARRAY /dev/md2 devices=/dev/hda1,/dev/hdb1 | |
586 | ||
587 | # /dev/md4 and /dev/md5 are a spare-group and spares | |
588 | .br | |
589 | # can be moved between them | |
590 | .br | |
591 | ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df | |
592 | .br | |
593 | spare\-group=group1 | |
594 | .br | |
595 | ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977 | |
596 | .br | |
597 | spare\-group=group1 | |
598 | .br | |
599 | # /dev/md/home is created if need to be a partitionable md array | |
600 | .br | |
601 | # any spare device number is allocated. | |
602 | .br | |
603 | ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b | |
604 | .br | |
605 | auto=part | |
606 | .br | |
607 | # The name of this array contains a space. | |
608 | .br | |
609 | ARRAY /dev/md9 name='Data Storage' | |
610 | .sp | |
611 | POLICY domain=domain1 metadata=imsm path=pci-0000:00:1f.2-scsi-* | |
612 | .br | |
613 | action=spare | |
614 | .br | |
615 | POLICY domain=domain1 metadata=imsm path=pci-0000:04:00.0-scsi-[01]* | |
616 | .br | |
617 | action=include | |
618 | .br | |
619 | # One domain comprising of devices attached to specified paths is defined. | |
620 | .br | |
621 | # Bare device matching first path will be made an imsm spare on hot plug. | |
622 | .br | |
623 | # If more than one array is created on devices belonging to domain1 and | |
624 | .br | |
625 | # one of them becomes degraded, then any imsm spare matching any path for | |
626 | .br | |
627 | # given domain name can be migrated. | |
628 | .br | |
629 | MAILADDR root@mydomain.tld | |
630 | .br | |
631 | PROGRAM /usr/sbin/handle\-mdadm\-events | |
632 | .br | |
633 | CREATE group=system mode=0640 auto=part\-8 | |
634 | .br | |
635 | HOMEHOST <system> | |
636 | .br | |
637 | AUTO +1.x homehost \-all | |
638 | ||
639 | .SH SEE ALSO | |
640 | .BR mdadm (8), | |
641 | .BR md (4). |