Man pages update for policy framework

Includes description of POLICY line in /etc/mdadm.conf
and of changes in Monitor and Incremental related to autorebuild.

Signed-off-by: Anna Czarnowska <anna.czarnowska@intel.com>
Signed-off-by: Przemyslaw Czarnowski <przemyslaw.hawrylewicz.czarnowski@intel.com>
Signed-off-by: NeilBrown <neilb@suse.de>

diff --git a/mdadm.8.in b/mdadm.8.in
index ac87b47b6dac52fccbadac44afd500954107c72c..4b82fdcc3069381f76c17b25806bad03fb5bef00 100644 (file)
--- a/mdadm.8.in
+++ b/mdadm.8.in
@@ -1330,6 +1330,11 @@ The device name given should be a kernel device name such as "sda",
 not a name in
 .IR /dev .
 
+.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.
+
 .SH For Monitor mode:
 .TP
 .BR \-m ", " \-\-mail
@@ -1401,6 +1406,18 @@ alert for every array found at startup.  This alert gets mailed and
 passed to the alert program.  This can be used for testing that alert
 message do get through successfully.
 
+.TP
+.BR \-\-no\-sharing
+Allows to run monitoring without 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.
+
 .SH ASSEMBLE MODE
 
 .HP 12
@@ -1951,6 +1968,8 @@ As well as reporting events,
 may move a spare drive from one array to another if they are in the
 same
 .B spare-group
+or
+.B domain
 and if the destination array has a failed drive but no spares.
 
 If any devices are listed on the command line,
@@ -2057,6 +2076,8 @@ notices that an array is degraded when it first sees the array.
 .B MoveSpare
 A spare drive has been moved from one array in a
 .B spare-group
+or
+.B domain
 to another to allow a failed drive to be replaced.
 (syslog priority: Info)
 
@@ -2109,6 +2130,7 @@ For
 to move spares from one array to another, the different arrays need to
 be labeled with the same
 .B spare-group
+or the spares must be allowed to migrate through matching POLICY domains
 in the configuration file.  The
 .B spare-group
 name can be any string; it is only necessary that different spare
@@ -2125,6 +2147,12 @@ first.
 If the removal succeeds but the adding fails, then it is added back to
 the original array.
 
+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
+and then follow similar steps as above if a matching spare is found.
+
 .SH GROW MODE
 The GROW mode is used for changing the size or shape of an active
 array.
@@ -2307,9 +2335,10 @@ adds the device to the array and conditionally starts the array.
 
 Note that
 .I mdadm
-will only add devices to an array which were previously working
-(active or spare) parts of that array.  It does not currently support
-automatic inclusion of a new drive as a spare in some array.
+will always 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.
 
 The tests that
 .I mdadm
@@ -2341,7 +2370,8 @@ then only that style of metadata is accepted, otherwise
 .I mdadm
 finds any known version of metadata.  If no
 .I md
-metadata is found, the device is rejected.
+metadata is found, the device may be still added to an array
+as a spare if POLICY allows.
 
 .ig
 .IP +

diff --git a/mdadm.conf.5 b/mdadm.conf.5
index e677ba9ec4ddd65c0b2377f7455875407a35f79d..ea56b55612d09df1125351a9c10676d1e39d6214 100644 (file)
--- a/mdadm.conf.5
+++ b/mdadm.conf.5
@@ -418,6 +418,78 @@ The known metadata types are
 .BR ddf ,
 .BR imsm .
 
+.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.
+.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
+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 config file
+
+Key words used in
+.I POLICY
+line and supported values:
+
+.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 action=
+include, re-add, spare, spare-same-slot, or force-spare
+
+.P
+The
+.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
+.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 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)
+.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
@@ -456,7 +528,25 @@ ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977
 ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b
 .br
            auto=part
-
+.br
+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