Man pages update for policy framework

[thirdparty/mdadm.git] / mdadm.conf.5

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