mdadm-1.6.0
[thirdparty/mdadm.git] / mdadm.conf.5
index 59235bc..9739010 100644 (file)
@@ -6,25 +6,25 @@ mdadm.conf \- configuration for management of Software Raid with mdadm
 .SH DESCRIPTION
 .PP
 .B mdadm
-is a tools for creating an managing RAID devices using the
+is a tool for creating, managing, and monitoring RAID devices using the
 .B md
 driver in Linux.
 .PP
 Some common tasks, such as assembling all arrays, can be simplified
-by describing the devices and array in this configuations file.
+by describing the devices and arrays in this configuration file.
 
 .SS SYNTAX
 The file should be seen as a collection of words separated by white
 space (space, tab, or newline).
-Any word that being with a hash sign (#) starts a comment and that
-word together with the remainder of the line are ignored.
+Any word that beings with a hash sign (#) starts a comment and that
+word together with the remainder of the line is ignored.
 
-Any line that start with white space (space or tab) is treated as
+Any line that starts with white space (space or tab) is treated as
 though it were a continuation of the previous line.
 
 Empty lines are ignored, but otherwise each (non continuation) line
-must start with a keyword as listed below.  The key words are case
-insensitve and can be abbreviated to 3 characters.
+must start with a keyword as listed below.  The keywords are case
+insensitive and can be abbreviated to 3 characters.
 
 The keywords are:
 .TP
@@ -35,7 +35,7 @@ line lists the devices (whole devices or partitions) that might contain
 a component of an MD array.  When looking for the components of an
 array,
 .B mdadm
-will scan these devices and no others.
+will scan these devices (or any devices listed on the command line).
 
 The
 .B device
@@ -45,10 +45,183 @@ and each device name can contain wild cards as defined by
 
 Also, there may be several device lines present in the file.
 
+Alternatively, a
+.B device
+line can contain the word
+.BR partitions .
+This will cause
+.I mdadm
+to read
+.I /proc/partitions
+and include all devices and partitions found there-in.
+.I mdadm
+does not use the names from
+.I /proc/partitions
+but only the major and minor device numbers.  It scans
+.I /dev
+to find the name that matches the numbers.
+
+For example:
+.IP
+DEVICE /dev/hda* /dev/hdc*
+.br
+DEV    /dev/sd*
+.br
+DEVICE /dev/discs/disc*/disc
+.br
+DEVICE partitions
+
 .TP
 .B ARRAY
+The ARRAY lines identify actual arrays.  The second word on the line
+should be the name of the device where the array is normally
+assembled, such as
+.BR  /dev/md1 .
+Subsequent words identify the array, or identify the array as a member
+of a group. If multiple identities are given,
+then a component device must match ALL identities to be considered a
+match.  Each identity word has a tag, and equals sign, and some value.
+The tags are:
+
+.RS 4
+.TP
+.B uuid=
+The value should be a 128 bit uuid in hexadecimal, with punctuation
+interspersed if desired.  This must match the uuid stored in the
+superblock.
+.TP
+.B super-minor=
+The value is an integer which indicates the minor number that was
+stored in the superblock when the array was created. When an array is
+created as /dev/mdX, then the minor number X is stored.
+.TP
+.B devices=
+The value is a comma separated list of device names or device name
+patterns.
+Only devices with names which match one entry in the list will be used
+to assemble the array.  Note that the devices 
+listed there must also be listed on a DEVICE line.
+.TP
+.B level=
+The value is a raid level.  This is not normally used to
+identify an array, but is supported so that the output of
+
+.B "mdadm --examine --scan"
+
+can be use directly in the configuration file.
+.TP
+.B num-devices=
+The value is the number of devices in a complete active array.  As with
+.B level=
+this is mainly for compatibility with the output of
+
+.BR "mdadm --examine --scan" .
+
+.TP
+.B spare-group=
+The value is a textual name for a group of arrays.  All arrays with
+the same
+.B spare-group
+name are considered to be part of the same group.  The significance of
+a group of arrays is that
+.B mdadm
+will, when monitoring the arrays, move a spare drive from one array in
+a group to another array in that group if the first array had a failed
+or missing drive but no spare.
+
+.TP
+.B auto=
+This option declares to
+.B mdadm
+that it should try to create the device file of the array if it
+doesn't already exist, or exists but with the wrong device number.
+
+The value of this option can be "yes" or "md" to indicate that a
+traditional, non-partitionable md array should be created, or "mdp",
+"part" or "partition" to indicate that a partitionable md array (only
+available in linux 2.6 and later) should be used.  This later set can
+also have a number appended to indicate how many partitions to create
+device files for, e.g.
+.BR auto=mdp5 .
+The default is 4.
+.RE
+
+.TP
+.B MAILADDR
+The
+.B mailaddr
+line gives an E-mail address that alerts should be
+sent to when
+.M mdadm
+is running in
+.B --monitor
+mode (and was given the
+.B --scan
+option).  There should only be one
+.B MAILADDR
+line and it should have only one address.
+
+
+.TP
+.B PROGRAM
+The
+.B program
+line gives the name of a program to be run when
+.B "mdadm --monitor"
+detects potentially interesting events on any of the arrays that it
+is monitoring.  This program gets run with two or three arguments, they
+being the Event, the md device, and possibly the related component
+device.
+
+There should only be one
+.B program
+line and it should be give only one program.
+
+.SH EXAMPLE
+DEVICE /dev/sd[bcdjkl]1
+.br
+DEVICE /dev/hda1 /dev/hdb1
+
+# /dev/md0 is known by it's UID.
+.br
+ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371
+.br
+# /dev/md1 contains all devices with a minor number of
+.br
+#   1 in the superblock.
+.br
+ARRAY /dev/md1 superminor=1
+.br
+# /dev/md2 is made from precisey these two devices
+.br
+ARRAY /dev/md2 devices=/dev/hda1,/dev/hda2
+
+# /dev/md4 and /dev/md5 are a spare-group and spares
+.br
+#  can be moved between them
+.br
+ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df
+.br
+           spare-group=group1
+.br
+ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977
+.br
+           spare-group=group1
+.br
+# /dev/md/home is created if need to be a partitionable md array
+.br
+# any spare device number is allocated.
+.br
+ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b
+.br
+           auto=part
+
+MAILADDR root@mydomain.tld
+.br
+PROGRAM /usr/sbin/handle-mdadm-events
+
 
 .SH SEE ALSO
-mdadm (8),
-md (4).
+.BR mdadm (8),
+.BR md (4).