1MDADM.CONF(5) File Formats Manual MDADM.CONF(5)
2
6 mdadm.conf - configuration for management of Software RAID with mdadm
7
9 /etc/mdadm.conf
10
12 mdadm is a tool for creating, managing, and monitoring RAID devices us‐
13 ing the md driver in Linux.
14 Some common tasks, such as assembling all arrays, can be simplified by
16 describing the devices and arrays in this configuration file.
17 SYNTAX
20 The file should be seen as a collection of words separated by white
21 space (space, tab, or newline). Any word that beings with a hash sign
22 (#) starts a comment and that word together with the remainder of the
23 line is ignored.
24 Spaces can be included in a word using quotation characters. Either
26 single quotes (') or double quotes (") may be used. All the characters
27 from one quotation character to next identical character are protected
28 and will not be used to separate words to start new quoted strings. To
29 include a single quote it must be between double quotes. To include a
30 double quote it must be between single quotes.
31 Any line that starts with white space (space or tab) is treated as
33 though it were a continuation of the previous line.
34 Empty lines are ignored, but otherwise each (non continuation) line
36 must start with a keyword as listed below. The keywords are case in‐
37 sensitive and can be abbreviated to 3 characters.
38 The keywords are:
40 DEVICE A device line lists the devices (whole devices or partitions)
42 that might contain a component of an MD array. When looking for
43 the components of an array, mdadm will scan these devices (or
44 any devices listed on the command line).
45 The device line may contain a number of different devices (sepa‐
47 rated by spaces) and each device name can contain wild cards as
48 defined by glob(7).
49 Also, there may be several device lines present in the file.
51 Alternatively, a device line can contain either or both of the
53 words containers and partitions. The word containers will cause
54 mdadm to look for assembled CONTAINER arrays and included them
55 as a source for assembling further arrays.
56 The word partitions will cause mdadm to read /proc/partitions
58 and include all devices and partitions found therein. mdadm
59 does not use the names from /proc/partitions but only the major
60 and minor device numbers. It scans /dev to find the name that
61 matches the numbers.
62 If no DEVICE line is present in any config file, then "DEVICE
64 partitions containers" is assumed.
65 For example:
67 DEVICE /dev/hda* /dev/hdc*
69 DEV /dev/sd*
70 DEVICE /dev/disk/by-path/pci*
71 DEVICE partitions
72 ARRAY The ARRAY lines identify actual arrays. The second word on the
75 line may be the name of the device where the array is normally
76 assembled, such as /dev/md1 or /dev/md/backup. If the name does
77 not start with a slash ('/'), it is treated as being in
78 /dev/md/. Alternately the word <ignore> (complete with angle
79 brackets) can be given in which case any array which matches the
80 rest of the line will never be automatically assembled. If no
81 device name is given, mdadm will use various heuristics to de‐
82 termine an appropriate name.
83 Subsequent words identify the array, or identify the array as a
85 member of a group. If multiple identities are given, then a com‐
86 ponent device must match ALL identities to be considered a
87 match. Each identity word has a tag, and equals sign, and some
88 value. The tags are:
89 uuid= The value should be a 128 bit uuid in hexadecimal, with
91 punctuation interspersed if desired. This must match the
92 uuid stored in the superblock.
93 name= The value should be a simple textual name as was given to
95 mdadm when the array was created. This must match the name
96 stored in the superblock on a device for that device to be
97 included in the array. Not all superblock formats support
98 names.
99 super-minor=
101 The value is an integer which indicates the minor number
102 that was stored in the superblock when the array was cre‐
103 ated. When an array is created as /dev/mdX, then the minor
104 number X is stored.
105 devices=
107 The value is a comma separated list of device names or de‐
108 vice name patterns. Only devices with names which match one
109 entry in the list will be used to assemble the array. Note
110 that the devices listed there must also be listed on a DE‐
111 VICE line.
112 level= The value is a RAID level. This is not normally used to
114 identify an array, but is supported so that the output of
115 mdadm --examine --scan
117 can be use directly in the configuration file.
119 num-devices=
121 The value is the number of devices in a complete active ar‐
122 ray. As with level= this is mainly for compatibility with
123 the output of
124 mdadm --examine --scan.
126 spares=
129 The value is a number of spare devices to expect the array
130 to have. The sole use of this keyword and value is as fol‐
131 lows: mdadm --monitor will report an array if it is found to
132 have fewer than this number of spares when --monitor starts
133 or when --oneshot is used.
134 spare-group=
137 The value is a textual name for a group of arrays. All ar‐
138 rays with the same spare-group name are considered to be
139 part of the same group. The significance of a group of ar‐
140 rays is that mdadm will, when monitoring the arrays, move a
141 spare drive from one array in a group to another array in
142 that group if the first array had a failed or missing drive
143 but no spare.
144 auto= This option is rarely needed with mdadm-3.0, particularly if
147 use with the Linux kernel v2.6.28 or later. It tells mdadm
148 whether to use partitionable array or non-partitionable ar‐
149 rays and, in the absence of udev, how many partition devices
150 to create. From 2.6.28 all md array devices are partition‐
151 able, hence this option is not needed.
152 The value of this option can be "yes" or "md" to indicate
154 that a traditional, non-partitionable md array should be
155 created, or "mdp", "part" or "partition" to indicate that a
156 partitionable md array (only available in linux 2.6 and
157 later) should be used. This later set can also have a num‐
158 ber appended to indicate how many partitions to create de‐
159 vice files for, e.g. auto=mdp5. The default is 4.
160 bitmap=
163 The option specifies a file in which a write-intent bitmap
164 should be found. When assembling the array, mdadm will pro‐
165 vide this file to the md driver as the bitmap file. This
166 has the same function as the --bitmap-file option to --as‐
167 semble.
168 metadata=
171 Specify the metadata format that the array has. This is
172 mainly recognised for comparability with the output of mdadm
173 -Es.
174 container=
177 Specify that this array is a member array of some container.
178 The value given can be either a path name in /dev, or a UUID
179 of the container array.
180 member=
183 Specify that this array is a member array of some container.
184 Each type of container has some way to enumerate member ar‐
185 rays, often a simple sequence number. The value identifies
186 which member of a container the array is. It will usually
187 accompany a "container=" word.
188 MAILADDR
191 The mailaddr line gives an E-mail address that alerts should be
192 sent to when mdadm is running in --monitor mode (and was given
193 the --scan option). There should only be one MAILADDR line and
194 it should have only one address. Any subsequent addresses are
195 silently ignored.
196 MAILFROM
199 The mailfrom line (which can only be abbreviated to at least 5
200 characters) gives an address to appear in the "From" address for
201 alert mails. This can be useful if you want to explicitly set a
202 domain, as the default from address is "root" with no domain.
203 All words on this line are catenated with spaces to form the ad‐
204 dress.
205 Note that this value cannot be set via the mdadm commandline.
207 It is only settable via the config file. There should only be
208 one MAILADDR line and it should have only one address. Any sub‐
209 sequent addresses are silently ignored.
210 PROGRAM
213 The program line gives the name of a program to be run when
214 mdadm --monitor detects potentially interesting events on any of
215 the arrays that it is monitoring. This program gets run with
216 two or three arguments, they being the Event, the md device, and
217 possibly the related component device.
218 There should only be one program line and it should be given
220 only one program. Any subsequent programs are silently ignored.
221 CREATE The create line gives default values to be used when creating
225 arrays, new members of arrays, and device entries for arrays.
226 There should only be one create line. Any subsequent lines will
228 override the previous settings.
229 Keywords used in the CREATE line and supported values are:
231 owner=
234 group= These can give user/group ids or names to use instead of
236 system defaults (root/wheel or root/disk).
237 mode= An octal file mode such as 0660 can be given to override the
239 default of 0600.
240 auto= This corresponds to the --auto flag to mdadm. Give yes, md,
242 mdp, part — possibly followed by a number of partitions — to
243 indicate how missing device entries should be created.
244 metadata=
247 The name of the metadata format to use if none is explicitly
248 given. This can be useful to impose a system-wide default
249 of version-1 superblocks.
250 names=yes
253 Since Linux 2.6.29 it has been possible to create md devices
254 with a name like md_home rather than just a number, like
255 md3. mdadm will use the numeric alternative by default as
256 other tools that interact with md arrays may expect only
257 numbers. If names=yes is given in mdadm.conf then mdadm
258 will use a name when appropriate. If names=no is given,
259 then non-numeric md device names will not be used even if
260 the default changes in a future release of mdadm.
261 bbl=no By default, mdadm will reserve space for a bad block list
264 (bbl) on all devices included in or added to any array that
265 supports them. Setting bbl=no will prevent this, so newly
266 added devices will not have a bad block log.
267 HOMEHOST
270 The homehost line gives a default value for the --homehost= op‐
271 tion to mdadm. There should normally be only one other word on
272 the line. It should either be a host name, or one of the spe‐
273 cial words <system>, <none> and <ignore>. If <system> is given,
274 then the gethostname(2) systemcall is used to get the host name.
275 This is the default.
276 If <ignore> is given, then a flag is set so that when arrays are
278 being auto-assembled the checking of the recorded homehost is
279 disabled. If <ignore> is given it is also possible to give an
280 explicit name which will be used when creating arrays. This is
281 the only case when there can be more that one other word on the
282 HOMEHOST line. If there are other words, or other HOMEHOST
283 lines, they are silently ignored.
284 If <none> is given, then the default of using gethostname(2) is
286 over-ridden and no homehost name is assumed.
287 When arrays are created, this host name will be stored in the
289 metadata. When arrays are assembled using auto-assembly, arrays
290 which do not record the correct homehost name in their metadata
291 will be assembled using a "foreign" name. A "foreign" name al‐
292 way ends with a digit string preceded by an underscore to dif‐
293 ferentiate it from any possible local name. e.g. /dev/md/1_1 or
294 /dev/md/home_0.
295 HOMECLUSTER
298 The homcluster line gives a default value for the --homecluster=
299 option to mdadm. It specifies the cluster name for the md de‐
300 vice. The md device can be assembled only on the cluster which
301 matches the name specified. If homcluster is not provided, mdadm
302 tries to detect the cluster name automatically.
303 There should only be one homecluster line. Any subsequent lines
305 will be silently ignored.
306 AUTO A list of names of metadata format can be given, each preceded
309 by a plus or minus sign. Also the word homehost is allowed as
310 is all preceded by plus or minus sign. all is usually last.
311 When mdadm is auto-assembling an array, either via --assemble or
313 --incremental and it finds metadata of a given type, it checks
314 that metadata type against those listed in this line. The first
315 match wins, where all matches anything. If a match is found
316 that was preceded by a plus sign, the auto assembly is allowed.
317 If the match was preceded by a minus sign, the auto assembly is
318 disallowed. If no match is found, the auto assembly is allowed.
319 If the metadata indicates that the array was created for this
321 host, and the word homehost appears before any other match, then
322 the array is treated as a valid candidate for auto-assembly.
323 This can be used to disable all auto-assembly (so that only ar‐
325 rays explicitly listed in mdadm.conf or on the command line are
326 assembled), or to disable assembly of certain metadata types
327 which might be handled by other software. It can also be used
328 to disable assembly of all foreign arrays - normally such arrays
329 are assembled but given a non-deterministic name in /dev/md/.
330 The known metadata types are 0.90, 1.x, ddf, imsm.
332 AUTO should be given at most once. Subsequent lines are
334 silently ignored. Thus a later config file in a config direc‐
335 tory will not overwrite the setting in an earlier config file.
336 POLICY This is used to specify what automatic behavior is allowed on
339 devices newly appearing in the system and provides a way of
340 marking spares that can be moved to other arrays as well as the
341 migration domains. Domain can be defined through policy line by
342 specifying a domain name for a number of paths from
343 /dev/disk/by-path/. A device may belong to several domains. The
344 domain of an array is a union of domains of all devices in that
345 array. A spare can be automatically moved from one array to an‐
346 other if the set of the destination array's domains contains all
347 the domains of the new disk or if both arrays have the same
348 spare-group.
349 To update hot plug configuration it is necessary to execute
351 mdadm --udev-rules command after changing the config file
352 Keywords used in the POLICY line and supported values are:
354 domain=
357 any arbitrary string
358 metadata=
360 0.9 1.x ddf or imsm
361 path= file glob matching anything from /dev/disk/by-path
363 type= either disk or part.
365 action=
367 include, re-add, spare, spare-same-slot, or force-spare
368 auto= yes, no, or homehost.
370 The action item determines the automatic behavior allowed for de‐
373 vices matching the path and type in the same line. If a device
374 matches several lines with different actions then the most permis‐
375 sive will apply. The ordering of policy lines is irrelevant to the
376 end result.
377 include
379 allows adding a disk to an array if metadata on that disk
380 matches that array
381 re-add will include the device in the array if it appears to be a
383 current member or a member that was recently removed and the
384 array has a write-intent-bitmap to allow the re-add func‐
385 tionality.
386 spare as above and additionally: if the device is bare it can be‐
388 come a spare if there is any array that it is a candidate
389 for based on domains and metadata.
390 spare-same-slot
392 as above and additionally if given slot was used by an array
393 that went degraded recently and the device plugged in has no
394 metadata then it will be automatically added to that array
395 (or it's container)
396 force-spare
398 as above and the disk will become a spare in remaining cases
399 PART-POLICY
402 This is similar to POLICY and accepts the same keyword assign‐
403 ments. It allows a consistent set of policies to applied to
404 each of the partitions of a device.
405 A PART-POLICY line should set type=disk and identify the path to
407 one or more disk devices. Each partition on these disks will be
408 treated according to the action= setting from this line. If a
409 domain is set in the line, then the domain associated with each
410 patition will be based on the domain, but with "-partN" ap‐
411 pended, when N is the partition number for the partition that
412 was found.
413 SYSFS The SYSFS line lists custom values of MD device's sysfs at‐
416 tributes which will be stored in sysfs after the array is assem‐
417 bled. Multiple lines are allowed and each line has to contain
418 the uuid or the name of the device to which it relates. Lines
419 are applied in reverse order.
420 uuid= hexadecimal identifier of MD device. This has to match the
422 uuid stored in the superblock.
423 name= name of the MD device as was given to mdadm when the array
425 was created. It will be ignored if uuid is not empty.
426 MONITORDELAY
429 The monitordelay line gives a delay in seconds mdadm shall wait
430 before pooling md arrays when mdadm is running in --monitor
431 mode. -d/--delay command line argument takes precedence over
432 the config file.
433 If multiple MINITORDELAY lines are provided, only first non-zero
435 value is considered.
436
439 /etc/mdadm.conf
440 The default config file location, used when mdadm is running without
441 --config option.
442 /etc/mdadm.conf.d
445 The default directory with config files. Used when mdadm is running
446 without --config option, after successful reading of the
447 /etc/mdadm.conf default config file. Files in that directory are read
448 in lexical order.
449 /etc/mdadm/mdadm.conf
453 Alternative config file that is read, when mdadm is running without
454 --config option and the /etc/mdadm.conf default config file was not
455 opened successfully.
456 /etc/mdadm/mdadm.conf.d
459 The alternative directory with config files. Used when mdadm is run‐
460 ninng without --config option, after reading the /etc/mdadm/mdadm.conf
461 alternative config file whether it was successful or not. Files in that
462 directory are read in lexical order.
463
466 DEVICE /dev/sd[bcdjkl]1
467 DEVICE /dev/hda1 /dev/hdb1
468 # /dev/md0 is known by its UUID.
470 ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371
471 # /dev/md1 contains all devices with a minor number of
472 # 1 in the superblock.
473 ARRAY /dev/md1 superminor=1
474 # /dev/md2 is made from precisely these two devices
475 ARRAY /dev/md2 devices=/dev/hda1,/dev/hdb1
476 # /dev/md4 and /dev/md5 are a spare-group and spares
478 # can be moved between them
479 ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df
480 spare-group=group1
481 ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977
482 spare-group=group1
483 # /dev/md/home is created if need to be a partitionable md array
484 # any spare device number is allocated.
485 ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b
486 auto=part
487 # The name of this array contains a space.
488 ARRAY /dev/md9 name='Data Storage'
489 POLICY domain=domain1 metadata=imsm path=pci-0000:00:1f.2-scsi-*
491 action=spare
492 POLICY domain=domain1 metadata=imsm path=pci-0000:04:00.0-scsi-[01]*
493 action=include
494 # One domain comprising of devices attached to specified paths is de‐
495 fined.
496 # Bare device matching first path will be made an imsm spare on hot
497 plug.
498 # If more than one array is created on devices belonging to domain1 and
499 # one of them becomes degraded, then any imsm spare matching any path
500 for
501 # given domain name can be migrated.
502 MAILADDR root@mydomain.tld
503 PROGRAM /usr/sbin/handle-mdadm-events
504 CREATE group=system mode=0640 auto=part-8
505 HOMEHOST <system>
506 AUTO +1.x homehost -all
507 SYSFS name=/dev/md/raid5 group_thread_cnt=4 sync_speed_max=1000000
508 SYSFS uuid=bead5eb6:31c17a27:da120ba2:7dfda40d group_thread_cnt=4
509 sync_speed_max=1000000
510 MONITORDELAY 60
511
514 mdadm(8), md(4).
515 MDADM.CONF(5)