Blame SOURCES/0006-mdadm-Respect-config-file-location-in-man.patch

c0f891
From e9dd5644843e2013a7dd1a8a5da2b9fa35837416 Mon Sep 17 00:00:00 2001
c0f891
From: Lukasz Florczak <lukasz.florczak@linux.intel.com>
c0f891
Date: Fri, 18 Mar 2022 09:26:04 +0100
37f2b0
Subject: [PATCH 06/83] mdadm: Respect config file location in man
c0f891
c0f891
Default config file location could differ depending on OS (e.g. Debian family).
c0f891
This patch takes default config file into consideration when creating mdadm.man
c0f891
file as well as mdadm.conf.man.
c0f891
c0f891
Rename mdadm.conf.5 to mdadm.conf.5.in. Now mdadm.conf.5 is generated automatically.
c0f891
c0f891
Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>
c0f891
Acked-by: Coly Li <colyli@suse.de>
c0f891
Signed-off-by: Jes Sorensen <jsorensen@fb.com>
c0f891
---
c0f891
 .gitignore      |   1 +
c0f891
 Makefile        |   7 +-
c0f891
 mdadm.8.in      |  16 +-
c0f891
 mdadm.conf.5    | 706 ------------------------------------------------
c0f891
 mdadm.conf.5.in | 706 ++++++++++++++++++++++++++++++++++++++++++++++++
c0f891
 5 files changed, 721 insertions(+), 715 deletions(-)
c0f891
 delete mode 100644 mdadm.conf.5
c0f891
 create mode 100644 mdadm.conf.5.in
c0f891
c0f891
diff --git a/.gitignore b/.gitignore
c0f891
index 217fe76d..8d791c6f 100644
c0f891
--- a/.gitignore
c0f891
+++ b/.gitignore
c0f891
@@ -3,6 +3,7 @@
c0f891
 /*-stamp
c0f891
 /mdadm
c0f891
 /mdadm.8
c0f891
+/mdadm.conf.5
c0f891
 /mdadm.udeb
c0f891
 /mdassemble
c0f891
 /mdmon
c0f891
diff --git a/Makefile b/Makefile
c0f891
index 2a51d813..bf126033 100644
c0f891
--- a/Makefile
c0f891
+++ b/Makefile
c0f891
@@ -227,7 +227,12 @@ raid6check : raid6check.o mdadm.h $(CHECK_OBJS)
c0f891
 
c0f891
 mdadm.8 : mdadm.8.in
c0f891
 	sed -e 's/{DEFAULT_METADATA}/$(DEFAULT_METADATA)/g' \
c0f891
-	-e 's,{MAP_PATH},$(MAP_PATH),g'  mdadm.8.in > mdadm.8
c0f891
+	-e 's,{MAP_PATH},$(MAP_PATH),g' -e 's,{CONFFILE},$(CONFFILE),g' \
c0f891
+	-e 's,{CONFFILE2},$(CONFFILE2),g'  mdadm.8.in > mdadm.8
c0f891
+
c0f891
+mdadm.conf.5 : mdadm.conf.5.in
c0f891
+	sed -e 's,{CONFFILE},$(CONFFILE),g' \
c0f891
+	-e 's,{CONFFILE2},$(CONFFILE2),g'  mdadm.conf.5.in > mdadm.conf.5
c0f891
 
c0f891
 mdadm.man : mdadm.8
c0f891
 	man -l mdadm.8 > mdadm.man
c0f891
diff --git a/mdadm.8.in b/mdadm.8.in
c0f891
index e2a42425..8b21ffd4 100644
c0f891
--- a/mdadm.8.in
c0f891
+++ b/mdadm.8.in
c0f891
@@ -267,13 +267,13 @@ the exact meaning of this option in different contexts.
c0f891
 .TP
c0f891
 .BR \-c ", " \-\-config=
c0f891
 Specify the config file or directory.  Default is to use
c0f891
-.B /etc/mdadm.conf
c0f891
+.B {CONFFILE}
c0f891
 and
c0f891
-.BR /etc/mdadm.conf.d ,
c0f891
+.BR {CONFFILE}.d ,
c0f891
 or if those are missing then
c0f891
-.B /etc/mdadm/mdadm.conf
c0f891
+.B {CONFFILE2}
c0f891
 and
c0f891
-.BR /etc/mdadm/mdadm.conf.d .
c0f891
+.BR {CONFFILE2}.d .
c0f891
 If the config file given is
c0f891
 .B "partitions"
c0f891
 then nothing will be read, but
c0f891
@@ -2014,9 +2014,9 @@ The config file is only used if explicitly named with
c0f891
 or requested with (a possibly implicit)
c0f891
 .BR \-\-scan .
c0f891
 In the later case,
c0f891
-.B /etc/mdadm.conf
c0f891
+.B {CONFFILE}
c0f891
 or
c0f891
-.B /etc/mdadm/mdadm.conf
c0f891
+.B {CONFFILE2}
c0f891
 is used.
c0f891
 
c0f891
 If
c0f891
@@ -3344,7 +3344,7 @@ uses this to find arrays when
c0f891
 is given in Misc mode, and to monitor array reconstruction
c0f891
 on Monitor mode.
c0f891
 
c0f891
-.SS /etc/mdadm.conf
c0f891
+.SS {CONFFILE} (or {CONFFILE2})
c0f891
 
c0f891
 The config file lists which devices may be scanned to see if
c0f891
 they contain MD super block, and gives identifying information
c0f891
@@ -3352,7 +3352,7 @@ they contain MD super block, and gives identifying information
c0f891
 .BR mdadm.conf (5)
c0f891
 for more details.
c0f891
 
c0f891
-.SS /etc/mdadm.conf.d
c0f891
+.SS {CONFFILE}.d (or {CONFFILE2}.d)
c0f891
 
c0f891
 A directory containing configuration files which are read in lexical
c0f891
 order.
c0f891
diff --git a/mdadm.conf.5 b/mdadm.conf.5
c0f891
deleted file mode 100644
c0f891
index 74a21c5f..00000000
c0f891
--- a/mdadm.conf.5
c0f891
+++ /dev/null
c0f891
@@ -1,706 +0,0 @@
c0f891
-.\" Copyright Neil Brown and others.
c0f891
-.\"   This program is free software; you can redistribute it and/or modify
c0f891
-.\"   it under the terms of the GNU General Public License as published by
c0f891
-.\"   the Free Software Foundation; either version 2 of the License, or
c0f891
-.\"   (at your option) any later version.
c0f891
-.\" See file COPYING in distribution for details.
c0f891
-.TH MDADM.CONF 5
c0f891
-.SH NAME
c0f891
-mdadm.conf \- configuration for management of Software RAID with mdadm
c0f891
-.SH SYNOPSIS
c0f891
-/etc/mdadm.conf
c0f891
-.SH DESCRIPTION
c0f891
-.PP
c0f891
-.I mdadm
c0f891
-is a tool for creating, managing, and monitoring RAID devices using the
c0f891
-.B md
c0f891
-driver in Linux.
c0f891
-.PP
c0f891
-Some common tasks, such as assembling all arrays, can be simplified
c0f891
-by describing the devices and arrays in this configuration file.
c0f891
-
c0f891
-.SS SYNTAX
c0f891
-The file should be seen as a collection of words separated by white
c0f891
-space (space, tab, or newline).
c0f891
-Any word that beings with a hash sign (#) starts a comment and that
c0f891
-word together with the remainder of the line is ignored.
c0f891
-
c0f891
-Spaces can be included in a word using quotation characters.  Either
c0f891
-single quotes
c0f891
-.RB ( ' )
c0f891
-or double quotes (\fB"\fP)
c0f891
-may be used.  All the characters from one quotation character to
c0f891
-next identical character are protected and will not be used to
c0f891
-separate words to start new quoted strings.  To include a single quote
c0f891
-it must be between double quotes.  To include a double quote it must
c0f891
-be between single quotes.
c0f891
-
c0f891
-Any line that starts with white space (space or tab) is treated as
c0f891
-though it were a continuation of the previous line.
c0f891
-
c0f891
-Empty lines are ignored, but otherwise each (non continuation) line
c0f891
-must start with a keyword as listed below.  The keywords are case
c0f891
-insensitive and can be abbreviated to 3 characters.
c0f891
-
c0f891
-The keywords are:
c0f891
-.TP
c0f891
-.B DEVICE
c0f891
-A
c0f891
-.B device
c0f891
-line lists the devices (whole devices or partitions) that might contain
c0f891
-a component of an MD array.  When looking for the components of an
c0f891
-array,
c0f891
-.I mdadm
c0f891
-will scan these devices (or any devices listed on the command line).
c0f891
-
c0f891
-The
c0f891
-.B device
c0f891
-line may contain a number of different devices (separated by spaces)
c0f891
-and each device name can contain wild cards as defined by
c0f891
-.BR glob (7).
c0f891
-
c0f891
-Also, there may be several device lines present in the file.
c0f891
-
c0f891
-Alternatively, a
c0f891
-.B device
c0f891
-line can contain either or both of the  words
c0f891
-.B containers
c0f891
-and
c0f891
-.BR partitions .
c0f891
-The word
c0f891
-.B containers
c0f891
-will cause
c0f891
-.I mdadm
c0f891
-to look for assembled CONTAINER arrays and included them as a source
c0f891
-for assembling further arrays.
c0f891
-
c0f891
-The word
c0f891
-.I partitions
c0f891
-will cause
c0f891
-.I mdadm
c0f891
-to read
c0f891
-.I /proc/partitions
c0f891
-and include all devices and partitions found therein.
c0f891
-.I mdadm
c0f891
-does not use the names from
c0f891
-.I /proc/partitions
c0f891
-but only the major and minor device numbers.  It scans
c0f891
-.I /dev
c0f891
-to find the name that matches the numbers.
c0f891
-
c0f891
-If no DEVICE line is present, then "DEVICE partitions containers" is assumed.
c0f891
-
c0f891
-For example:
c0f891
-.IP
c0f891
-DEVICE /dev/hda* /dev/hdc*
c0f891
-.br
c0f891
-DEV    /dev/sd*
c0f891
-.br
c0f891
-DEVICE /dev/disk/by-path/pci*
c0f891
-.br
c0f891
-DEVICE partitions
c0f891
-
c0f891
-.TP
c0f891
-.B ARRAY
c0f891
-The ARRAY lines identify actual arrays.  The second word on the line
c0f891
-may be the name of the device where the array is normally
c0f891
-assembled, such as
c0f891
-.B /dev/md1
c0f891
-or
c0f891
-.BR /dev/md/backup .
c0f891
-If the name does not start with a slash
c0f891
-.RB (' / '),
c0f891
-it is treated as being in
c0f891
-.BR /dev/md/ .
c0f891
-Alternately the word
c0f891
-.B <ignore>
c0f891
-(complete with angle brackets) can be given in which case any array
c0f891
-which matches the rest of the line will never be automatically assembled.
c0f891
-If no device name is given,
c0f891
-.I mdadm
c0f891
-will use various heuristics to determine an appropriate name.
c0f891
-
c0f891
-Subsequent words identify the array, or identify the array as a member
c0f891
-of a group. If multiple identities are given,
c0f891
-then a component device must match ALL identities to be considered a
c0f891
-match.  Each identity word has a tag, and equals sign, and some value.
c0f891
-The tags are:
c0f891
-.RS 4
c0f891
-.TP
c0f891
-.B uuid=
c0f891
-The value should be a 128 bit uuid in hexadecimal, with punctuation
c0f891
-interspersed if desired.  This must match the uuid stored in the
c0f891
-superblock.
c0f891
-.TP
c0f891
-.B name=
c0f891
-The value should be a simple textual name as was given to
c0f891
-.I mdadm
c0f891
-when the array was created.  This must match the name stored in the
c0f891
-superblock on a device for that device to be included in the array.
c0f891
-Not all superblock formats support names.
c0f891
-.TP
c0f891
-.B super\-minor=
c0f891
-The value is an integer which indicates the minor number that was
c0f891
-stored in the superblock when the array was created. When an array is
c0f891
-created as /dev/mdX, then the minor number X is stored.
c0f891
-.TP
c0f891
-.B devices=
c0f891
-The value is a comma separated list of device names or device name
c0f891
-patterns.
c0f891
-Only devices with names which match one entry in the list will be used
c0f891
-to assemble the array.  Note that the devices
c0f891
-listed there must also be listed on a DEVICE line.
c0f891
-.TP
c0f891
-.B level=
c0f891
-The value is a RAID level.  This is not normally used to
c0f891
-identify an array, but is supported so that the output of
c0f891
-
c0f891
-.B "mdadm \-\-examine \-\-scan"
c0f891
-
c0f891
-can be use directly in the configuration file.
c0f891
-.TP
c0f891
-.B num\-devices=
c0f891
-The value is the number of devices in a complete active array.  As with
c0f891
-.B level=
c0f891
-this is mainly for compatibility with the output of
c0f891
-
c0f891
-.BR "mdadm \-\-examine \-\-scan" .
c0f891
-
c0f891
-.TP
c0f891
-.B spares=
c0f891
-The value is a number of spare devices to expect the array to have.
c0f891
-The sole use of this keyword and value is as follows:
c0f891
-.B mdadm \-\-monitor
c0f891
-will report an array if it is found to have fewer than this number of
c0f891
-spares when
c0f891
-.B \-\-monitor
c0f891
-starts or when
c0f891
-.B \-\-oneshot
c0f891
-is used.
c0f891
-
c0f891
-.TP
c0f891
-.B spare\-group=
c0f891
-The value is a textual name for a group of arrays.  All arrays with
c0f891
-the same
c0f891
-.B spare\-group
c0f891
-name are considered to be part of the same group.  The significance of
c0f891
-a group of arrays is that
c0f891
-.I mdadm
c0f891
-will, when monitoring the arrays, move a spare drive from one array in
c0f891
-a group to another array in that group if the first array had a failed
c0f891
-or missing drive but no spare.
c0f891
-
c0f891
-.TP
c0f891
-.B auto=
c0f891
-This option is rarely needed with mdadm-3.0, particularly if use with
c0f891
-the Linux kernel v2.6.28 or later.
c0f891
-It tells
c0f891
-.I mdadm
c0f891
-whether to use partitionable array or non-partitionable arrays and,
c0f891
-in the absence of
c0f891
-.IR udev ,
c0f891
-how many partition devices to create.  From 2.6.28 all md array
c0f891
-devices are partitionable, hence this option is not needed.
c0f891
-
c0f891
-The value of this option can be "yes" or "md" to indicate that a
c0f891
-traditional, non-partitionable md array should be created, or "mdp",
c0f891
-"part" or "partition" to indicate that a partitionable md array (only
c0f891
-available in linux 2.6 and later) should be used.  This later set can
c0f891
-also have a number appended to indicate how many partitions to create
c0f891
-device files for, e.g.
c0f891
-.BR auto=mdp5 .
c0f891
-The default is 4.
c0f891
-
c0f891
-.TP
c0f891
-.B bitmap=
c0f891
-The option specifies a file in which a write-intent bitmap should be
c0f891
-found.  When assembling the array,
c0f891
-.I mdadm
c0f891
-will provide this file to the
c0f891
-.B md
c0f891
-driver as the bitmap file.  This has the same function as the
c0f891
-.B \-\-bitmap\-file
c0f891
-option to
c0f891
-.BR \-\-assemble .
c0f891
-
c0f891
-.TP
c0f891
-.B metadata=
c0f891
-Specify the metadata format that the array has.  This is mainly
c0f891
-recognised for comparability with the output of
c0f891
-.BR "mdadm \-Es" .
c0f891
-
c0f891
-.TP
c0f891
-.B container=
c0f891
-Specify that this array is a member array of some container.  The
c0f891
-value given can be either a path name in /dev, or a UUID of the
c0f891
-container array.
c0f891
-
c0f891
-.TP
c0f891
-.B member=
c0f891
-Specify that this array is a member array of some container.  Each
c0f891
-type of container has some way to enumerate member arrays, often a
c0f891
-simple sequence number.  The value identifies which member of a
c0f891
-container the array is.  It will usually accompany a "container=" word.
c0f891
-.RE
c0f891
-
c0f891
-.TP
c0f891
-.B MAILADDR
c0f891
-The
c0f891
-.B mailaddr
c0f891
-line gives an E-mail address that alerts should be
c0f891
-sent to when
c0f891
-.I mdadm
c0f891
-is running in
c0f891
-.B \-\-monitor
c0f891
-mode (and was given the
c0f891
-.B \-\-scan
c0f891
-option).  There should only be one
c0f891
-.B MAILADDR
c0f891
-line and it should have only one address.  Any subsequent addresses
c0f891
-are silently ignored.
c0f891
-
c0f891
-.TP
c0f891
-.B MAILFROM
c0f891
-The
c0f891
-.B mailfrom
c0f891
-line (which can only be abbreviated to at least 5 characters) gives an
c0f891
-address to appear in the "From" address for alert mails.  This can be
c0f891
-useful if you want to explicitly set a domain, as the default from
c0f891
-address is "root" with no domain.  All words on this line are
c0f891
-catenated with spaces to form the address.
c0f891
-
c0f891
-Note that this value cannot be set via the
c0f891
-.I mdadm
c0f891
-commandline.  It is only settable via the config file.
c0f891
-
c0f891
-.TP
c0f891
-.B PROGRAM
c0f891
-The
c0f891
-.B program
c0f891
-line gives the name of a program to be run when
c0f891
-.B "mdadm \-\-monitor"
c0f891
-detects potentially interesting events on any of the arrays that it
c0f891
-is monitoring.  This program gets run with two or three arguments, they
c0f891
-being the Event, the md device, and possibly the related component
c0f891
-device.
c0f891
-
c0f891
-There should only be one
c0f891
-.B program
c0f891
-line and it should be give only one program.
c0f891
-
c0f891
-
c0f891
-.TP
c0f891
-.B CREATE
c0f891
-The
c0f891
-.B create
c0f891
-line gives default values to be used when creating arrays, new members
c0f891
-of arrays, and device entries for arrays.
c0f891
-These include:
c0f891
-
c0f891
-.RS 4
c0f891
-.TP
c0f891
-.B owner=
c0f891
-.TP
c0f891
-.B group=
c0f891
-These can give user/group ids or names to use instead of system
c0f891
-defaults (root/wheel or root/disk).
c0f891
-.TP
c0f891
-.B mode=
c0f891
-An octal file mode such as 0660 can be given to override the default
c0f891
-of 0600.
c0f891
-.TP
c0f891
-.B auto=
c0f891
-This corresponds to the
c0f891
-.B \-\-auto
c0f891
-flag to mdadm.  Give
c0f891
-.BR yes ,
c0f891
-.BR md ,
c0f891
-.BR mdp ,
c0f891
-.B part
c0f891
-\(em possibly followed by a number of partitions \(em to indicate how
c0f891
-missing device entries should be created.
c0f891
-
c0f891
-.TP
c0f891
-.B metadata=
c0f891
-The name of the metadata format to use if none is explicitly given.
c0f891
-This can be useful to impose a system-wide default of version-1 superblocks.
c0f891
-
c0f891
-.TP
c0f891
-.B symlinks=no
c0f891
-Normally when creating devices in
c0f891
-.B /dev/md/
c0f891
-.I mdadm
c0f891
-will create a matching symlink from
c0f891
-.B /dev/
c0f891
-with a name starting
c0f891
-.B md
c0f891
-or
c0f891
-.BR md_ .
c0f891
-Give
c0f891
-.B symlinks=no
c0f891
-to suppress this symlink creation.
c0f891
-
c0f891
-.TP
c0f891
-.B names=yes
c0f891
-Since Linux 2.6.29 it has been possible to create
c0f891
-.B md
c0f891
-devices with a name like
c0f891
-.B md_home
c0f891
-rather than just a number, like
c0f891
-.BR md3 .
c0f891
-.I mdadm
c0f891
-will use the numeric alternative by default as other tools that interact
c0f891
-with md arrays may expect only numbers.
c0f891
-If
c0f891
-.B names=yes
c0f891
-is given in
c0f891
-.I mdadm.conf
c0f891
-then
c0f891
-.I mdadm
c0f891
-will use a name when appropriate.
c0f891
-If
c0f891
-.B names=no
c0f891
-is given, then non-numeric
c0f891
-.I md
c0f891
-device names will not be used even if the default changes in a future
c0f891
-release of
c0f891
-.IR mdadm .
c0f891
-
c0f891
-.TP
c0f891
-.B bbl=no
c0f891
-By default,
c0f891
-.I mdadm
c0f891
-will reserve space for a bad block list (bbl) on all devices
c0f891
-included in or added to any array that supports them.  Setting
c0f891
-.B bbl=no
c0f891
-will prevent this, so newly added devices will not have a bad
c0f891
-block log.
c0f891
-.RE
c0f891
-
c0f891
-.TP
c0f891
-.B HOMEHOST
c0f891
-The
c0f891
-.B homehost
c0f891
-line gives a default value for the
c0f891
-.B \-\-homehost=
c0f891
-option to mdadm.  There should normally be only one other word on the line.
c0f891
-It should either be a host name, or one of the special words
c0f891
-.BR <system>,
c0f891
-.B <none>
c0f891
-and
c0f891
-.BR <ignore> .
c0f891
-If
c0f891
-.B <system>
c0f891
-is given, then the
c0f891
-.BR gethostname ( 2 )
c0f891
-systemcall is used to get the host name.  This is the default.
c0f891
-
c0f891
-If
c0f891
-.B <ignore>
c0f891
-is given, then a flag is set so that when arrays are being
c0f891
-auto-assembled the checking of the recorded
c0f891
-.I homehost
c0f891
-is disabled.
c0f891
-If
c0f891
-.B <ignore>
c0f891
-is given it is also possible to give an explicit name which will be
c0f891
-used when creating arrays.  This is the only case when there can be
c0f891
-more that one other word on the
c0f891
-.B HOMEHOST
c0f891
-line.  If there are other words, or other
c0f891
-.B HOMEHOST
c0f891
-lines, they are silently ignored.
c0f891
-
c0f891
-If
c0f891
-.B <none>
c0f891
-is given, then the default of using
c0f891
-.BR gethostname ( 2 )
c0f891
-is over-ridden and no homehost name is assumed.
c0f891
-
c0f891
-When arrays are created, this host name will be stored in the
c0f891
-metadata.  When arrays are assembled using auto-assembly, arrays which
c0f891
-do not record the correct homehost name in their metadata will be
c0f891
-assembled using a "foreign" name.  A "foreign" name alway ends with a
c0f891
-digit string preceded by an underscore to differentiate it
c0f891
-from any possible local name. e.g.
c0f891
-.B /dev/md/1_1
c0f891
-or
c0f891
-.BR /dev/md/home_0 .
c0f891
-.TP
c0f891
-.B AUTO
c0f891
-A list of names of metadata format can be given, each preceded by a
c0f891
-plus or minus sign.  Also the word
c0f891
-.I homehost
c0f891
-is allowed as is
c0f891
-.I all
c0f891
-preceded by plus or minus sign.
c0f891
-.I all
c0f891
-is usually last.
c0f891
-
c0f891
-When
c0f891
-.I mdadm
c0f891
-is auto-assembling an array, either via
c0f891
-.I \-\-assemble
c0f891
-or
c0f891
-.I \-\-incremental
c0f891
-and it finds metadata of a given type, it checks that metadata type
c0f891
-against those listed in this line.  The first match wins, where
c0f891
-.I all
c0f891
-matches anything.
c0f891
-If a match is found that was preceded by a plus sign, the auto
c0f891
-assembly is allowed.  If the match was preceded by a minus sign, the
c0f891
-auto assembly is disallowed.  If no match is found, the auto assembly
c0f891
-is allowed.
c0f891
-
c0f891
-If the metadata indicates that the array was created for
c0f891
-.I this
c0f891
-host, and the word
c0f891
-.I homehost
c0f891
-appears before any other match, then the array is treated as a valid
c0f891
-candidate for auto-assembly.
c0f891
-
c0f891
-This can be used to disable all auto-assembly (so that only arrays
c0f891
-explicitly listed in mdadm.conf or on the command line are assembled),
c0f891
-or to disable assembly of certain metadata types which might be
c0f891
-handled by other software.  It can also be used to disable assembly of
c0f891
-all foreign arrays - normally such arrays are assembled but given a
c0f891
-non-deterministic name in
c0f891
-.BR /dev/md/ .
c0f891
-
c0f891
-The known metadata types are
c0f891
-.BR 0.90 ,
c0f891
-.BR 1.x ,
c0f891
-.BR ddf ,
c0f891
-.BR imsm .
c0f891
-
c0f891
-.B AUTO
c0f891
-should be given at most once.  Subsequent lines are silently ignored.
c0f891
-Thus an earlier config file in a config directory will over-ride
c0f891
-the setting in a later config file.
c0f891
-
c0f891
-.TP
c0f891
-.B POLICY
c0f891
-This is used to specify what automatic behavior is allowed on devices
c0f891
-newly appearing in the system and provides a way of marking spares that can
c0f891
-be moved to other arrays as well as the migration domains.
c0f891
-.I Domain
c0f891
-can be defined through
c0f891
-.I policy
c0f891
-line by specifying a domain name for a number of paths from
c0f891
-.BR /dev/disk/by-path/ .
c0f891
-A device may belong to several domains. The domain of an array is a union
c0f891
-of domains of all devices in that array.  A spare can be automatically
c0f891
-moved from one array to another if the set of the destination array's
c0f891
-.I domains
c0f891
-contains all the
c0f891
-.I domains
c0f891
-of the new disk or if both arrays have the same
c0f891
-.IR spare-group .
c0f891
-
c0f891
-To update hot plug configuration it is necessary to execute
c0f891
-.B mdadm \-\-udev\-rules
c0f891
-command after changing the config file
c0f891
-
c0f891
-Keywords used in the
c0f891
-.I POLICY
c0f891
-line and supported values are:
c0f891
-
c0f891
-.RS 4
c0f891
-.TP
c0f891
-.B domain=
c0f891
-any arbitrary string
c0f891
-.TP
c0f891
-.B metadata=
c0f891
-0.9 1.x ddf or imsm
c0f891
-.TP
c0f891
-.B path=
c0f891
-file glob matching anything from
c0f891
-.B /dev/disk/by-path
c0f891
-.TP
c0f891
-.B type=
c0f891
-either
c0f891
-.B disk
c0f891
-or
c0f891
-.BR part .
c0f891
-.TP
c0f891
-.B action=
c0f891
-include, re-add, spare, spare-same-slot, or force-spare
c0f891
-.TP
c0f891
-.B auto=
c0f891
-yes, no, or homehost.
c0f891
-
c0f891
-.P
c0f891
-The
c0f891
-.I action
c0f891
-item determines the automatic behavior allowed for devices matching the
c0f891
-.I path
c0f891
-and
c0f891
-.I type
c0f891
-in the same line.  If a device matches several lines with different
c0f891
-.I  actions
c0f891
-then the most permissive will apply. The ordering of policy lines
c0f891
-is irrelevant to the end result.
c0f891
-.TP
c0f891
-.B include
c0f891
-allows adding a disk to an array if metadata on that disk matches that array
c0f891
-.TP
c0f891
-.B re\-add
c0f891
-will include the device in the array if it appears to be a current member
c0f891
-or a member that was recently removed and the array has a
c0f891
-write-intent-bitmap to allow the
c0f891
-.B re\-add
c0f891
-functionality.
c0f891
-.TP
c0f891
-.B spare
c0f891
-as above and additionally: if the device is bare it can
c0f891
-become a spare if there is any array that it is a candidate for based
c0f891
-on domains and metadata.
c0f891
-.TP
c0f891
-.B spare\-same\-slot
c0f891
-as above and additionally if given slot was used by an array that went
c0f891
-degraded recently and the device plugged in has no metadata then it will
c0f891
-be automatically added to that array (or it's container)
c0f891
-.TP
c0f891
-.B force\-spare
c0f891
-as above and the disk will become a spare in remaining cases
c0f891
-.RE
c0f891
-
c0f891
-.TP
c0f891
-.B PART-POLICY
c0f891
-This is similar to
c0f891
-.B POLICY
c0f891
-and accepts the same keyword assignments.  It allows a consistent set
c0f891
-of policies to applied to each of the partitions of a device.
c0f891
-
c0f891
-A
c0f891
-.B PART-POLICY
c0f891
-line should set
c0f891
-.I type=disk
c0f891
-and identify the path to one or more disk devices.  Each partition on
c0f891
-these disks will be treated according to the
c0f891
-.I action=
c0f891
-setting  from this line.  If a
c0f891
-.I domain
c0f891
-is set in the line, then the domain associated with each patition will
c0f891
-be based on the domain, but with
c0f891
-.RB \(dq -part N\(dq
c0f891
-appended, when N is the partition number for the partition that was
c0f891
-found.
c0f891
-
c0f891
-.TP
c0f891
-.B SYSFS
c0f891
-The
c0f891
-.B SYSFS
c0f891
-line lists custom values of MD device's sysfs attributes which will be
c0f891
-stored in sysfs after the array is assembled. Multiple lines are allowed and each
c0f891
-line has to contain the uuid or the name of the device to which it relates.
c0f891
-.RS 4
c0f891
-.TP
c0f891
-.B uuid=
c0f891
-hexadecimal identifier of MD device. This has to match the uuid stored in the
c0f891
-superblock.
c0f891
-.TP
c0f891
-.B name=
c0f891
-name of the MD device as was given to
c0f891
-.I mdadm
c0f891
-when the array was created. It will be ignored if
c0f891
-.B uuid
c0f891
-is not empty.
c0f891
-.RE
c0f891
-
c0f891
-.TP
c0f891
-.B MONITORDELAY
c0f891
-The
c0f891
-.B monitordelay
c0f891
-line gives a delay in seconds
c0f891
-.I mdadm
c0f891
-shall wait before pooling md arrays
c0f891
-when
c0f891
-.I mdadm
c0f891
-is running in
c0f891
-.B \-\-monitor
c0f891
-mode.
c0f891
-.B \-d/\-\-delay
c0f891
-command line argument takes precedence over the config file
c0f891
-
c0f891
-.SH EXAMPLE
c0f891
-DEVICE /dev/sd[bcdjkl]1
c0f891
-.br
c0f891
-DEVICE /dev/hda1 /dev/hdb1
c0f891
-
c0f891
-# /dev/md0 is known by its UUID.
c0f891
-.br
c0f891
-ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371
c0f891
-.br
c0f891
-# /dev/md1 contains all devices with a minor number of
c0f891
-.br
c0f891
-#   1 in the superblock.
c0f891
-.br
c0f891
-ARRAY /dev/md1 superminor=1
c0f891
-.br
c0f891
-# /dev/md2 is made from precisely these two devices
c0f891
-.br
c0f891
-ARRAY /dev/md2 devices=/dev/hda1,/dev/hdb1
c0f891
-
c0f891
-# /dev/md4 and /dev/md5 are a spare-group and spares
c0f891
-.br
c0f891
-#  can be moved between them
c0f891
-.br
c0f891
-ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df
c0f891
-.br
c0f891
-           spare\-group=group1
c0f891
-.br
c0f891
-ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977
c0f891
-.br
c0f891
-           spare\-group=group1
c0f891
-.br
c0f891
-# /dev/md/home is created if need to be a partitionable md array
c0f891
-.br
c0f891
-# any spare device number is allocated.
c0f891
-.br
c0f891
-ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b
c0f891
-.br
c0f891
-           auto=part
c0f891
-.br
c0f891
-# The name of this array contains a space.
c0f891
-.br
c0f891
-ARRAY /dev/md9 name='Data Storage'
c0f891
-.sp
c0f891
-POLICY domain=domain1 metadata=imsm path=pci-0000:00:1f.2-scsi-*
c0f891
-.br
c0f891
-           action=spare
c0f891
-.br
c0f891
-POLICY domain=domain1 metadata=imsm path=pci-0000:04:00.0-scsi-[01]*
c0f891
-.br
c0f891
-           action=include
c0f891
-.br
c0f891
-# One domain comprising of devices attached to specified paths is defined.
c0f891
-.br
c0f891
-# Bare device matching first path will be made an imsm spare on hot plug.
c0f891
-.br
c0f891
-# If more than one array is created on devices belonging to domain1 and
c0f891
-.br
c0f891
-# one of them becomes degraded, then any imsm spare matching any path for
c0f891
-.br
c0f891
-# given domain name can be migrated.
c0f891
-.br
c0f891
-MAILADDR root@mydomain.tld
c0f891
-.br
c0f891
-PROGRAM /usr/sbin/handle\-mdadm\-events
c0f891
-.br
c0f891
-CREATE group=system mode=0640 auto=part\-8
c0f891
-.br
c0f891
-HOMEHOST <system>
c0f891
-.br
c0f891
-AUTO +1.x homehost \-all
c0f891
-.br
c0f891
-SYSFS name=/dev/md/raid5 group_thread_cnt=4 sync_speed_max=1000000
c0f891
-.br
c0f891
-SYSFS uuid=bead5eb6:31c17a27:da120ba2:7dfda40d group_thread_cnt=4
c0f891
-sync_speed_max=1000000
c0f891
-.br
c0f891
-MONITORDELAY 60
c0f891
-
c0f891
-.SH SEE ALSO
c0f891
-.BR mdadm (8),
c0f891
-.BR md (4).
c0f891
diff --git a/mdadm.conf.5.in b/mdadm.conf.5.in
c0f891
new file mode 100644
c0f891
index 00000000..83edd008
c0f891
--- /dev/null
c0f891
+++ b/mdadm.conf.5.in
c0f891
@@ -0,0 +1,706 @@
c0f891
+.\" Copyright Neil Brown and others.
c0f891
+.\"   This program is free software; you can redistribute it and/or modify
c0f891
+.\"   it under the terms of the GNU General Public License as published by
c0f891
+.\"   the Free Software Foundation; either version 2 of the License, or
c0f891
+.\"   (at your option) any later version.
c0f891
+.\" See file COPYING in distribution for details.
c0f891
+.TH MDADM.CONF 5
c0f891
+.SH NAME
c0f891
+mdadm.conf \- configuration for management of Software RAID with mdadm
c0f891
+.SH SYNOPSIS
c0f891
+{CONFFILE}
c0f891
+.SH DESCRIPTION
c0f891
+.PP
c0f891
+.I mdadm
c0f891
+is a tool for creating, managing, and monitoring RAID devices using the
c0f891
+.B md
c0f891
+driver in Linux.
c0f891
+.PP
c0f891
+Some common tasks, such as assembling all arrays, can be simplified
c0f891
+by describing the devices and arrays in this configuration file.
c0f891
+
c0f891
+.SS SYNTAX
c0f891
+The file should be seen as a collection of words separated by white
c0f891
+space (space, tab, or newline).
c0f891
+Any word that beings with a hash sign (#) starts a comment and that
c0f891
+word together with the remainder of the line is ignored.
c0f891
+
c0f891
+Spaces can be included in a word using quotation characters.  Either
c0f891
+single quotes
c0f891
+.RB ( ' )
c0f891
+or double quotes (\fB"\fP)
c0f891
+may be used.  All the characters from one quotation character to
c0f891
+next identical character are protected and will not be used to
c0f891
+separate words to start new quoted strings.  To include a single quote
c0f891
+it must be between double quotes.  To include a double quote it must
c0f891
+be between single quotes.
c0f891
+
c0f891
+Any line that starts with white space (space or tab) is treated as
c0f891
+though it were a continuation of the previous line.
c0f891
+
c0f891
+Empty lines are ignored, but otherwise each (non continuation) line
c0f891
+must start with a keyword as listed below.  The keywords are case
c0f891
+insensitive and can be abbreviated to 3 characters.
c0f891
+
c0f891
+The keywords are:
c0f891
+.TP
c0f891
+.B DEVICE
c0f891
+A
c0f891
+.B device
c0f891
+line lists the devices (whole devices or partitions) that might contain
c0f891
+a component of an MD array.  When looking for the components of an
c0f891
+array,
c0f891
+.I mdadm
c0f891
+will scan these devices (or any devices listed on the command line).
c0f891
+
c0f891
+The
c0f891
+.B device
c0f891
+line may contain a number of different devices (separated by spaces)
c0f891
+and each device name can contain wild cards as defined by
c0f891
+.BR glob (7).
c0f891
+
c0f891
+Also, there may be several device lines present in the file.
c0f891
+
c0f891
+Alternatively, a
c0f891
+.B device
c0f891
+line can contain either or both of the  words
c0f891
+.B containers
c0f891
+and
c0f891
+.BR partitions .
c0f891
+The word
c0f891
+.B containers
c0f891
+will cause
c0f891
+.I mdadm
c0f891
+to look for assembled CONTAINER arrays and included them as a source
c0f891
+for assembling further arrays.
c0f891
+
c0f891
+The word
c0f891
+.I partitions
c0f891
+will cause
c0f891
+.I mdadm
c0f891
+to read
c0f891
+.I /proc/partitions
c0f891
+and include all devices and partitions found therein.
c0f891
+.I mdadm
c0f891
+does not use the names from
c0f891
+.I /proc/partitions
c0f891
+but only the major and minor device numbers.  It scans
c0f891
+.I /dev
c0f891
+to find the name that matches the numbers.
c0f891
+
c0f891
+If no DEVICE line is present, then "DEVICE partitions containers" is assumed.
c0f891
+
c0f891
+For example:
c0f891
+.IP
c0f891
+DEVICE /dev/hda* /dev/hdc*
c0f891
+.br
c0f891
+DEV    /dev/sd*
c0f891
+.br
c0f891
+DEVICE /dev/disk/by-path/pci*
c0f891
+.br
c0f891
+DEVICE partitions
c0f891
+
c0f891
+.TP
c0f891
+.B ARRAY
c0f891
+The ARRAY lines identify actual arrays.  The second word on the line
c0f891
+may be the name of the device where the array is normally
c0f891
+assembled, such as
c0f891
+.B /dev/md1
c0f891
+or
c0f891
+.BR /dev/md/backup .
c0f891
+If the name does not start with a slash
c0f891
+.RB (' / '),
c0f891
+it is treated as being in
c0f891
+.BR /dev/md/ .
c0f891
+Alternately the word
c0f891
+.B <ignore>
c0f891
+(complete with angle brackets) can be given in which case any array
c0f891
+which matches the rest of the line will never be automatically assembled.
c0f891
+If no device name is given,
c0f891
+.I mdadm
c0f891
+will use various heuristics to determine an appropriate name.
c0f891
+
c0f891
+Subsequent words identify the array, or identify the array as a member
c0f891
+of a group. If multiple identities are given,
c0f891
+then a component device must match ALL identities to be considered a
c0f891
+match.  Each identity word has a tag, and equals sign, and some value.
c0f891
+The tags are:
c0f891
+.RS 4
c0f891
+.TP
c0f891
+.B uuid=
c0f891
+The value should be a 128 bit uuid in hexadecimal, with punctuation
c0f891
+interspersed if desired.  This must match the uuid stored in the
c0f891
+superblock.
c0f891
+.TP
c0f891
+.B name=
c0f891
+The value should be a simple textual name as was given to
c0f891
+.I mdadm
c0f891
+when the array was created.  This must match the name stored in the
c0f891
+superblock on a device for that device to be included in the array.
c0f891
+Not all superblock formats support names.
c0f891
+.TP
c0f891
+.B super\-minor=
c0f891
+The value is an integer which indicates the minor number that was
c0f891
+stored in the superblock when the array was created. When an array is
c0f891
+created as /dev/mdX, then the minor number X is stored.
c0f891
+.TP
c0f891
+.B devices=
c0f891
+The value is a comma separated list of device names or device name
c0f891
+patterns.
c0f891
+Only devices with names which match one entry in the list will be used
c0f891
+to assemble the array.  Note that the devices
c0f891
+listed there must also be listed on a DEVICE line.
c0f891
+.TP
c0f891
+.B level=
c0f891
+The value is a RAID level.  This is not normally used to
c0f891
+identify an array, but is supported so that the output of
c0f891
+
c0f891
+.B "mdadm \-\-examine \-\-scan"
c0f891
+
c0f891
+can be use directly in the configuration file.
c0f891
+.TP
c0f891
+.B num\-devices=
c0f891
+The value is the number of devices in a complete active array.  As with
c0f891
+.B level=
c0f891
+this is mainly for compatibility with the output of
c0f891
+
c0f891
+.BR "mdadm \-\-examine \-\-scan" .
c0f891
+
c0f891
+.TP
c0f891
+.B spares=
c0f891
+The value is a number of spare devices to expect the array to have.
c0f891
+The sole use of this keyword and value is as follows:
c0f891
+.B mdadm \-\-monitor
c0f891
+will report an array if it is found to have fewer than this number of
c0f891
+spares when
c0f891
+.B \-\-monitor
c0f891
+starts or when
c0f891
+.B \-\-oneshot
c0f891
+is used.
c0f891
+
c0f891
+.TP
c0f891
+.B spare\-group=
c0f891
+The value is a textual name for a group of arrays.  All arrays with
c0f891
+the same
c0f891
+.B spare\-group
c0f891
+name are considered to be part of the same group.  The significance of
c0f891
+a group of arrays is that
c0f891
+.I mdadm
c0f891
+will, when monitoring the arrays, move a spare drive from one array in
c0f891
+a group to another array in that group if the first array had a failed
c0f891
+or missing drive but no spare.
c0f891
+
c0f891
+.TP
c0f891
+.B auto=
c0f891
+This option is rarely needed with mdadm-3.0, particularly if use with
c0f891
+the Linux kernel v2.6.28 or later.
c0f891
+It tells
c0f891
+.I mdadm
c0f891
+whether to use partitionable array or non-partitionable arrays and,
c0f891
+in the absence of
c0f891
+.IR udev ,
c0f891
+how many partition devices to create.  From 2.6.28 all md array
c0f891
+devices are partitionable, hence this option is not needed.
c0f891
+
c0f891
+The value of this option can be "yes" or "md" to indicate that a
c0f891
+traditional, non-partitionable md array should be created, or "mdp",
c0f891
+"part" or "partition" to indicate that a partitionable md array (only
c0f891
+available in linux 2.6 and later) should be used.  This later set can
c0f891
+also have a number appended to indicate how many partitions to create
c0f891
+device files for, e.g.
c0f891
+.BR auto=mdp5 .
c0f891
+The default is 4.
c0f891
+
c0f891
+.TP
c0f891
+.B bitmap=
c0f891
+The option specifies a file in which a write-intent bitmap should be
c0f891
+found.  When assembling the array,
c0f891
+.I mdadm
c0f891
+will provide this file to the
c0f891
+.B md
c0f891
+driver as the bitmap file.  This has the same function as the
c0f891
+.B \-\-bitmap\-file
c0f891
+option to
c0f891
+.BR \-\-assemble .
c0f891
+
c0f891
+.TP
c0f891
+.B metadata=
c0f891
+Specify the metadata format that the array has.  This is mainly
c0f891
+recognised for comparability with the output of
c0f891
+.BR "mdadm \-Es" .
c0f891
+
c0f891
+.TP
c0f891
+.B container=
c0f891
+Specify that this array is a member array of some container.  The
c0f891
+value given can be either a path name in /dev, or a UUID of the
c0f891
+container array.
c0f891
+
c0f891
+.TP
c0f891
+.B member=
c0f891
+Specify that this array is a member array of some container.  Each
c0f891
+type of container has some way to enumerate member arrays, often a
c0f891
+simple sequence number.  The value identifies which member of a
c0f891
+container the array is.  It will usually accompany a "container=" word.
c0f891
+.RE
c0f891
+
c0f891
+.TP
c0f891
+.B MAILADDR
c0f891
+The
c0f891
+.B mailaddr
c0f891
+line gives an E-mail address that alerts should be
c0f891
+sent to when
c0f891
+.I mdadm
c0f891
+is running in
c0f891
+.B \-\-monitor
c0f891
+mode (and was given the
c0f891
+.B \-\-scan
c0f891
+option).  There should only be one
c0f891
+.B MAILADDR
c0f891
+line and it should have only one address.  Any subsequent addresses
c0f891
+are silently ignored.
c0f891
+
c0f891
+.TP
c0f891
+.B MAILFROM
c0f891
+The
c0f891
+.B mailfrom
c0f891
+line (which can only be abbreviated to at least 5 characters) gives an
c0f891
+address to appear in the "From" address for alert mails.  This can be
c0f891
+useful if you want to explicitly set a domain, as the default from
c0f891
+address is "root" with no domain.  All words on this line are
c0f891
+catenated with spaces to form the address.
c0f891
+
c0f891
+Note that this value cannot be set via the
c0f891
+.I mdadm
c0f891
+commandline.  It is only settable via the config file.
c0f891
+
c0f891
+.TP
c0f891
+.B PROGRAM
c0f891
+The
c0f891
+.B program
c0f891
+line gives the name of a program to be run when
c0f891
+.B "mdadm \-\-monitor"
c0f891
+detects potentially interesting events on any of the arrays that it
c0f891
+is monitoring.  This program gets run with two or three arguments, they
c0f891
+being the Event, the md device, and possibly the related component
c0f891
+device.
c0f891
+
c0f891
+There should only be one
c0f891
+.B program
c0f891
+line and it should be give only one program.
c0f891
+
c0f891
+
c0f891
+.TP
c0f891
+.B CREATE
c0f891
+The
c0f891
+.B create
c0f891
+line gives default values to be used when creating arrays, new members
c0f891
+of arrays, and device entries for arrays.
c0f891
+These include:
c0f891
+
c0f891
+.RS 4
c0f891
+.TP
c0f891
+.B owner=
c0f891
+.TP
c0f891
+.B group=
c0f891
+These can give user/group ids or names to use instead of system
c0f891
+defaults (root/wheel or root/disk).
c0f891
+.TP
c0f891
+.B mode=
c0f891
+An octal file mode such as 0660 can be given to override the default
c0f891
+of 0600.
c0f891
+.TP
c0f891
+.B auto=
c0f891
+This corresponds to the
c0f891
+.B \-\-auto
c0f891
+flag to mdadm.  Give
c0f891
+.BR yes ,
c0f891
+.BR md ,
c0f891
+.BR mdp ,
c0f891
+.B part
c0f891
+\(em possibly followed by a number of partitions \(em to indicate how
c0f891
+missing device entries should be created.
c0f891
+
c0f891
+.TP
c0f891
+.B metadata=
c0f891
+The name of the metadata format to use if none is explicitly given.
c0f891
+This can be useful to impose a system-wide default of version-1 superblocks.
c0f891
+
c0f891
+.TP
c0f891
+.B symlinks=no
c0f891
+Normally when creating devices in
c0f891
+.B /dev/md/
c0f891
+.I mdadm
c0f891
+will create a matching symlink from
c0f891
+.B /dev/
c0f891
+with a name starting
c0f891
+.B md
c0f891
+or
c0f891
+.BR md_ .
c0f891
+Give
c0f891
+.B symlinks=no
c0f891
+to suppress this symlink creation.
c0f891
+
c0f891
+.TP
c0f891
+.B names=yes
c0f891
+Since Linux 2.6.29 it has been possible to create
c0f891
+.B md
c0f891
+devices with a name like
c0f891
+.B md_home
c0f891
+rather than just a number, like
c0f891
+.BR md3 .
c0f891
+.I mdadm
c0f891
+will use the numeric alternative by default as other tools that interact
c0f891
+with md arrays may expect only numbers.
c0f891
+If
c0f891
+.B names=yes
c0f891
+is given in
c0f891
+.I mdadm.conf
c0f891
+then
c0f891
+.I mdadm
c0f891
+will use a name when appropriate.
c0f891
+If
c0f891
+.B names=no
c0f891
+is given, then non-numeric
c0f891
+.I md
c0f891
+device names will not be used even if the default changes in a future
c0f891
+release of
c0f891
+.IR mdadm .
c0f891
+
c0f891
+.TP
c0f891
+.B bbl=no
c0f891
+By default,
c0f891
+.I mdadm
c0f891
+will reserve space for a bad block list (bbl) on all devices
c0f891
+included in or added to any array that supports them.  Setting
c0f891
+.B bbl=no
c0f891
+will prevent this, so newly added devices will not have a bad
c0f891
+block log.
c0f891
+.RE
c0f891
+
c0f891
+.TP
c0f891
+.B HOMEHOST
c0f891
+The
c0f891
+.B homehost
c0f891
+line gives a default value for the
c0f891
+.B \-\-homehost=
c0f891
+option to mdadm.  There should normally be only one other word on the line.
c0f891
+It should either be a host name, or one of the special words
c0f891
+.BR <system>,
c0f891
+.B <none>
c0f891
+and
c0f891
+.BR <ignore> .
c0f891
+If
c0f891
+.B <system>
c0f891
+is given, then the
c0f891
+.BR gethostname ( 2 )
c0f891
+systemcall is used to get the host name.  This is the default.
c0f891
+
c0f891
+If
c0f891
+.B <ignore>
c0f891
+is given, then a flag is set so that when arrays are being
c0f891
+auto-assembled the checking of the recorded
c0f891
+.I homehost
c0f891
+is disabled.
c0f891
+If
c0f891
+.B <ignore>
c0f891
+is given it is also possible to give an explicit name which will be
c0f891
+used when creating arrays.  This is the only case when there can be
c0f891
+more that one other word on the
c0f891
+.B HOMEHOST
c0f891
+line.  If there are other words, or other
c0f891
+.B HOMEHOST
c0f891
+lines, they are silently ignored.
c0f891
+
c0f891
+If
c0f891
+.B <none>
c0f891
+is given, then the default of using
c0f891
+.BR gethostname ( 2 )
c0f891
+is over-ridden and no homehost name is assumed.
c0f891
+
c0f891
+When arrays are created, this host name will be stored in the
c0f891
+metadata.  When arrays are assembled using auto-assembly, arrays which
c0f891
+do not record the correct homehost name in their metadata will be
c0f891
+assembled using a "foreign" name.  A "foreign" name alway ends with a
c0f891
+digit string preceded by an underscore to differentiate it
c0f891
+from any possible local name. e.g.
c0f891
+.B /dev/md/1_1
c0f891
+or
c0f891
+.BR /dev/md/home_0 .
c0f891
+.TP
c0f891
+.B AUTO
c0f891
+A list of names of metadata format can be given, each preceded by a
c0f891
+plus or minus sign.  Also the word
c0f891
+.I homehost
c0f891
+is allowed as is
c0f891
+.I all
c0f891
+preceded by plus or minus sign.
c0f891
+.I all
c0f891
+is usually last.
c0f891
+
c0f891
+When
c0f891
+.I mdadm
c0f891
+is auto-assembling an array, either via
c0f891
+.I \-\-assemble
c0f891
+or
c0f891
+.I \-\-incremental
c0f891
+and it finds metadata of a given type, it checks that metadata type
c0f891
+against those listed in this line.  The first match wins, where
c0f891
+.I all
c0f891
+matches anything.
c0f891
+If a match is found that was preceded by a plus sign, the auto
c0f891
+assembly is allowed.  If the match was preceded by a minus sign, the
c0f891
+auto assembly is disallowed.  If no match is found, the auto assembly
c0f891
+is allowed.
c0f891
+
c0f891
+If the metadata indicates that the array was created for
c0f891
+.I this
c0f891
+host, and the word
c0f891
+.I homehost
c0f891
+appears before any other match, then the array is treated as a valid
c0f891
+candidate for auto-assembly.
c0f891
+
c0f891
+This can be used to disable all auto-assembly (so that only arrays
c0f891
+explicitly listed in mdadm.conf or on the command line are assembled),
c0f891
+or to disable assembly of certain metadata types which might be
c0f891
+handled by other software.  It can also be used to disable assembly of
c0f891
+all foreign arrays - normally such arrays are assembled but given a
c0f891
+non-deterministic name in
c0f891
+.BR /dev/md/ .
c0f891
+
c0f891
+The known metadata types are
c0f891
+.BR 0.90 ,
c0f891
+.BR 1.x ,
c0f891
+.BR ddf ,
c0f891
+.BR imsm .
c0f891
+
c0f891
+.B AUTO
c0f891
+should be given at most once.  Subsequent lines are silently ignored.
c0f891
+Thus an earlier config file in a config directory will over-ride
c0f891
+the setting in a later config file.
c0f891
+
c0f891
+.TP
c0f891
+.B POLICY
c0f891
+This is used to specify what automatic behavior is allowed on devices
c0f891
+newly appearing in the system and provides a way of marking spares that can
c0f891
+be moved to other arrays as well as the migration domains.
c0f891
+.I Domain
c0f891
+can be defined through
c0f891
+.I policy
c0f891
+line by specifying a domain name for a number of paths from
c0f891
+.BR /dev/disk/by-path/ .
c0f891
+A device may belong to several domains. The domain of an array is a union
c0f891
+of domains of all devices in that array.  A spare can be automatically
c0f891
+moved from one array to another if the set of the destination array's
c0f891
+.I domains
c0f891
+contains all the
c0f891
+.I domains
c0f891
+of the new disk or if both arrays have the same
c0f891
+.IR spare-group .
c0f891
+
c0f891
+To update hot plug configuration it is necessary to execute
c0f891
+.B mdadm \-\-udev\-rules
c0f891
+command after changing the config file
c0f891
+
c0f891
+Keywords used in the
c0f891
+.I POLICY
c0f891
+line and supported values are:
c0f891
+
c0f891
+.RS 4
c0f891
+.TP
c0f891
+.B domain=
c0f891
+any arbitrary string
c0f891
+.TP
c0f891
+.B metadata=
c0f891
+0.9 1.x ddf or imsm
c0f891
+.TP
c0f891
+.B path=
c0f891
+file glob matching anything from
c0f891
+.B /dev/disk/by-path
c0f891
+.TP
c0f891
+.B type=
c0f891
+either
c0f891
+.B disk
c0f891
+or
c0f891
+.BR part .
c0f891
+.TP
c0f891
+.B action=
c0f891
+include, re-add, spare, spare-same-slot, or force-spare
c0f891
+.TP
c0f891
+.B auto=
c0f891
+yes, no, or homehost.
c0f891
+
c0f891
+.P
c0f891
+The
c0f891
+.I action
c0f891
+item determines the automatic behavior allowed for devices matching the
c0f891
+.I path
c0f891
+and
c0f891
+.I type
c0f891
+in the same line.  If a device matches several lines with different
c0f891
+.I  actions
c0f891
+then the most permissive will apply. The ordering of policy lines
c0f891
+is irrelevant to the end result.
c0f891
+.TP
c0f891
+.B include
c0f891
+allows adding a disk to an array if metadata on that disk matches that array
c0f891
+.TP
c0f891
+.B re\-add
c0f891
+will include the device in the array if it appears to be a current member
c0f891
+or a member that was recently removed and the array has a
c0f891
+write-intent-bitmap to allow the
c0f891
+.B re\-add
c0f891
+functionality.
c0f891
+.TP
c0f891
+.B spare
c0f891
+as above and additionally: if the device is bare it can
c0f891
+become a spare if there is any array that it is a candidate for based
c0f891
+on domains and metadata.
c0f891
+.TP
c0f891
+.B spare\-same\-slot
c0f891
+as above and additionally if given slot was used by an array that went
c0f891
+degraded recently and the device plugged in has no metadata then it will
c0f891
+be automatically added to that array (or it's container)
c0f891
+.TP
c0f891
+.B force\-spare
c0f891
+as above and the disk will become a spare in remaining cases
c0f891
+.RE
c0f891
+
c0f891
+.TP
c0f891
+.B PART-POLICY
c0f891
+This is similar to
c0f891
+.B POLICY
c0f891
+and accepts the same keyword assignments.  It allows a consistent set
c0f891
+of policies to applied to each of the partitions of a device.
c0f891
+
c0f891
+A
c0f891
+.B PART-POLICY
c0f891
+line should set
c0f891
+.I type=disk
c0f891
+and identify the path to one or more disk devices.  Each partition on
c0f891
+these disks will be treated according to the
c0f891
+.I action=
c0f891
+setting  from this line.  If a
c0f891
+.I domain
c0f891
+is set in the line, then the domain associated with each patition will
c0f891
+be based on the domain, but with
c0f891
+.RB \(dq -part N\(dq
c0f891
+appended, when N is the partition number for the partition that was
c0f891
+found.
c0f891
+
c0f891
+.TP
c0f891
+.B SYSFS
c0f891
+The
c0f891
+.B SYSFS
c0f891
+line lists custom values of MD device's sysfs attributes which will be
c0f891
+stored in sysfs after the array is assembled. Multiple lines are allowed and each
c0f891
+line has to contain the uuid or the name of the device to which it relates.
c0f891
+.RS 4
c0f891
+.TP
c0f891
+.B uuid=
c0f891
+hexadecimal identifier of MD device. This has to match the uuid stored in the
c0f891
+superblock.
c0f891
+.TP
c0f891
+.B name=
c0f891
+name of the MD device as was given to
c0f891
+.I mdadm
c0f891
+when the array was created. It will be ignored if
c0f891
+.B uuid
c0f891
+is not empty.
c0f891
+.RE
c0f891
+
c0f891
+.TP
c0f891
+.B MONITORDELAY
c0f891
+The
c0f891
+.B monitordelay
c0f891
+line gives a delay in seconds
c0f891
+.I mdadm
c0f891
+shall wait before pooling md arrays
c0f891
+when
c0f891
+.I mdadm
c0f891
+is running in
c0f891
+.B \-\-monitor
c0f891
+mode.
c0f891
+.B \-d/\-\-delay
c0f891
+command line argument takes precedence over the config file
c0f891
+
c0f891
+.SH EXAMPLE
c0f891
+DEVICE /dev/sd[bcdjkl]1
c0f891
+.br
c0f891
+DEVICE /dev/hda1 /dev/hdb1
c0f891
+
c0f891
+# /dev/md0 is known by its UUID.
c0f891
+.br
c0f891
+ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371
c0f891
+.br
c0f891
+# /dev/md1 contains all devices with a minor number of
c0f891
+.br
c0f891
+#   1 in the superblock.
c0f891
+.br
c0f891
+ARRAY /dev/md1 superminor=1
c0f891
+.br
c0f891
+# /dev/md2 is made from precisely these two devices
c0f891
+.br
c0f891
+ARRAY /dev/md2 devices=/dev/hda1,/dev/hdb1
c0f891
+
c0f891
+# /dev/md4 and /dev/md5 are a spare-group and spares
c0f891
+.br
c0f891
+#  can be moved between them
c0f891
+.br
c0f891
+ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df
c0f891
+.br
c0f891
+           spare\-group=group1
c0f891
+.br
c0f891
+ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977
c0f891
+.br
c0f891
+           spare\-group=group1
c0f891
+.br
c0f891
+# /dev/md/home is created if need to be a partitionable md array
c0f891
+.br
c0f891
+# any spare device number is allocated.
c0f891
+.br
c0f891
+ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b
c0f891
+.br
c0f891
+           auto=part
c0f891
+.br
c0f891
+# The name of this array contains a space.
c0f891
+.br
c0f891
+ARRAY /dev/md9 name='Data Storage'
c0f891
+.sp
c0f891
+POLICY domain=domain1 metadata=imsm path=pci-0000:00:1f.2-scsi-*
c0f891
+.br
c0f891
+           action=spare
c0f891
+.br
c0f891
+POLICY domain=domain1 metadata=imsm path=pci-0000:04:00.0-scsi-[01]*
c0f891
+.br
c0f891
+           action=include
c0f891
+.br
c0f891
+# One domain comprising of devices attached to specified paths is defined.
c0f891
+.br
c0f891
+# Bare device matching first path will be made an imsm spare on hot plug.
c0f891
+.br
c0f891
+# If more than one array is created on devices belonging to domain1 and
c0f891
+.br
c0f891
+# one of them becomes degraded, then any imsm spare matching any path for
c0f891
+.br
c0f891
+# given domain name can be migrated.
c0f891
+.br
c0f891
+MAILADDR root@mydomain.tld
c0f891
+.br
c0f891
+PROGRAM /usr/sbin/handle\-mdadm\-events
c0f891
+.br
c0f891
+CREATE group=system mode=0640 auto=part\-8
c0f891
+.br
c0f891
+HOMEHOST <system>
c0f891
+.br
c0f891
+AUTO +1.x homehost \-all
c0f891
+.br
c0f891
+SYSFS name=/dev/md/raid5 group_thread_cnt=4 sync_speed_max=1000000
c0f891
+.br
c0f891
+SYSFS uuid=bead5eb6:31c17a27:da120ba2:7dfda40d group_thread_cnt=4
c0f891
+sync_speed_max=1000000
c0f891
+.br
c0f891
+MONITORDELAY 60
c0f891
+
c0f891
+.SH SEE ALSO
c0f891
+.BR mdadm (8),
c0f891
+.BR md (4).
c0f891
-- 
37f2b0
2.38.1
c0f891