Any word that beings with a hash sign (#) starts a comment and that
word together with the remainder of the line is ignored.
+Spaces can be included in a word using quotation characters. Either
+single quotes
+.RB ( ' )
+or double quotes (\fB"\fP)
+may be used. All the characters from one quotation character to
+next identical character are protected and will not be used to
+separate words to start new quoted strings. To include a single quote
+it must be between double quotes. To include a double quote it must
+be between single quotes.
+
Any line that starts with white space (space or tab) is treated as
though it were a continuation of the previous line.
Alternatively, a
.B device
-line can contain either of both of the words
+line can contain either or both of the words
.B containers
and
.BR partitions .
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
+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
+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"
.B \-\-scan
option). There should only be one
.B MAILADDR
-line and it should have only one address.
-
+line and it should have only one address. Any subsequent addresses
+are silently ignored.
.TP
.B MAILFROM
.B CREATE
The
.B create
-line gives default values to be used when creating arrays and device entries for
-arrays.
+line gives default values to be used when creating arrays, new members
+of arrays, and device entries for arrays.
These include:
.RS 4
Give
.B symlinks=no
to suppress this symlink creation.
+
+.TP
+.B names=yes
+Since Linux 2.6.29 it has been possible to create
+.B md
+devices with a name like
+.B md_home
+rather than just a number, like
+.BR md3 .
+.I mdadm
+will use the numeric alternative by default as other tools that interact
+with md arrays may expect only numbers.
+If
+.B names=yes
+is given in
+.I mdadm.conf
+then
+.I mdadm
+will use a name when appropriate.
+If
+.B names=no
+is given, then non-numeric
+.I md
+device names will not be used even if the default changes in a future
+release of
+.IR mdadm .
+
+.TP
+.B bbl=no
+By default,
+.I mdadm
+will reserve space for a bad block list (bbl) on all devices
+included in or added to any array that supports them. Setting
+.B bbl=no
+will prevent this, so newly added devices will not have a bad
+block log.
.RE
.TP
.B \-\-homehost=
option to mdadm. There should normally be only one other word on the line.
It should either be a host name, or one of the special words
-.B <system>
+.BR <system>,
+.B <none>
and
.BR <ignore> .
If
.B <system>
is given, then the
.BR gethostname ( 2 )
-systemcall is used to get the host name.
+systemcall is used to get the host name. This is the default.
If
.B <ignore>
used when creating arrays. This is the only case when there can be
more that one other word on the
.B HOMEHOST
-line.
+line. If there are other words, or other
+.B HOMEHOST
+lines, they are silently ignored.
+
+If
+.B <none>
+is given, then the default of using
+.BR gethostname ( 2 )
+is over-ridden and no homehost name is assumed.
When arrays are created, this host name will be stored in the
metadata. When arrays are assembled using auto-assembly, arrays which
.BR ddf ,
.BR imsm .
+.B AUTO
+should be given at most once. Subsequent lines are silently ignored.
+Thus an earlier config file in a config directory will over-ride
+the setting in a later config file.
+
+.TP
+.B POLICY
+This is used to specify what automatic behavior is allowed on devices
+newly appearing in the system and provides a way of marking spares that can
+be moved to other arrays as well as the migration domains.
+.I Domain
+can be defined through
+.I policy
+line by specifying a domain name for a number of paths from
+.BR /dev/disk/by-path/ .
+A device may belong to several domains. The domain of an array is a union
+of domains of all devices in that array. A spare can be automatically
+moved from one array to another if the set of the destination array's
+.I domains
+contains all the
+.I domains
+of the new disk or if both arrays have the same
+.IR spare-group .
+
+To update hot plug configuration it is necessary to execute
+.B mdadm \-\-udev\-rules
+command after changing the config file
+
+Key words used in the
+.I POLICY
+line and supported values are:
+
+.RS 7
+.TP
+.B domain=
+any arbitrary string
+.TP
+.B metadata=
+0.9 1.x ddf or imsm
+.TP
+.B path=
+file glob matching anything from
+.B /dev/disk/by-path
+.TP
+.B type=
+either
+.B disk
+or
+.BR part .
+.TP
+.B action=
+include, re-add, spare, spare-same-slot, or force-spare
+.TP
+.B auto=
+yes, no, or homehost.
+
+.P
+The
+.I action
+item determines the automatic behavior allowed for devices matching the
+.I path
+and
+.I type
+in the same line. If a device matches several lines with different
+.I actions
+then the most permissive will apply. The ordering of policy lines
+is irrelevant to the end result.
+.TP
+.B include
+allows adding a disk to an array if metadata on that disk matches that array
+.TP
+.B re\-add
+will include the device in the array if it appears to be a current member
+or a member that was recently removed and the array has a
+write-intent-bitmap to allow the
+.B re\-add
+functionality.
+.TP
+.B spare
+as above and additionally: if the device is bare it can
+become a spare if there is any array that it is a candidate for based
+on domains and metadata.
+.TP
+.B spare\-same\-slot
+as above and additionally if given slot was used by an array that went
+degraded recently and the device plugged in has no metadata then it will
+be automatically added to that array (or it's container)
+.TP
+.B force\-spare
+as above and the disk will become a spare in remaining cases
+.RE
+
.SH EXAMPLE
DEVICE /dev/sd[bcdjkl]1
.br
ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b
.br
auto=part
-
+.br
+# The name of this array contains a space.
+.br
+ARRAY /dev/md9 name='Data Storage'
+.sp
+POLICY domain=domain1 metadata=imsm path=pci-0000:00:1f.2-scsi-*
+.br
+ action=spare
+.br
+POLICY domain=domain1 metadata=imsm path=pci-0000:04:00.0-scsi-[01]*
+.br
+ action=include
+.br
+# One domain comprising of devices attached to specified paths is defined.
+.br
+# Bare device matching first path will be made an imsm spare on hot plug.
+.br
+# If more than one array is created on devices belonging to domain1 and
+.br
+# one of them becomes degraded, then any imsm spare matching any path for
+.br
+# given domain name can be migrated.
+.br
MAILADDR root@mydomain.tld
.br
PROGRAM /usr/sbin/handle\-mdadm\-events
.br
HOMEHOST <system>
.br
-AUTO +1.x homehost -all
+AUTO +1.x homehost \-all
.SH SEE ALSO
.BR mdadm (8),
.BR md (4).
-