.TP
.BR \-\-path=
-Only used with \-\-fail. Allows the failed device to be automatically replaced
-by a new device without metadata if it appears at specified path.
+Only used with \-\-fail. The 'path' given will be recorded so that if
+a new device appears at the same location it can be automatically
+added to the same array. This allows the failed device to be
+automatically replaced by a new device without metadata if it appears
+at specified path. This option is normally only set by a
+.I udev
+script.
.SH For Monitor mode:
.TP
.TP
.BR \-\-no\-sharing
-Allows to run monitoring without moving spares between arrays.
+This inhibits the functionality for moving spares between arrays.
Only one monitoring process started with
.B \-\-scan
-is allowed.
-Any subsequent call of
-.B mdadm \-F \-\-scan
-must also use
-.B \-\-no\-sharing
-option.
+but without this flag is allowed, otherwise the two could interfere
+with each other.
.SH ASSEMBLE MODE
.B \-\-scan
will cause the output to be less detailed and the format to be
suitable for inclusion in
-.BR /etc/mdadm.conf .
+.BR mdadm.conf .
The exit status of
.I mdadm
will normally be 0 unless
is given, then multiple devices that are components of the one array
are grouped together and reported in a single entry suitable
for inclusion in
-.BR /etc/mdadm.conf .
+.BR mdadm.conf .
Having
.B \-\-scan
If the spare group for a degraded array is not defined,
.I mdadm
will look at the rules of spare migration specified by POLICY lines in
-.B /etc/mdadm.conf
+.B mdadm.conf
and then follow similar steps as above if a matching spare is found.
.SH GROW MODE
Note that
.I mdadm
-will always add devices to an array which were previously working
-(active or spare) parts of that array. The support for automatic
+will normally only add devices to an array which were previously working
+(active or spare) parts of that array. The support for automatic
inclusion of a new drive as a spare in some array requires
a configuration through POLICY in config file.
.I mdadm
can reasonably determine that the array really is meant for this host,
either by a hostname in the metadata, or by the presence of the array
-in /etc/mdadm.conf, then it will leave off the suffix if possible.
+in
+.BR mdadm.conf ,
+then it will leave off the suffix if possible.
Also if the homehost is specified as
.B <ignore>
.I mdadm
.TP
.B POLICY
-Allows 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 array as well as the migration domains.
+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. Domain of an array is a union
-of domains of all devices in that array. A spare can be automatically
+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
To update hot plug configuration it is necessary to execute
.B mdadm \-\-udev\-rules
-command after changing config file
+command after changing the config file
-Key words used in
+Key words used in the
.I POLICY
-line and supported values:
+line and supported values are:
.RS 7
.TP
.B path=
file glob matching anything from
.B /dev/disk/by-path
+.B type=
+either
+.B disk
+or
+.BR part .
.TP
.B action=
include, re-add, spare, spare-same-slot, or force-spare
.I action
item determines the automatic behavior allowed for devices matching the
.I path
-in the same line. If a device matches several lines with different
+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.
allows adding a disk to an array if metadata on that disk matches that array
.TP
.B re-add
-will include device in the array if it appears to be a current member
+will include the device in the array if it appears to be a current member
or a member that was recently removed
.TP
.B spare
-as above and additionally: if the device is bare it will
-become a spare (for metadata the same line)
+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