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, then "DEVICE partitions contain‐
64 ers" 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.
208 PROGRAM
211 The program line gives the name of a program to be run when
212 mdadm --monitor detects potentially interesting events on any of
213 the arrays that it is monitoring. This program gets run with
214 two or three arguments, they being the Event, the md device, and
215 possibly the related component device.
216 There should only be one program line and it should be give only
218 one program.
219 CREATE The create line gives default values to be used when creating
223 arrays, new members of arrays, and device entries for arrays.
224 These include:
225 owner=
228 group= These can give user/group ids or names to use instead of
230 system defaults (root/wheel or root/disk).
231 mode= An octal file mode such as 0660 can be given to override the
233 default of 0600.
234 auto= This corresponds to the --auto flag to mdadm. Give yes, md,
236 mdp, part — possibly followed by a number of partitions — to
237 indicate how missing device entries should be created.
238 metadata=
241 The name of the metadata format to use if none is explicitly
242 given. This can be useful to impose a system-wide default
243 of version-1 superblocks.
244 symlinks=no
247 Normally when creating devices in /dev/md/ mdadm will create
248 a matching symlink from /dev/ with a name starting md or
249 md_. Give symlinks=no to suppress this symlink creation.
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 AUTO A list of names of metadata format can be given, each preceded
297 by a plus or minus sign. Also the word homehost is allowed as
298 is all preceded by plus or minus sign. all is usually last.
299 When mdadm is auto-assembling an array, either via --assemble or
301 --incremental and it finds metadata of a given type, it checks
302 that metadata type against those listed in this line. The first
303 match wins, where all matches anything. If a match is found
304 that was preceded by a plus sign, the auto assembly is allowed.
305 If the match was preceded by a minus sign, the auto assembly is
306 disallowed. If no match is found, the auto assembly is allowed.
307 If the metadata indicates that the array was created for this
309 host, and the word homehost appears before any other match, then
310 the array is treated as a valid candidate for auto-assembly.
311 This can be used to disable all auto-assembly (so that only ar‐
313 rays explicitly listed in mdadm.conf or on the command line are
314 assembled), or to disable assembly of certain metadata types
315 which might be handled by other software. It can also be used
316 to disable assembly of all foreign arrays - normally such arrays
317 are assembled but given a non-deterministic name in /dev/md/.
318 The known metadata types are 0.90, 1.x, ddf, imsm.
320 AUTO should be given at most once. Subsequent lines are
322 silently ignored. Thus an earlier config file in a config di‐
323 rectory will over-ride the setting in a later config file.
324 POLICY This is used to specify what automatic behavior is allowed on
327 devices newly appearing in the system and provides a way of
328 marking spares that can be moved to other arrays as well as the
329 migration domains. Domain can be defined through policy line by
330 specifying a domain name for a number of paths from
331 /dev/disk/by-path/. A device may belong to several domains. The
332 domain of an array is a union of domains of all devices in that
333 array. A spare can be automatically moved from one array to an‐
334 other if the set of the destination array's domains contains all
335 the domains of the new disk or if both arrays have the same
336 spare-group.
337 To update hot plug configuration it is necessary to execute
339 mdadm --udev-rules command after changing the config file
340 Keywords used in the POLICY line and supported values are:
342 domain=
345 any arbitrary string
346 metadata=
348 0.9 1.x ddf or imsm
349 path= file glob matching anything from /dev/disk/by-path
351 type= either disk or part.
353 action=
355 include, re-add, spare, spare-same-slot, or force-spare
356 auto= yes, no, or homehost.
358 The action item determines the automatic behavior allowed for de‐
361 vices matching the path and type in the same line. If a device
362 matches several lines with different actions then the most permis‐
363 sive will apply. The ordering of policy lines is irrelevant to the
364 end result.
365 include
367 allows adding a disk to an array if metadata on that disk
368 matches that array
369 re-add will include the device in the array if it appears to be a
371 current member or a member that was recently removed and the
372 array has a write-intent-bitmap to allow the re-add func‐
373 tionality.
374 spare as above and additionally: if the device is bare it can be‐
376 come a spare if there is any array that it is a candidate
377 for based on domains and metadata.
378 spare-same-slot
380 as above and additionally if given slot was used by an array
381 that went degraded recently and the device plugged in has no
382 metadata then it will be automatically added to that array
383 (or it's container)
384 force-spare
386 as above and the disk will become a spare in remaining cases
387 PART-POLICY
390 This is similar to POLICY and accepts the same keyword assign‐
391 ments. It allows a consistent set of policies to applied to
392 each of the partitions of a device.
393 A PART-POLICY line should set type=disk and identify the path to
395 one or more disk devices. Each partition on these disks will be
396 treated according to the action= setting from this line. If a
397 domain is set in the line, then the domain associated with each
398 patition will be based on the domain, but with "-partN" ap‐
399 pended, when N is the partition number for the partition that
400 was found.
401 SYSFS The SYSFS line lists custom values of MD device's sysfs at‐
404 tributes which will be stored in sysfs after the array is assem‐
405 bled. Multiple lines are allowed and each line has to contain
406 the uuid or the name of the device to which it relates.
407 uuid= hexadecimal identifier of MD device. This has to match the
409 uuid stored in the superblock.
410 name= name of the MD device as was given to mdadm when the array
412 was created. It will be ignored if uuid is not empty.
413 MONITORDELAY
416 The monitordelay line gives a delay in seconds mdadm shall wait
417 before pooling md arrays when mdadm is running in --monitor
418 mode. -d/--delay command line argument takes precedence over
419 the config file
420
423 DEVICE /dev/sd[bcdjkl]1
424 DEVICE /dev/hda1 /dev/hdb1
425 # /dev/md0 is known by its UUID.
427 ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371
428 # /dev/md1 contains all devices with a minor number of
429 # 1 in the superblock.
430 ARRAY /dev/md1 superminor=1
431 # /dev/md2 is made from precisely these two devices
432 ARRAY /dev/md2 devices=/dev/hda1,/dev/hdb1
433 # /dev/md4 and /dev/md5 are a spare-group and spares
435 # can be moved between them
436 ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df
437 spare-group=group1
438 ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977
439 spare-group=group1
440 # /dev/md/home is created if need to be a partitionable md array
441 # any spare device number is allocated.
442 ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b
443 auto=part
444 # The name of this array contains a space.
445 ARRAY /dev/md9 name='Data Storage'
446 POLICY domain=domain1 metadata=imsm path=pci-0000:00:1f.2-scsi-*
448 action=spare
449 POLICY domain=domain1 metadata=imsm path=pci-0000:04:00.0-scsi-[01]*
450 action=include
451 # One domain comprising of devices attached to specified paths is de‐
452 fined.
453 # Bare device matching first path will be made an imsm spare on hot
454 plug.
455 # If more than one array is created on devices belonging to domain1 and
456 # one of them becomes degraded, then any imsm spare matching any path
457 for
458 # given domain name can be migrated.
459 MAILADDR root@mydomain.tld
460 PROGRAM /usr/sbin/handle-mdadm-events
461 CREATE group=system mode=0640 auto=part-8
462 HOMEHOST <system>
463 AUTO +1.x homehost -all
464 SYSFS name=/dev/md/raid5 group_thread_cnt=4 sync_speed_max=1000000
465 SYSFS uuid=bead5eb6:31c17a27:da120ba2:7dfda40d group_thread_cnt=4
466 sync_speed_max=1000000
467 MONITORDELAY 60
468
471 mdadm(8), md(4).
472 MDADM.CONF(5)