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
13 using 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
37 insensitive 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
82 determine 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
108 device name patterns. Only devices with names which match
109 one entry in the list will be used to assemble the array.
110 Note that the devices listed there must also be listed on a
111 DEVICE 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
122 array. 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
138 arrays with the same spare-group name are considered to be
139 part of the same group. The significance of a group of
140 arrays is that mdadm will, when monitoring the arrays, move
141 a 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
149 arrays and, in the absence of udev, how many partition
150 devices to create. From 2.6.28 all md array devices are
151 partitionable, 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
159 device 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
167 --assemble.
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
185 arrays, often a simple sequence number. The value identi‐
186 fies which member of a container the array is. It will usu‐
187 ally 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
204 address.
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=
271 option to mdadm. There should normally be only one other word
272 on the line. It should either be a host name, or one of the
273 special words <system>, <none> and <ignore>. If <system> is
274 given, then the gethostname(2) systemcall is used to get the
275 host name. 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
292 alway 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
313 arrays explicitly listed in mdadm.conf or on the command line
314 are 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
323 directory 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
334 another if the set of the destination array's domains contains
335 all 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 Key words 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
361 devices matching the path and type in the same line. If a
362 device matches several lines with different actions then the
363 most permissive will apply. The ordering of policy lines is
364 irrelevant to the 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
371 a current member or a member that was recently removed
372 and the array has a write-intent-bitmap to allow the
373 re-add functionality.
374 spare as above and additionally: if the device is bare it can
376 become a spare if there is any array that it is a candi‐
377 date for based on domains and metadata.
378 spare-same-slot
380 as above and additionally if given slot was used by an
381 array that went degraded recently and the device plugged
382 in has no metadata then it will be automatically added to
383 that array (or it's container)
384 force-spare
386 as above and the disk will become a spare in remaining
387 cases
388
391 DEVICE /dev/sd[bcdjkl]1
392 DEVICE /dev/hda1 /dev/hdb1
393 # /dev/md0 is known by its UUID.
395 ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371
396 # /dev/md1 contains all devices with a minor number of
397 # 1 in the superblock.
398 ARRAY /dev/md1 superminor=1
399 # /dev/md2 is made from precisely these two devices
400 ARRAY /dev/md2 devices=/dev/hda1,/dev/hdb1
401 # /dev/md4 and /dev/md5 are a spare-group and spares
403 # can be moved between them
404 ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df
405 spare-group=group1
406 ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977
407 spare-group=group1
408 # /dev/md/home is created if need to be a partitionable md array
409 # any spare device number is allocated.
410 ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b
411 auto=part
412 # The name of this array contains a space.
413 ARRAY /dev/md9 name='Data Storage'
414 POLICY domain=domain1 metadata=imsm path=pci-0000:00:1f.2-scsi-*
416 action=spare
417 POLICY domain=domain1 metadata=imsm path=pci-0000:04:00.0-scsi-[01]*
418 action=include
419 # One domain comprising of devices attached to specified paths is
420 defined.
421 # Bare device matching first path will be made an imsm spare on hot
422 plug.
423 # If more than one array is created on devices belonging to domain1 and
424 # one of them becomes degraded, then any imsm spare matching any path
425 for
426 # given domain name can be migrated.
427 MAILADDR root@mydomain.tld
428 PROGRAM /usr/sbin/handle-mdadm-events
429 CREATE group=system mode=0640 auto=part-8
430 HOMEHOST <system>
431 AUTO +1.x homehost -all
432
435 mdadm(8), md(4).
436 MDADM.CONF(5)