1MDADM.CONF(5)                 File Formats Manual                MDADM.CONF(5)
2
3
4

NAME

6       mdadm.conf - configuration for management of Software RAID with mdadm
7

SYNOPSIS

9       /etc/mdadm.conf
10

DESCRIPTION

12       mdadm  is  a  tool  for creating, managing, and monitoring RAID devices
13       using the md driver in Linux.
14
15       Some common tasks, such as assembling all arrays, can be simplified  by
16       describing the devices and arrays in this configuration file.
17
18
19   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
25       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
32       Any  line  that  starts  with  white space (space or tab) is treated as
33       though it were a continuation of the previous line.
34
35       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
39       The keywords are:
40
41       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
46              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
50              Also, there may be several device lines present in the file.
51
52              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
57              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
63              If no DEVICE line is present, then "DEVICE  partitions  contain‐
64              ers" is assumed.
65
66              For example:
67
68              DEVICE /dev/hda* /dev/hdc*
69              DEV    /dev/sd*
70              DEVICE /dev/disk/by-path/pci*
71              DEVICE partitions
72
73
74       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
84              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
90           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
94           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
100           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
106           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
113           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
116                  mdadm --examine --scan
117
118                  can be use directly in the configuration file.
119
120           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
125                  mdadm --examine --scan.
126
127
128           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
135
136           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
145
146           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
153                  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
161
162           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
169
170           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
175
176           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
181
182           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
189
190       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
197
198       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
206              Note  that  this  value cannot be set via the mdadm commandline.
207              It is only settable via the config file.
208
209
210       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
217              There should only be one program line and it should be give only
218              one program.
219
220
221
222       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
226
227           owner=
228
229           group= These  can  give  user/group  ids or names to use instead of
230                  system defaults (root/wheel or root/disk).
231
232           mode=  An octal file mode such as 0660 can be given to override the
233                  default of 0600.
234
235           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
239
240           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
245
246           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
251
252           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
262
263           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
268
269       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
277              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
285              If <none> is given, then the default of using gethostname(2)  is
286              over-ridden and no homehost name is assumed.
287
288              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
296       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
300              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
308              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
312              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
319              The known metadata types are 0.90, 1.x, ddf, imsm.
320
321              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
325
326       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
338              To update hot plug configuration  it  is  necessary  to  execute
339              mdadm --udev-rules command after changing the config file
340
341              Key words used in the POLICY line and supported values are:
342
343
344              domain=
345                     any arbitrary string
346
347              metadata=
348                     0.9 1.x ddf or imsm
349
350              path=  file glob matching anything from /dev/disk/by-path
351
352              type=  either disk or part.
353
354              action=
355                     include, re-add, spare, spare-same-slot, or force-spare
356
357              auto=  yes, no, or homehost.
358
359
360              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
366              include
367                     allows adding a disk to an array if metadata on that disk
368                     matches that array
369
370              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
375              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
379              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
385              force-spare
386                     as above and the disk will become a  spare  in  remaining
387                     cases
388
389

EXAMPLE

391       DEVICE /dev/sd[bcdjkl]1
392       DEVICE /dev/hda1 /dev/hdb1
393
394       # /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
402       # /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
415       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
433

SEE ALSO

435       mdadm(8), md(4).
436
437
438
439                                                                 MDADM.CONF(5)
Impressum