]> git.ipfire.org Git - thirdparty/mdadm.git/blame - mdadm.conf.5
Don't close fds in write_init_super
[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
6d6de2ee 342.B <system>
0ac91628
N
343and
344.BR <ignore> .
6d6de2ee
NB
345If
346.B <system>
347is given, then the
348.BR gethostname ( 2 )
349systemcall is used to get the host name.
5bbb4842 350
0ac91628
N
351If
352.B <ignore>
353is given, then a flag is set so that when arrays are being
e0fe762a 354auto-assembled the checking of the recorded
0ac91628
N
355.I homehost
356is disabled.
e0fe762a
N
357If
358.B <ignore>
359is given it is also possible to give an explicit name which will be
360used when creating arrays. This is the only case when there can be
361more that one other word on the
362.B HOMEHOST
363line.
0ac91628
N
364
365When arrays are created, this host name will be stored in the
366metadata. When arrays are assembled using auto-assembly, arrays which
367do not record the correct homehost name in their metadata will be
e0fe762a
N
368assembled using a "foreign" name. A "foreign" name alway ends with a
369digit string preceded by an underscore to differentiate it
0ac91628
N
370from any possible local name. e.g.
371.B /dev/md/1_1
372or
e0fe762a 373.BR /dev/md/home_0 .
31015d57
N
374.TP
375.B AUTO
376A list of names of metadata format can be given, each preceded by a
377plus or minus sign. Also the word
d1d3482b
N
378.I homehost
379is allowed as is
380.I all
381preceded by plus or minus sign.
31015d57 382.I all
d1d3482b 383is usually last.
31015d57
N
384
385When
386.I mdadm
a1331cc4 387is auto-assembling an array, either via
d1d3482b 388.I \-\-assemble
31015d57 389or
d1d3482b 390.I \-\-incremental
31015d57
N
391and it finds metadata of a given type, it checks that metadata type
392against those listed in this line. The first match wins, where
393.I all
394matches anything.
395If a match is found that was preceded by a plus sign, the auto
396assembly is allowed. If the match was preceded by a minus sign, the
397auto assembly is disallowed. If no match is found, the auto assembly
398is allowed.
399
d1d3482b
N
400If the metadata indicates that the array was created for
401.I this
402host, and the word
403.I homehost
404appears before any other match, then the array is treated as a valid
405candidate for auto-assembly.
406
31015d57
N
407This can be used to disable all auto-assembly (so that only arrays
408explicitly listed in mdadm.conf or on the command line are assembled),
409or to disable assembly of certain metadata types which might be
d1d3482b
N
410handled by other software. It can also be used to disable assembly of
411all foreign arrays - normally such arrays are assembled but given a
412non-deterministic name in
413.BR /dev/md/ .
31015d57
N
414
415The known metadata types are
416.BR 0.90 ,
417.BR 1.x ,
418.BR ddf ,
419.BR imsm .
420
2d465520
NB
421.SH EXAMPLE
422DEVICE /dev/sd[bcdjkl]1
423.br
424DEVICE /dev/hda1 /dev/hdb1
425
0e69da72 426# /dev/md0 is known by its UUID.
2d465520
NB
427.br
428ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371
429.br
430# /dev/md1 contains all devices with a minor number of
431.br
432# 1 in the superblock.
433.br
434ARRAY /dev/md1 superminor=1
435.br
93e790af 436# /dev/md2 is made from precisely these two devices
2d465520 437.br
a9d69660 438ARRAY /dev/md2 devices=/dev/hda1,/dev/hdb1
2d465520
NB
439
440# /dev/md4 and /dev/md5 are a spare-group and spares
441.br
442# can be moved between them
443.br
444ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df
445.br
7e23fc43 446 spare\-group=group1
2d465520
NB
447.br
448ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977
449.br
7e23fc43 450 spare\-group=group1
dd0781e5
NB
451.br
452# /dev/md/home is created if need to be a partitionable md array
453.br
454# any spare device number is allocated.
455.br
456ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b
457.br
458 auto=part
2d465520
NB
459
460MAILADDR root@mydomain.tld
461.br
7e23fc43 462PROGRAM /usr/sbin/handle\-mdadm\-events
5bbb4842 463.br
7e23fc43 464CREATE group=system mode=0640 auto=part\-8
41a3b72a
NB
465.br
466HOMEHOST <system>
31015d57 467.br
d1d3482b 468AUTO +1.x homehost -all
e0d19036 469
56eb10c0 470.SH SEE ALSO
11a3e71d
NB
471.BR mdadm (8),
472.BR md (4).
56eb10c0 473