[PATCH] Man pages update for policy framework

[PATCH] Man pages update for policy framework

[Przemyslaw Czarnowski]

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>
---
 mdadm.8.in   |   37 +++++++++++++++++++++--
 mdadm.conf.5 |   92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 124 insertions(+), 5 deletions(-)

diff --git a/mdadm.8.in b/mdadm.8.in
index ac87b47..f87578d 100644
--- 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,11 @@ first.
 If the removal succeeds but the adding fails, then it is added back to
 the original array.
 
+If the spare group for degraded array is not defined mdadm will look
+at the rules of spare migration specified by POLICY lines
+in /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 +2334,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 +2369,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 e677ba9..75a911f 100644
--- 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

Re: [PATCH] Man pages update for policy framework

[NeilBrown]

On Fri, 28 Jan 2011 18:29:57 +0100 Przemyslaw Czarnowski
<przemyslaw.hawrylewicz.czarnowski@intel.com> wrote:

> 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>
> ---
>  mdadm.8.in   |   37 +++++++++++++++++++++--
>  mdadm.conf.5 |   92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
>  2 files changed, 124 insertions(+), 5 deletions(-)

Applied, thanks.

NeilBrown

> 
> diff --git a/mdadm.8.in b/mdadm.8.in
> index ac87b47..f87578d 100644
> --- 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,11 @@ first.
>  If the removal succeeds but the adding fails, then it is added back to
>  the original array.
>  
> +If the spare group for degraded array is not defined mdadm will look
> +at the rules of spare migration specified by POLICY lines
> +in /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 +2334,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 +2369,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 e677ba9..75a911f 100644
> --- 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