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