This allows basing auto-assembly decisions on whether the array is recorded as belonging to this host or not. Signed-off-by: NeilBrown <neilb@suse.de>
474 lines
12 KiB
Groff
474 lines
12 KiB
Groff
.\" Copyright Neil Brown and others.
|
|
.\" This program is free software; you can redistribute it and/or modify
|
|
.\" it under the terms of the GNU General Public License as published by
|
|
.\" the Free Software Foundation; either version 2 of the License, or
|
|
.\" (at your option) any later version.
|
|
.\" See file COPYING in distribution for details.
|
|
.TH MDADM.CONF 5
|
|
.SH NAME
|
|
mdadm.conf \- configuration for management of Software RAID with mdadm
|
|
.SH SYNOPSIS
|
|
/etc/mdadm.conf
|
|
.SH DESCRIPTION
|
|
.PP
|
|
.I mdadm
|
|
is a tool for creating, managing, and monitoring RAID devices using the
|
|
.B md
|
|
driver in Linux.
|
|
.PP
|
|
Some common tasks, such as assembling all arrays, can be simplified
|
|
by describing the devices and arrays in this configuration file.
|
|
|
|
.SS SYNTAX
|
|
The file should be seen as a collection of words separated by white
|
|
space (space, tab, or newline).
|
|
Any word that beings with a hash sign (#) starts a comment and that
|
|
word together with the remainder of the line is ignored.
|
|
|
|
Any line that starts with white space (space or tab) is treated as
|
|
though it were a continuation of the previous line.
|
|
|
|
Empty lines are ignored, but otherwise each (non continuation) line
|
|
must start with a keyword as listed below. The keywords are case
|
|
insensitive and can be abbreviated to 3 characters.
|
|
|
|
The keywords are:
|
|
.TP
|
|
.B DEVICE
|
|
A
|
|
.B device
|
|
line lists the devices (whole devices or partitions) that might contain
|
|
a component of an MD array. When looking for the components of an
|
|
array,
|
|
.I mdadm
|
|
will scan these devices (or any devices listed on the command line).
|
|
|
|
The
|
|
.B device
|
|
line may contain a number of different devices (separated by spaces)
|
|
and each device name can contain wild cards as defined by
|
|
.BR glob (7).
|
|
|
|
Also, there may be several device lines present in the file.
|
|
|
|
Alternatively, a
|
|
.B device
|
|
line can contain either of both of the words
|
|
.B containers
|
|
and
|
|
.BR partitions .
|
|
The word
|
|
.B containers
|
|
will cause
|
|
.I mdadm
|
|
to look for assembled CONTAINER arrays and included them as a source
|
|
for assembling further arrays.
|
|
|
|
The word
|
|
.I partitions
|
|
will cause
|
|
.I mdadm
|
|
to read
|
|
.I /proc/partitions
|
|
and include all devices and partitions found therein.
|
|
.I mdadm
|
|
does not use the names from
|
|
.I /proc/partitions
|
|
but only the major and minor device numbers. It scans
|
|
.I /dev
|
|
to find the name that matches the numbers.
|
|
|
|
If no DEVICE line is present, then "DEVICE partitions containers" is assumed.
|
|
|
|
For example:
|
|
.IP
|
|
DEVICE /dev/hda* /dev/hdc*
|
|
.br
|
|
DEV /dev/sd*
|
|
.br
|
|
DEVICE /dev/disk/by-path/pci*
|
|
.br
|
|
DEVICE partitions
|
|
|
|
.TP
|
|
.B ARRAY
|
|
The ARRAY lines identify actual arrays. The second word on the line
|
|
may be the name of the device where the array is normally
|
|
assembled, such as
|
|
.B /dev/md1
|
|
or
|
|
.BR /dev/md/backup .
|
|
If the name does not start with a slash
|
|
.RB (' / '),
|
|
it is treated as being in
|
|
.BR /dev/md/ .
|
|
Alternately the word
|
|
.B <ignore>
|
|
(complete with angle brackets) can be given in which case any array
|
|
which matches the rest of the line will never be automatically assembled.
|
|
If no device name is given,
|
|
.I mdadm
|
|
will use various heuristics to determine an appropriate name.
|
|
|
|
Subsequent words identify the array, or identify the array as a member
|
|
of a group. If multiple identities are given,
|
|
then a component device must match ALL identities to be considered a
|
|
match. Each identity word has a tag, and equals sign, and some value.
|
|
The tags are:
|
|
.RS 4
|
|
.TP
|
|
.B uuid=
|
|
The value should be a 128 bit uuid in hexadecimal, with punctuation
|
|
interspersed if desired. This must match the uuid stored in the
|
|
superblock.
|
|
.TP
|
|
.B name=
|
|
The value should be a simple textual name as was given to
|
|
.I mdadm
|
|
when the array was created. This must match the name stored in the
|
|
superblock on a device for that device to be included in the array.
|
|
Not all superblock formats support names.
|
|
.TP
|
|
.B super\-minor=
|
|
The value is an integer which indicates the minor number that was
|
|
stored in the superblock when the array was created. When an array is
|
|
created as /dev/mdX, then the minor number X is stored.
|
|
.TP
|
|
.B devices=
|
|
The value is a comma separated list of device names or device name
|
|
patterns.
|
|
Only devices with names which match one entry in the list will be used
|
|
to assemble the array. Note that the devices
|
|
listed there must also be listed on a DEVICE line.
|
|
.TP
|
|
.B level=
|
|
The value is a raid level. This is not normally used to
|
|
identify an array, but is supported so that the output of
|
|
|
|
.B "mdadm \-\-examine \-\-scan"
|
|
|
|
can be use directly in the configuration file.
|
|
.TP
|
|
.B num\-devices=
|
|
The value is the number of devices in a complete active array. As with
|
|
.B level=
|
|
this is mainly for compatibility with the output of
|
|
|
|
.BR "mdadm \-\-examine \-\-scan" .
|
|
|
|
.TP
|
|
.B spares=
|
|
The value is a number of spare devices to expect the array to have.
|
|
The sole use of this keyword and value is as follows:
|
|
.B mdadm \-\-monitor
|
|
will report an array if it is found to have fewer than this number of
|
|
spares when
|
|
.B \-\-monitor
|
|
starts or when
|
|
.B \-\-oneshot
|
|
is used.
|
|
|
|
.TP
|
|
.B spare\-group=
|
|
The value is a textual name for a group of arrays. All arrays with
|
|
the same
|
|
.B spare\-group
|
|
name are considered to be part of the same group. The significance of
|
|
a group of arrays is that
|
|
.I mdadm
|
|
will, when monitoring the arrays, move a spare drive from one array in
|
|
a group to another array in that group if the first array had a failed
|
|
or missing drive but no spare.
|
|
|
|
.TP
|
|
.B auto=
|
|
This option is rarely needed with mdadm-3.0, particularly if use with
|
|
the Linux kernel v2.6.28 or later.
|
|
It tells
|
|
.I mdadm
|
|
whether to use partitionable array or non-partitionable arrays and,
|
|
in the absence of
|
|
.IR udev ,
|
|
how many partition devices to create. From 2.6.28 all md array
|
|
devices are partitionable, hence this option is not needed.
|
|
|
|
The value of this option can be "yes" or "md" to indicate that a
|
|
traditional, non-partitionable md array should be created, or "mdp",
|
|
"part" or "partition" to indicate that a partitionable md array (only
|
|
available in linux 2.6 and later) should be used. This later set can
|
|
also have a number appended to indicate how many partitions to create
|
|
device files for, e.g.
|
|
.BR auto=mdp5 .
|
|
The default is 4.
|
|
|
|
.TP
|
|
.B bitmap=
|
|
The option specifies a file in which a write-intent bitmap should be
|
|
found. When assembling the array,
|
|
.I mdadm
|
|
will provide this file to the
|
|
.B md
|
|
driver as the bitmap file. This has the same function as the
|
|
.B \-\-bitmap\-file
|
|
option to
|
|
.BR \-\-assemble .
|
|
|
|
.TP
|
|
.B metadata=
|
|
Specify the metadata format that the array has. This is mainly
|
|
recognised for comparability with the output of
|
|
.BR "mdadm \-Es" .
|
|
|
|
.TP
|
|
.B container=
|
|
Specify that this array is a member array of some container. The
|
|
value given can be either a path name in /dev, or a UUID of the
|
|
container array.
|
|
|
|
.TP
|
|
.B member=
|
|
Specify that this array is a member array of some container. Each
|
|
type of container has some way to enumerate member arrays, often a
|
|
simple sequence number. The value identifies which member of a
|
|
container the array is. It will usually accompany a "container=" word.
|
|
.RE
|
|
|
|
.TP
|
|
.B MAILADDR
|
|
The
|
|
.B mailaddr
|
|
line gives an E-mail address that alerts should be
|
|
sent to when
|
|
.I mdadm
|
|
is running in
|
|
.B \-\-monitor
|
|
mode (and was given the
|
|
.B \-\-scan
|
|
option). There should only be one
|
|
.B MAILADDR
|
|
line and it should have only one address.
|
|
|
|
|
|
.TP
|
|
.B MAILFROM
|
|
The
|
|
.B mailfrom
|
|
line (which can only be abbreviated to at least 5 characters) gives an
|
|
address to appear in the "From" address for alert mails. This can be
|
|
useful if you want to explicitly set a domain, as the default from
|
|
address is "root" with no domain. All words on this line are
|
|
catenated with spaces to form the address.
|
|
|
|
Note that this value cannot be set via the
|
|
.I mdadm
|
|
commandline. It is only settable via the config file.
|
|
|
|
.TP
|
|
.B PROGRAM
|
|
The
|
|
.B program
|
|
line gives the name of a program to be run when
|
|
.B "mdadm \-\-monitor"
|
|
detects potentially interesting events on any of the arrays that it
|
|
is monitoring. This program gets run with two or three arguments, they
|
|
being the Event, the md device, and possibly the related component
|
|
device.
|
|
|
|
There should only be one
|
|
.B program
|
|
line and it should be give only one program.
|
|
|
|
|
|
.TP
|
|
.B CREATE
|
|
The
|
|
.B create
|
|
line gives default values to be used when creating arrays and device entries for
|
|
arrays.
|
|
These include:
|
|
|
|
.RS 4
|
|
.TP
|
|
.B owner=
|
|
.TP
|
|
.B group=
|
|
These can give user/group ids or names to use instead of system
|
|
defaults (root/wheel or root/disk).
|
|
.TP
|
|
.B mode=
|
|
An octal file mode such as 0660 can be given to override the default
|
|
of 0600.
|
|
.TP
|
|
.B auto=
|
|
This corresponds to the
|
|
.B \-\-auto
|
|
flag to mdadm. Give
|
|
.BR yes ,
|
|
.BR md ,
|
|
.BR mdp ,
|
|
.B part
|
|
\(em possibly followed by a number of partitions \(em to indicate how
|
|
missing device entries should be created.
|
|
|
|
.TP
|
|
.B metadata=
|
|
The name of the metadata format to use if none is explicitly given.
|
|
This can be useful to impose a system-wide default of version-1 superblocks.
|
|
|
|
.TP
|
|
.B symlinks=no
|
|
Normally when creating devices in
|
|
.B /dev/md/
|
|
.I mdadm
|
|
will create a matching symlink from
|
|
.B /dev/
|
|
with a name starting
|
|
.B md
|
|
or
|
|
.BR md_ .
|
|
Give
|
|
.B symlinks=no
|
|
to suppress this symlink creation.
|
|
.RE
|
|
|
|
.TP
|
|
.B HOMEHOST
|
|
The
|
|
.B homehost
|
|
line gives a default value for the
|
|
.B \-\-homehost=
|
|
option to mdadm. There should normally be only one other word on the line.
|
|
It should either be a host name, or one of the special words
|
|
.B <system>
|
|
and
|
|
.BR <ignore> .
|
|
If
|
|
.B <system>
|
|
is given, then the
|
|
.BR gethostname ( 2 )
|
|
systemcall is used to get the host name.
|
|
|
|
If
|
|
.B <ignore>
|
|
is given, then a flag is set so that when arrays are being
|
|
auto-assembled the checking of the recorded
|
|
.I homehost
|
|
is disabled.
|
|
If
|
|
.B <ignore>
|
|
is given it is also possible to give an explicit name which will be
|
|
used when creating arrays. This is the only case when there can be
|
|
more that one other word on the
|
|
.B HOMEHOST
|
|
line.
|
|
|
|
When arrays are created, this host name will be stored in the
|
|
metadata. When arrays are assembled using auto-assembly, arrays which
|
|
do not record the correct homehost name in their metadata will be
|
|
assembled using a "foreign" name. A "foreign" name alway ends with a
|
|
digit string preceded by an underscore to differentiate it
|
|
from any possible local name. e.g.
|
|
.B /dev/md/1_1
|
|
or
|
|
.BR /dev/md/home_0 .
|
|
.TP
|
|
.B AUTO
|
|
A list of names of metadata format can be given, each preceded by a
|
|
plus or minus sign. Also the word
|
|
.I homehost
|
|
is allowed as is
|
|
.I all
|
|
preceded by plus or minus sign.
|
|
.I all
|
|
is usually last.
|
|
|
|
When
|
|
.I mdadm
|
|
is auto-assembling an array, either via
|
|
.I \-\-assemble
|
|
or
|
|
.I \-\-incremental
|
|
and it finds metadata of a given type, it checks that metadata type
|
|
against those listed in this line. The first match wins, where
|
|
.I all
|
|
matches anything.
|
|
If a match is found that was preceded by a plus sign, the auto
|
|
assembly is allowed. If the match was preceded by a minus sign, the
|
|
auto assembly is disallowed. If no match is found, the auto assembly
|
|
is allowed.
|
|
|
|
If the metadata indicates that the array was created for
|
|
.I this
|
|
host, and the word
|
|
.I homehost
|
|
appears before any other match, then the array is treated as a valid
|
|
candidate for auto-assembly.
|
|
|
|
This can be used to disable all auto-assembly (so that only arrays
|
|
explicitly listed in mdadm.conf or on the command line are assembled),
|
|
or to disable assembly of certain metadata types which might be
|
|
handled by other software. It can also be used to disable assembly of
|
|
all foreign arrays - normally such arrays are assembled but given a
|
|
non-deterministic name in
|
|
.BR /dev/md/ .
|
|
|
|
The known metadata types are
|
|
.BR 0.90 ,
|
|
.BR 1.x ,
|
|
.BR ddf ,
|
|
.BR imsm .
|
|
|
|
.SH EXAMPLE
|
|
DEVICE /dev/sd[bcdjkl]1
|
|
.br
|
|
DEVICE /dev/hda1 /dev/hdb1
|
|
|
|
# /dev/md0 is known by its UUID.
|
|
.br
|
|
ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371
|
|
.br
|
|
# /dev/md1 contains all devices with a minor number of
|
|
.br
|
|
# 1 in the superblock.
|
|
.br
|
|
ARRAY /dev/md1 superminor=1
|
|
.br
|
|
# /dev/md2 is made from precisely these two devices
|
|
.br
|
|
ARRAY /dev/md2 devices=/dev/hda1,/dev/hdb1
|
|
|
|
# /dev/md4 and /dev/md5 are a spare-group and spares
|
|
.br
|
|
# can be moved between them
|
|
.br
|
|
ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df
|
|
.br
|
|
spare\-group=group1
|
|
.br
|
|
ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977
|
|
.br
|
|
spare\-group=group1
|
|
.br
|
|
# /dev/md/home is created if need to be a partitionable md array
|
|
.br
|
|
# any spare device number is allocated.
|
|
.br
|
|
ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b
|
|
.br
|
|
auto=part
|
|
|
|
MAILADDR root@mydomain.tld
|
|
.br
|
|
PROGRAM /usr/sbin/handle\-mdadm\-events
|
|
.br
|
|
CREATE group=system mode=0640 auto=part\-8
|
|
.br
|
|
HOMEHOST <system>
|
|
.br
|
|
AUTO +1.x homehost -all
|
|
|
|
.SH SEE ALSO
|
|
.BR mdadm (8),
|
|
.BR md (4).
|
|
|