1367 lines
35 KiB
Groff
1367 lines
35 KiB
Groff
.\" -*- nroff -*-
|
|
.TH MDADM 8 "" v2.0-devel-1
|
|
.SH NAME
|
|
mdadm \- manage MD devices
|
|
.I aka
|
|
Linux Software Raid.
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.BI mdadm " [mode] <raiddevice> [options] <component-devices>"
|
|
|
|
.SH DESCRIPTION
|
|
RAID devices are virtual devices created from two or more
|
|
real block devices. This allows multiple devices (typically disk
|
|
drives or partitions there-of) to be combined into a single device to
|
|
hold (for example) a single filesystem.
|
|
Some RAID levels include redundancy and so can survive some degree of
|
|
device failure.
|
|
|
|
Linux Software RAID devices are implemented through the md (Multiple
|
|
Devices) device driver.
|
|
|
|
Currently, Linux supports
|
|
.B LINEAR
|
|
md devices,
|
|
.B RAID0
|
|
(striping),
|
|
.B RAID1
|
|
(mirroring),
|
|
.BR RAID4 ,
|
|
.BR RAID5 ,
|
|
.BR RAID6 ,
|
|
.BR MULTIPATH ,
|
|
and
|
|
.BR FAULTY .
|
|
|
|
.B MULTIPATH is not a Software RAID mechanism, but does involve
|
|
multiple devices. For
|
|
.B MULTIPATH
|
|
each device is a path to one common physical storage device.
|
|
|
|
.B FAULTY is also no true RAID, and it only involves one device. It
|
|
provides a layer over a true device that can be used to inject faults.
|
|
|
|
.B mdadm
|
|
is a program that can be used to create, manage, and monitor
|
|
MD devices. As
|
|
such it provides a similar set of functionality to the
|
|
.B raidtools
|
|
packages.
|
|
The key differences between
|
|
.B mdadm
|
|
and
|
|
.B raidtools
|
|
are:
|
|
.IP \(bu 4
|
|
.B mdadm
|
|
is a single program and not a collection of programs.
|
|
.IP \(bu 4
|
|
.B mdadm
|
|
can perform (almost) all of its functions without having a
|
|
configuration file and does not use one by default. Also
|
|
.B mdadm
|
|
helps with management of the configuration
|
|
file.
|
|
.IP \(bu 4
|
|
.B mdadm
|
|
can provide information about your arrays (through Query, Detail, and Examine)
|
|
that
|
|
.B raidtools
|
|
cannot.
|
|
.P
|
|
.I mdadm
|
|
does not use
|
|
.IR /etc/raidtab ,
|
|
the
|
|
.B raidtools
|
|
configuration file, at all. It has a different configuration file
|
|
with a different format and an different purpose.
|
|
|
|
.SH MODES
|
|
mdadm has 7 major modes of operation:
|
|
.TP
|
|
.B Assemble
|
|
Assemble the parts of a previously created
|
|
array into an active array. Components can be explicitly given
|
|
or can be searched for.
|
|
.B mdadm
|
|
checks that the components
|
|
do form a bona fide array, and can, on request, fiddle superblock
|
|
information so as to assemble a faulty array.
|
|
|
|
.TP
|
|
.B Build
|
|
Build an array without per-device superblocks.
|
|
|
|
.TP
|
|
.B Create
|
|
Create a new array with per-device superblocks.
|
|
'''It can progress
|
|
'''in several step create-add-add-run or it can all happen with one command.
|
|
|
|
.TP
|
|
.B Manage
|
|
This is for doing things to specific components of an array such as
|
|
adding new spares and removing faulty devices.
|
|
|
|
.TP
|
|
.B Misc
|
|
This mode allows operations on independent devices such as examine MD
|
|
superblocks, erasing old superblocks and stopping active arrays.
|
|
|
|
.TP
|
|
.B "Follow or Monitor"
|
|
Monitor one or more md devices and act on any state changes. This is
|
|
only meaningful for raid1, 4, 5, 6 or multipath arrays as
|
|
only these have interesting state. raid0 or linear never have
|
|
missing, spare, or failed drives, so there is nothing to monitor.
|
|
|
|
.TP
|
|
.B "Grow"
|
|
Grow (or shrink) an array, or otherwise reshape it in some way.
|
|
Currently supported growth options including changing the active size
|
|
of componenet devices in RAID level 1/4/5/6 and changing the number of
|
|
active devices in RAID1.
|
|
|
|
.SH OPTIONS
|
|
|
|
Available options are:
|
|
|
|
.TP
|
|
.BR -A ", " --assemble
|
|
Assemble a pre-existing array.
|
|
|
|
.TP
|
|
.BR -B ", " --build
|
|
Build a legacy array without superblocks.
|
|
|
|
.TP
|
|
.BR -C ", " --create
|
|
Create a new array.
|
|
|
|
.TP
|
|
.BR -Q ", " --query
|
|
Examine a device to see
|
|
(1) if it is an md device and (2) if it is a component of an md
|
|
array.
|
|
Information about what is discovered is presented.
|
|
|
|
.TP
|
|
.BR -D ", " --detail
|
|
Print detail of one or more md devices.
|
|
|
|
.TP
|
|
.BR -E ", " --examine
|
|
Print content of md superblock on device(s).
|
|
|
|
.TP
|
|
.BR -F ", " --follow ", " --monitor
|
|
Select
|
|
.B Monitor
|
|
mode.
|
|
|
|
.TP
|
|
.BR -G ", " --grow
|
|
Change the size or shape of an active array.
|
|
|
|
.TP
|
|
.BR -X ", " --examine-bitmap
|
|
Report information about a bitmap file.
|
|
|
|
.TP
|
|
.BR -h ", " --help
|
|
Display help message or, after above option, mode specific help
|
|
message.
|
|
|
|
.TP
|
|
.B --help-options
|
|
Display more detailed help about command line parsing and some commonly
|
|
used options.
|
|
|
|
.TP
|
|
.BR -V ", " --version
|
|
Print version information for mdadm.
|
|
|
|
.TP
|
|
.BR -v ", " --verbose
|
|
Be more verbose about what is happening.
|
|
|
|
.TP
|
|
.BR -b ", " --brief
|
|
Be less verbose. This is used with
|
|
.B --detail
|
|
and
|
|
.BR --examine .
|
|
|
|
.TP
|
|
.BR -b ", " --bitmap=
|
|
Give the name of a bitmap file to use with this array. Can be used
|
|
with --create (file should not exist) or --assemble (file should
|
|
exist).
|
|
|
|
.TP
|
|
.BR --bitmap-chunk=
|
|
Set the Chunksize of the bitmap. Each bit corresponds to that many
|
|
Kilobytes of storage. Default is 4.
|
|
|
|
|
|
.TP
|
|
.BR -f ", " --force
|
|
Be more forceful about certain operations. See the various modes of
|
|
the exact meaning of this option in different contexts.
|
|
|
|
.TP
|
|
.BR -c ", " --config=
|
|
Specify the config file. Default is
|
|
.BR /etc/mdadm.conf .
|
|
If the config file given is
|
|
.B partitions
|
|
then nothing will be read, but
|
|
.I mdadm
|
|
will act as though the config file contained exactly
|
|
.B "DEVICE partitions"
|
|
and will read
|
|
.B /proc/partitions
|
|
to find a list of devices to scan.
|
|
If the word
|
|
.B none
|
|
is given for the config file, then
|
|
.I mdadm
|
|
will act as though the config file were empty.
|
|
|
|
.TP
|
|
.BR -s ", " --scan
|
|
scan config file or
|
|
.B /proc/mdstat
|
|
for missing information.
|
|
In general, this option gives
|
|
.B mdadm
|
|
permission to get any missing information, like component devices,
|
|
array devices, array identities, and alert destination from the
|
|
configuration file:
|
|
.BR /etc/mdadm.conf .
|
|
One exception is MISC mode when using
|
|
.B --detail
|
|
or
|
|
.B --stop
|
|
in which case
|
|
.B --scan
|
|
says to get a list of array devices from
|
|
.BR /proc/mdstat .
|
|
|
|
.TP
|
|
.B -e ", " --metadata=
|
|
Declare the style of superblock (raid metadata) to be used. The
|
|
default is 0.90 for --create, and to guess for other operations.
|
|
|
|
Options are:
|
|
.RS
|
|
.IP "0, 0.90, default"
|
|
Use the original 0.90 format superblock. This format limits arrays to
|
|
28 componenet devices and limits component devices of levels 1 and
|
|
greater to 2 terabytes.
|
|
.IP "1, 1.0, 1.1, 1.2"
|
|
Use the new version-1 format superblock. This has few restrictions.
|
|
The different subversion store the superblock at different locations
|
|
on the device, either at the end (for 1.0), at the start (for 1.1) or
|
|
4K from the start (for 1.2).
|
|
.RE
|
|
|
|
.SH For create or build:
|
|
|
|
.TP
|
|
.BR -c ", " --chunk=
|
|
Specify chunk size of kibibytes. The default is 64.
|
|
|
|
.TP
|
|
.BR --rounding=
|
|
Specify rounding factor for linear array (==chunk size)
|
|
|
|
.TP
|
|
.BR -l ", " --level=
|
|
Set raid level. When used with
|
|
.IR --create ,
|
|
options are: linear, raid0, 0, stripe, raid1, 1, mirror, raid4, 4,
|
|
raid5, 5, raid6, 6, multipath, mp, fautly. Obviously some of these are synonymous.
|
|
|
|
When used with
|
|
.IR --build ,
|
|
only linear, raid0, 0, stripe are valid.
|
|
|
|
.TP
|
|
.BR -p ", " --parity=
|
|
Set raid5 parity algorithm. Options are:
|
|
left-asymmetric,
|
|
left-symmetric,
|
|
right-asymmetric,
|
|
right-symmetric,
|
|
la, ra, ls, rs. The default is left-symmetric.
|
|
|
|
This option is also used to set the failure mode for
|
|
.IR faulty .
|
|
The options are:
|
|
write-transient,
|
|
wt,
|
|
read-transient,
|
|
rt,
|
|
write-presistent,
|
|
wp,
|
|
read-persistent,
|
|
rp,
|
|
write-all,
|
|
read-fixable,
|
|
rf,
|
|
clear,
|
|
flush,
|
|
none.
|
|
|
|
Each mode can be followed by a number which is used as a period
|
|
between fault generation. Without a number, the fault is generated
|
|
once on the first relevant request. With a number, the fault will be
|
|
generated after that many request, and will continue to be generated
|
|
every time the period elapses.
|
|
|
|
Multiple failure modes can be current simultaneously by using the
|
|
"--grow" option to set subsequent failure modes.
|
|
|
|
"clear" or "none" will remove any pending or periodic failure modes,
|
|
and "flush" will clear any persistant faults.
|
|
|
|
To set the parity with "--grow", the level of the array ("faulty")
|
|
must be specified before the fault mode is specified.
|
|
|
|
.TP
|
|
.BR --layout=
|
|
same as --parity
|
|
|
|
.TP
|
|
.BR -b ", " --bitmap=
|
|
Specify a file to store a write-intent bitmap in. The file should not
|
|
exist unless --force is also given. The same file should be provided
|
|
when assembling the array.
|
|
|
|
.TP
|
|
.BR --bitmap-chunk=
|
|
Specifty the chunksize for the bitmap.
|
|
|
|
.TP
|
|
.BR -n ", " --raid-devices=
|
|
Specify the number of active devices in the array. This, plus the
|
|
number of spare devices (see below) must equal the number of
|
|
.I component-devices
|
|
(including "\fBmissing\fP" devices)
|
|
that are listed on the command line for
|
|
.BR --create .
|
|
Setting a value of 1 is probably
|
|
a mistake and so requires that
|
|
.B --force
|
|
be specified first. A value of 1 will then be allowed for linear,
|
|
multipath, raid0 and raid1. It is never allowed for raid4 or raid5.
|
|
.br
|
|
This number can only be changed using
|
|
.B --grow
|
|
for RAID1 arrays, and only on kernels which provide necessary support.
|
|
|
|
.TP
|
|
.BR -x ", " --spare-devices=
|
|
Specify the number of spare (eXtra) devices in the initial array.
|
|
Spares can also be added
|
|
and removed later. The number of component devices listed
|
|
on the command line must equal the number of raid devices plus the
|
|
number of spare devices.
|
|
|
|
|
|
.TP
|
|
.BR -z ", " --size=
|
|
Amount (in Kibibytes) of space to use from each drive in RAID1/4/5/6.
|
|
This must be a multiple of the chunk size, and must leave about 128Kb
|
|
of space at the end of the drive for the RAID superblock.
|
|
If this is not specified
|
|
(as it normally is not) the smallest drive (or partition) sets the
|
|
size, though if there is a variance among the drives of greater than 1%, a warning is
|
|
issued.
|
|
|
|
This value can be set with
|
|
.B --grow
|
|
for RAID level 1/4/5/6. If the array was created with a size smaller
|
|
than the currently active drives, the extra space can be accessed
|
|
using
|
|
.BR --grow .
|
|
|
|
.TP
|
|
.BR --assume-clean
|
|
Tell
|
|
.I mdadm
|
|
that the array pre-existed and is known to be clean. This is only
|
|
really useful for Building RAID1 array. Only use this if you really
|
|
know what you are doing. This is currently only supported for --build.
|
|
|
|
.TP
|
|
.BR -R ", " --run
|
|
Insist that
|
|
.I mdadm
|
|
run the array, even if some of the components
|
|
appear to be active in another array or filesystem. Normally
|
|
.I mdadm
|
|
will ask for confirmation before including such components in an
|
|
array. This option causes that question to be suppressed.
|
|
|
|
.TP
|
|
.BR -f ", " --force
|
|
Insist that
|
|
.I mdadm
|
|
accept the geometry and layout specified without question. Normally
|
|
.I mdadm
|
|
will not allow creation of an array with only one device, and will try
|
|
to create a raid5 array with one missing drive (as this makes the
|
|
initial resync work faster). With
|
|
.BR --force ,
|
|
.I mdadm
|
|
will not try to be so clever.
|
|
|
|
.TP
|
|
.BR -a ", " "--auto{=no,yes,md,mdp,part,p}{NN}"
|
|
Instruct mdadm to create the device file if needed, possibly allocating
|
|
an unused minor number. "md" causes a non-partitionable array
|
|
to be used. "mdp", "part" or "p" causes a partitionable array (2.6 and
|
|
later) to be used. "yes" requires the named md device to have a
|
|
'standard' format, and the type and minor number will be determined
|
|
from this. See DEVICE NAMES below.
|
|
|
|
The argumentment can also come immediately after
|
|
"-a". e.g. "-ap".
|
|
|
|
For partitionable arrays,
|
|
.I mdadm
|
|
will create the device file for the whole array and for the first 4
|
|
partitions. A different number of partitions can be specified at the
|
|
end of this option (e.g.
|
|
.BR --auto=p7 ).
|
|
If the device name ends with a digit, the partition names add a'p',
|
|
and a number, e.g. "/dev/home1p3". If there is no
|
|
trailing digit, then the partition names just have a number added,
|
|
e.g. "/dev/scratch3".
|
|
|
|
If the md device name is in a 'standard' format as described in DEVICE
|
|
NAMES, then it will be created, if necessary, with the appropriate
|
|
number based on that name. If the device name is not in one of these
|
|
formats, then a unused minor number will be allocted. The minor
|
|
number will be considered unused if there is no active array for that
|
|
number, and there is no entry in /dev for that number and with a
|
|
non-standard name.
|
|
|
|
.SH For assemble:
|
|
|
|
.TP
|
|
.BR -u ", " --uuid=
|
|
uuid of array to assemble. Devices which don't have this uuid are
|
|
excluded
|
|
|
|
.TP
|
|
.BR -m ", " --super-minor=
|
|
Minor number of device that array was created for. Devices which
|
|
don't have this minor number are excluded. If you create an array as
|
|
/dev/md1, then all superblocks will contain the minor number 1, even if
|
|
the array is later assembled as /dev/md2.
|
|
|
|
Giving the literal word "dev" for
|
|
.B --super-minor
|
|
will cause
|
|
.I mdadm
|
|
to use the minor number of the md device that is being assembled.
|
|
e.g. when assembling
|
|
.BR /dev/md0 ,
|
|
.M --super-minor=dev
|
|
will look for super blocks with a minor number of 0.
|
|
|
|
.TP
|
|
.BR -f ", " --force
|
|
Assemble the array even if some superblocks appear out-of-date
|
|
|
|
.TP
|
|
.BR -R ", " --run
|
|
Attempt to start the array even if fewer drives were given than are
|
|
needed for a full array. Normally if not all drives are found and
|
|
.B --scan
|
|
is not used, then the array will be assembled but not started.
|
|
With
|
|
.B --run
|
|
an attempt will be made to start it anyway.
|
|
|
|
.TP
|
|
.BR -a ", " "--auto{=no,yes,md,mdp,part}"
|
|
See this option under Create and Build options.
|
|
|
|
.TP
|
|
.BR -b ", " --bitmap=
|
|
Specify the bitmap file that was given when the array was created.
|
|
|
|
.TP
|
|
.BR -U ", " --update=
|
|
Update the superblock on each device while assembling the array. The
|
|
argument given to this flag can be one of
|
|
.BR sparc2.2 ,
|
|
.BR summaries ,
|
|
.BR resync ,
|
|
or
|
|
.BR super-minor .
|
|
|
|
The
|
|
.B sparc2.2
|
|
option will adjust the superblock of an array what was created on a Sparc
|
|
machine running a patched 2.2 Linux kernel. This kernel got the
|
|
alignment of part of the superblock wrong. You can use the
|
|
.B "--examine --sparc2.2"
|
|
option to
|
|
.I mdadm
|
|
to see what effect this would have.
|
|
|
|
The
|
|
.B super-minor
|
|
option will update the
|
|
.B "prefered minor"
|
|
field on each superblock to match the minor number of the array being
|
|
assembled. This is not needed on 2.6 and later kernels as they make
|
|
this adjustment automatically.
|
|
|
|
The
|
|
.B resync
|
|
option will cause the array to be marked
|
|
.I dirty
|
|
meaning that any redundancy in the array (e.g. parity for raid5,
|
|
copies for raid1) may be incorrect. This will cause the raid system
|
|
to perform a "resync" pass to make sure that all redundant information
|
|
is correct.
|
|
|
|
The
|
|
.B summaries
|
|
option will correct the summaries in the superblock. That is the
|
|
counts of total, working, active, failed, and spare devices.
|
|
|
|
.SH For Manage mode:
|
|
|
|
.TP
|
|
.BR -a ", " --add
|
|
'''add, or
|
|
hotadd listed devices.
|
|
|
|
.TP
|
|
.BR -r ", " --remove
|
|
remove listed devices. They must not be active. i.e. they should
|
|
be failed or spare devices.
|
|
|
|
.TP
|
|
.BR -f ", " --fail
|
|
mark listed devices as faulty.
|
|
|
|
.TP
|
|
.BR --set-faulty
|
|
same as --fail.
|
|
|
|
.SH For Examine mode:
|
|
|
|
.TP
|
|
.B --sparc2.2
|
|
In an array was created on a 2.2 Linux kernel patched with RAID
|
|
support, the superblock will have been created incorrectly, or at
|
|
least incompatibly with 2.4 and later kernels. Using the
|
|
.B --sparc2.2
|
|
flag with
|
|
.B --examine
|
|
will fix the superblock before displaying it. If this appears to do
|
|
the right thing, then the array can be successfully assembled using
|
|
.BR "--assemble --update=sparc2.2" .
|
|
|
|
.SH For Misc mode:
|
|
|
|
.TP
|
|
.BR -R ", " --run
|
|
start a partially built array.
|
|
|
|
.TP
|
|
.BR -S ", " --stop
|
|
deactivate array, releasing all resources.
|
|
|
|
.TP
|
|
.BR -o ", " --readonly
|
|
mark array as readonly.
|
|
|
|
.TP
|
|
.BR -w ", " --readwrite
|
|
mark array as readwrite.
|
|
|
|
.TP
|
|
.B --zero-superblock
|
|
If the device contains a valid md superblock, the block is
|
|
over-written with zeros. With
|
|
--force
|
|
the block where the superblock would be is over-written even if it
|
|
doesn't appear to be valid.
|
|
|
|
.TP
|
|
.BR -t ", " --test
|
|
When used with
|
|
.BR --detail ,
|
|
the exit status of
|
|
.I mdadm
|
|
is set to reflect the status of the device.
|
|
|
|
.SH For Monitor mode:
|
|
.TP
|
|
.BR -m ", " --mail
|
|
Give a mail address to send alerts to.
|
|
|
|
.TP
|
|
.BR -p ", " --program ", " --alert
|
|
Give a program to be run whenever an event is detected.
|
|
|
|
.TP
|
|
.BR -d ", " --delay
|
|
Give a delay in seconds.
|
|
.B mdadm
|
|
polls the md arrays and then waits this many seconds before polling
|
|
again. The default is 60 seconds.
|
|
|
|
.TP
|
|
.BR -f ", " --daemonise
|
|
Tell
|
|
.B mdadm
|
|
to run as a background daemon if it decides to monitor anything. This
|
|
causes it to fork and run in the child, and to disconnect form the
|
|
terminal. The process id of the child is written to stdout.
|
|
This is useful with
|
|
.B --scan
|
|
which will only continue monitoring if a mail address or alert program
|
|
is found in the config file.
|
|
|
|
.TP
|
|
.BR -i ", " --pid-file
|
|
When
|
|
.B mdadm
|
|
is running in daemon mode, write the pid of the daemon process to
|
|
the specified file, instead of printing it on standard output.
|
|
|
|
.TP
|
|
.BR -1 ", " --oneshot
|
|
Check arrays only once. This will generate
|
|
.B NewArray
|
|
events and more significantly
|
|
.B DegradedArray
|
|
events. Running
|
|
.in +5
|
|
.B " mdadm --monitor --scan -1"
|
|
.in -5
|
|
from a cron script will ensure regular notification of any degraded arrays.
|
|
|
|
.TP
|
|
.BR -t ", " --test
|
|
Generate a
|
|
.B TestMessage
|
|
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 to get through successfully.
|
|
|
|
.SH ASSEMBLE MODE
|
|
|
|
.HP 12
|
|
Usage:
|
|
.B mdadm --assemble
|
|
.I md-device options-and-component-devices...
|
|
.HP 12
|
|
Usage:
|
|
.B mdadm --assemble --scan
|
|
.I md-devices-and-options...
|
|
.HP 12
|
|
Usage:
|
|
.B mdadm --assemble --scan
|
|
.I options...
|
|
|
|
.PP
|
|
This usage assembles one or more raid arrays from pre-existing components.
|
|
For each array, mdadm needs to know the md device, the identity of the
|
|
array, and a number of component-devices. These can be found in a number of ways.
|
|
|
|
In the first usage example (without the
|
|
.BR --scan )
|
|
the first device given is the md device.
|
|
In the second usage example, all devices listed are treated as md
|
|
devices and assembly is attempted.
|
|
In the third (where no devices are listed) all md devices that are
|
|
listed in the configuration file are assembled.
|
|
|
|
If precisely one device is listed, but
|
|
.B --scan
|
|
is not given, then
|
|
.I mdadm
|
|
acts as though
|
|
.B --scan
|
|
was given and identify information is extracted from the configuration file.
|
|
|
|
The identity can be given with the
|
|
.B --uuid
|
|
option, with the
|
|
.B --super-minor
|
|
option, can be found in the config file, or will be taken from the
|
|
super block on the first component-device listed on the command line.
|
|
|
|
Devices can be given on the
|
|
.B --assemble
|
|
command line or in the config file. Only devices which have an md
|
|
superblock which contains the right identity will be considered for
|
|
any array.
|
|
|
|
The config file is only used if explicitly named with
|
|
.B --config
|
|
or requested with (a possibly implicit)
|
|
.B --scan.
|
|
In the later case,
|
|
.B /etc/mdadm.conf
|
|
is used.
|
|
|
|
If
|
|
.B --scan
|
|
is not given, then the config file will only be used to find the
|
|
identity of md arrays.
|
|
|
|
Normally the array will be started after it is assembled. However if
|
|
.B --scan
|
|
is not given and insufficient drives were listed to start a complete
|
|
(non-degraded) array, then the array is not started (to guard against
|
|
usage errors). To insist that the array be started in this case (as
|
|
may work for RAID1, 4, 5 or 6), give the
|
|
.B --run
|
|
flag.
|
|
|
|
If an
|
|
.B auto
|
|
option is given, either on the command line (--auto) or in the
|
|
configuration file (e.g. auto=part), then
|
|
.I mdadm
|
|
will create the md device if necessary or will re-create it if it
|
|
doesn't look usable as it is.
|
|
|
|
This can be useful for handling partitioned devices (which don't have
|
|
a stable device number - it can change after a reboot) and when using
|
|
"udev" to manage your
|
|
.B /dev
|
|
tree (udev cannot handle md devices because of the unusual device
|
|
initialisation conventions).
|
|
|
|
If the option to "auto" is "mdp" or "part" or (on the command line
|
|
only) "p", then mdadm will create a partitionable array, using the
|
|
first free one that is not inuse, and does not already have an entry
|
|
in /dev (apart from numeric /dev/md* entries).
|
|
|
|
If the option to "auto" is "yes" or "md" or (on the command line)
|
|
nothing, then mdadm will create a traditional, non-partitionable md
|
|
array.
|
|
|
|
It is expected that the "auto" functionality will be used to create
|
|
device entries with meaningful names such as "/dev/md/home" or
|
|
"/dev/md/root", rather than names based on the numerical array number.
|
|
|
|
When using this option to create a partitionable array, the device
|
|
files for the first 4 partitions are also created. If a different
|
|
number is required it can be simply appended to the auto option.
|
|
e.g. "auto=part8". Partition names are created by appending a digit
|
|
string to the device name, with an intervening "_p" if the device name
|
|
ends with a digit.
|
|
|
|
The
|
|
.B --auto
|
|
option is also available in Build and Create modes. As those modes do
|
|
not use a config file, the "auto=" config option does not apply to
|
|
these modes.
|
|
|
|
.SH BUILD MODE
|
|
|
|
.HP 12
|
|
Usage:
|
|
.B mdadm --build
|
|
.I device
|
|
.BI --chunk= X
|
|
.BI --level= Y
|
|
.BI --raid-devices= Z
|
|
.I devices
|
|
|
|
.PP
|
|
This usage is similar to
|
|
.BR --create .
|
|
The difference is that it creates a legacy array without a superblock. With
|
|
these arrays there is no difference between initially creating the array and
|
|
subsequently assembling the array, except that hopefully there is useful
|
|
data there in the second case.
|
|
|
|
The level may only be 0, raid0, or linear. All devices must be listed
|
|
and the array will be started once complete.
|
|
|
|
.SH CREATE MODE
|
|
|
|
.HP 12
|
|
Usage:
|
|
.B mdadm --create
|
|
.I device
|
|
.BI --chunk= X
|
|
.BI --level= Y
|
|
.br
|
|
.BI --raid-devices= Z
|
|
.I devices
|
|
|
|
.PP
|
|
This usage will initialise a new md array, associate some devices with
|
|
it, and activate the array.
|
|
|
|
This the
|
|
.B --auto
|
|
option is given (as described in more detail in the section on
|
|
Assemble mode), then the md device will be created with a suitable
|
|
device number if necessary.
|
|
|
|
As devices are added, they are checked to see if they contain raid
|
|
superblocks or filesystems. They are also checked to see if the variance in
|
|
device size exceeds 1%.
|
|
|
|
If any discrepancy is found, the array will not automatically be run, though
|
|
the presence of a
|
|
.B --run
|
|
can override this caution.
|
|
|
|
To create a "degraded" array in which some devices are missing, simply
|
|
give the word "\fBmissing\fP"
|
|
in place of a device name. This will cause
|
|
.B mdadm
|
|
to leave the corresponding slot in the array empty.
|
|
For a RAID4 or RAID5 array at most one slot can be
|
|
"\fBmissing\fP"; for a RAID6 array at most two slots.
|
|
For a RAID1 array, only one real device needs to be given. All of the
|
|
others can be
|
|
"\fBmissing\fP".
|
|
|
|
When creating a RAID5 array,
|
|
.B mdadm
|
|
will automatically create a degraded array with an extra spare drive.
|
|
This is because building the spare into a degraded array is in general faster than resyncing
|
|
the parity on a non-degraded, but not clean, array. This feature can
|
|
be over-ridden with the
|
|
.I --force
|
|
option.
|
|
|
|
'''If the
|
|
'''.B --size
|
|
'''option is given, it is not necessary to list any component-devices in this command.
|
|
'''They can be added later, before a
|
|
'''.B --run.
|
|
'''If no
|
|
'''.B --size
|
|
'''is given, the apparent size of the smallest drive given is used.
|
|
|
|
The General Management options that are valid with --create are:
|
|
.TP
|
|
.B --run
|
|
insist on running the array even if some devices look like they might
|
|
be in use.
|
|
|
|
.TP
|
|
.B --readonly
|
|
start the array readonly - not supported yet.
|
|
|
|
.SH MANAGE MODE
|
|
.HP 12
|
|
Usage:
|
|
.B mdadm
|
|
.I device
|
|
.I options... devices...
|
|
.PP
|
|
|
|
This usage will allow individual devices in an array to be failed,
|
|
removed or added. It is possible to perform multiple operations with
|
|
on command. For example:
|
|
.br
|
|
.B " mdadm /dev/md0 -f /dev/hda1 -r /dev/hda1 -a /dev/hda1"
|
|
.br
|
|
will firstly mark
|
|
.B /dev/hda1
|
|
as faulty in
|
|
.B /dev/md0
|
|
and will then remove it from the array and finally add it back
|
|
in as a spare. However only one md array can be affected by a single
|
|
command.
|
|
|
|
.SH MISC MODE
|
|
.HP 12
|
|
Usage:
|
|
.B mdadm
|
|
.I options ...
|
|
.I devices ...
|
|
.PP
|
|
|
|
MISC mode includes a number of distinct operations that
|
|
operate on distinct devices. The operations are:
|
|
.TP
|
|
--query
|
|
The device is examined to see if it is
|
|
(1) an active md array, or
|
|
(2) a component of an md array.
|
|
The information discovered is reported.
|
|
|
|
.TP
|
|
--detail
|
|
The device should be an active md device.
|
|
.B mdadm
|
|
will display a detailed description of the array.
|
|
.B --brief
|
|
or
|
|
.B --scan
|
|
will cause the output to be less detailed and the format to be
|
|
suitable for inclusion in
|
|
.BR /etc/mdadm.conf .
|
|
The exit status of
|
|
.I mdadm
|
|
will normally be 0 unless
|
|
.I mdadm
|
|
failed to get useful information about the device(s). However if the
|
|
.B --test
|
|
option is given, then the exit status will be:
|
|
.RS
|
|
.TP
|
|
0
|
|
The array is functioning normally.
|
|
.TP
|
|
1
|
|
The array has at least one failed device.
|
|
.TP
|
|
2
|
|
The array has multiple failed devices and hence is unusable (raid4 or
|
|
raid5).
|
|
.TP
|
|
4
|
|
There was an error while trying to get information about the device.
|
|
.RE
|
|
|
|
.TP
|
|
--examine
|
|
The device should be a component of an md array.
|
|
.B mdadm
|
|
will read the md superblock of the device and display the contents.
|
|
If
|
|
.B --brief
|
|
is given, or
|
|
.B --scan
|
|
then multiple devices that are components of the one array
|
|
are grouped together and reported in a single entry suitable
|
|
for inclusion in
|
|
.BR /etc/mdadm.conf .
|
|
|
|
Having
|
|
.B --scan
|
|
without listing any devices will cause all devices listed in the
|
|
config file to be examined.
|
|
|
|
.TP
|
|
--stop
|
|
The devices should be active md arrays which will be deactivated, as
|
|
long as they are not currently in use.
|
|
|
|
.TP
|
|
--run
|
|
This will fully activate a partially assembled md array.
|
|
|
|
.TP
|
|
--readonly
|
|
This will mark an active array as read-only, providing that it is
|
|
not currently being used.
|
|
|
|
.TP
|
|
--readwrite
|
|
This will change a
|
|
.B readonly
|
|
array back to being read/write.
|
|
|
|
.TP
|
|
--scan
|
|
For all operations except
|
|
.BR --examine ,
|
|
.B --scan
|
|
will cause the operation to be applied to all arrays listed in
|
|
.BR /proc/mdstat .
|
|
For
|
|
.BR --examine,
|
|
.B --scan
|
|
causes all devices listed in the config file to be examined.
|
|
|
|
|
|
.SH MONITOR MODE
|
|
|
|
.HP 12
|
|
Usage:
|
|
.B mdadm --monitor
|
|
.I options... devices...
|
|
|
|
.PP
|
|
This usage causes
|
|
.B mdadm
|
|
to periodically poll a number of md arrays and to report on any events
|
|
noticed.
|
|
.B mdadm
|
|
will never exit once it decides that there are arrays to be checked,
|
|
so it should normally be run in the background.
|
|
|
|
As well as reporting events,
|
|
.B mdadm
|
|
may move a spare drive from one array to another if they are in the
|
|
same
|
|
.B spare-group
|
|
and if the destination array has a failed drive but not spares.
|
|
|
|
If any devices are listed on the command line,
|
|
.B mdadm
|
|
will only monitor those devices. Otherwise all arrays listed in the
|
|
configuration file will be monitored. Further, if
|
|
.B --scan
|
|
is given, then any other md devices that appear in
|
|
.B /proc/mdstat
|
|
will also be monitored.
|
|
|
|
The result of monitoring the arrays is the generation of events.
|
|
These events are passed to a separate program (if specified) and may
|
|
be mailed to a given E-mail address.
|
|
|
|
When passing event to program, the program is run once for each event
|
|
and is given 2 or 3 command-line arguements. The first is the
|
|
name of the event (see below). The second is the name of the
|
|
md device which is affected, and the third is the name of a related
|
|
device if relevant, such as a component device that has failed.
|
|
|
|
If
|
|
.B --scan
|
|
is given, then a program or an E-mail address must be specified on the
|
|
command line or in the config file. If neither are available, then
|
|
.B mdadm
|
|
will not monitor anything.
|
|
Without
|
|
.B --scan
|
|
.B mdadm
|
|
will continue monitoring as long as something was found to monitor. If
|
|
no program or email is given, then each event is reported to
|
|
.BR stdout .
|
|
|
|
The different events are:
|
|
|
|
.RS 4
|
|
.TP
|
|
.B DeviceDisappeared
|
|
An md array which previously was configured appears to no longer be
|
|
configured.
|
|
|
|
.TP
|
|
.B RebuildStarted
|
|
An md array started reconstruction.
|
|
|
|
.TP
|
|
.BI Rebuild NN
|
|
Where
|
|
.I NN
|
|
is 20, 40, 60, or 80, this indicates that rebuild has passed that many
|
|
percentage of the total.
|
|
|
|
.TP
|
|
.B RebuildFinished
|
|
An md array that was rebuilding, isn't any more, either because it
|
|
finished normally or was aborted.
|
|
|
|
.TP
|
|
.B Fail
|
|
An active component device of an array has been marked as faulty.
|
|
|
|
.TP
|
|
.B FailSpare
|
|
A spare component device which was being rebuilt to replace a faulty
|
|
device has failed.
|
|
|
|
.TP
|
|
.B SpareActive
|
|
A spare component device which was being rebuilt to replace a faulty
|
|
device as been successfully rebuild and has been made active.
|
|
|
|
.TP
|
|
.B NewArray
|
|
A new md array has been detected in the
|
|
.B /proc/mdstat
|
|
file.
|
|
|
|
.TP
|
|
.B DegradedArray
|
|
A newly noticed array appears to be degraded. This message is not
|
|
generated when
|
|
.I mdadm
|
|
notices a drive failure which causes degradation, but only when
|
|
.I mdadm
|
|
notices that an array is degraded when it first sees the array.
|
|
|
|
.TP
|
|
.B MoveSpare
|
|
A spare drive has been moved from one array in a
|
|
.B spare-group
|
|
to another to allow a failed drive to be replaced.
|
|
|
|
.TP
|
|
.B TestMessage
|
|
An array was found at startup, and the
|
|
.B --test
|
|
flag was given.
|
|
.RE
|
|
|
|
Only
|
|
.B Fail ,
|
|
.B FailSpare ,
|
|
.B DegradedArray ,
|
|
and
|
|
.B TestMessage
|
|
cause Email to be sent. All events cause the program to be run.
|
|
The program is run with two or three arguments, they being the event
|
|
name, the array device and possibly a second device.
|
|
|
|
Each event has an associated array device (e.g.
|
|
.BR /dev/md1 )
|
|
and possibly a second device. For
|
|
.BR Fail ,
|
|
.BR FailSpare ,
|
|
and
|
|
.B SpareActive
|
|
the second device is the relevant component device.
|
|
For
|
|
.B MoveSpare
|
|
the second device is the array that the spare was moved from.
|
|
|
|
For
|
|
.B mdadm
|
|
to move spares from one array to another, the different arrays need to
|
|
be labelled with the same
|
|
.B spare-group
|
|
in the configuration file. The
|
|
.B spare-group
|
|
name can be any string. It is only necessary that different spare
|
|
groups use different names.
|
|
|
|
When
|
|
.B mdadm
|
|
detects that an array which is in a spare group has fewer active
|
|
devices than necessary for the complete array, and has no spare
|
|
devices, it will look for another array in the same spare group that
|
|
has a full complement of working drive and a spare. It will then
|
|
attempt to remove the spare from the second drive and add it to the
|
|
first.
|
|
If the removal succeeds but the adding fails, then it is added back to
|
|
the original array.
|
|
|
|
.SH GROW MODE
|
|
The GROW mode is used for changing the size or shape of an active
|
|
array.
|
|
For this to work, the kernel must support the necessary change.
|
|
Various types of growth may be added during 2.6 development, possibly
|
|
including restructuring a raid5 array to have more active devices.
|
|
|
|
Currently the only support available is to change the "size" attribute
|
|
for arrays with redundancy, and the raid-disks attribute of RAID1
|
|
arrays.
|
|
|
|
Normally when an array is build the "size" it taken from the smallest
|
|
of the drives. If all the small drives in an arrays are, one at a
|
|
time, removed and replaced with larger drives, then you could have an
|
|
array of large drives with only a small amount used. In this
|
|
situation, changing the "size" with "GROW" mode will allow the extra
|
|
space to start being used. If the size is increased in this way, a
|
|
"resync" process will start to make sure the new parts of the array
|
|
are synchronised.
|
|
|
|
Note that when an array changes size, any filesystem that may be
|
|
stored in the array will not automatically grow to use the space. The
|
|
filesystem will need to be explicitly told to use the extra space.
|
|
|
|
A RAID1 array can work with any number of devices from 1 upwards
|
|
(though 1 is not very useful). There may be times which you want to
|
|
increase or decrease the number of active devices. Note that this is
|
|
different to hot-add or hot-remove which changes the number of
|
|
inactive devices.
|
|
|
|
When reducing the number of devices in a RAID1 array, the slots which
|
|
are to be removed from the array must already be vacant. That is, the
|
|
devices that which were in those slots must be failed and removed.
|
|
|
|
When the number of devices is increased, any hot spares that are
|
|
present may be activated immediately.
|
|
|
|
.SH EXAMPLES
|
|
|
|
.B " mdadm --query /dev/name-of-device"
|
|
.br
|
|
This will find out if a given device is a raid array, or is part of
|
|
one, and will provide brief information about the device.
|
|
|
|
.B " mdadm --assemble --scan"
|
|
.br
|
|
This will assemble and start all arrays listed in the standard confile
|
|
file. This command will typically go in a system startup file.
|
|
|
|
.B " mdadm --stop --scan"
|
|
.br
|
|
This will shut down all array that can be shut down (i.e. are not
|
|
currently in use). This will typically go in a system shutdown script.
|
|
|
|
.B " mdadm --follow --scan --delay=120"
|
|
.br
|
|
If (and only if) there is an Email address or program given in the
|
|
standard config file, then
|
|
monitor the status of all arrays listed in that file by
|
|
polling them ever 2 minutes.
|
|
|
|
.B " mdadm --create /dev/md0 --level=1 --raid-devices=2 /dev/hd[ac]1"
|
|
.br
|
|
Create /dev/md0 as a RAID1 array consisting of /dev/hda1 and /dev/hdc1.
|
|
|
|
.br
|
|
.B " echo 'DEVICE /dev/hd*[0-9] /dev/sd*[0-9]' > mdadm.conf"
|
|
.br
|
|
.B " mdadm --detail --scan >> mdadm.conf"
|
|
.br
|
|
This will create a prototype config file that describes currently
|
|
active arrays that are known to be made from partitions of IDE or SCSI drives.
|
|
This file should be reviewed before being used as it may
|
|
contain unwanted detail.
|
|
|
|
.B " echo 'DEVICE /dev/hd[a-z] /dev/sd*[a-z]' > mdadm.conf"
|
|
.br
|
|
.B " mdadm --examine --scan --config=mdadm.conf >> mdadm.conf"
|
|
.ber
|
|
This will find what arrays could be assembled from existign IDE and
|
|
SCSI whole drives (not partitions) and store the information is the
|
|
format of a config file.
|
|
This file is very likely to contain unwanted detail, particularly
|
|
the
|
|
.B devices=
|
|
entries. It should be reviewed and edited before being used as an
|
|
actual config file.
|
|
|
|
.B " mdadm --examine --brief --scan --config=partitions"
|
|
.br
|
|
.B " mdadm -Ebsc partitions"
|
|
.br
|
|
Create a list of devices by reading
|
|
.BR /proc/partitions ,
|
|
scan these for RAID superblocks, and printout a brief listing of all
|
|
that was found.
|
|
|
|
.B " mdadm -Ac partitions -m 0 /dev/md0"
|
|
.br
|
|
Scan all partitions and devices listed in
|
|
.BR /proc/partitions
|
|
and assemble
|
|
.B /dev/md0
|
|
out of all such devices with a RAID superblock with a minor number of 0.
|
|
|
|
.B " mdadm --monitor --scan --daemonise > /var/run/mdadm"
|
|
.br
|
|
If config file contains a mail address or alert program, run mdadm in
|
|
the background in monitor mode monitoring all md devices. Also write
|
|
pid of mdadm daemon to
|
|
.BR /var/run/mdadm .
|
|
|
|
.B " mdadm --create --help"
|
|
.br
|
|
Providew help about the Create mode.
|
|
|
|
.B " mdadm --config --help"
|
|
.br
|
|
Provide help about the format of the config file.
|
|
|
|
.B " mdadm --help"
|
|
.br
|
|
Provide general help.
|
|
|
|
|
|
.SH FILES
|
|
|
|
.SS /proc/mdstat
|
|
|
|
If you're using the
|
|
.B /proc
|
|
filesystem,
|
|
.B /proc/mdstat
|
|
lists all active md devices with information about them.
|
|
.B mdadm
|
|
uses this to find arrays when
|
|
.B --scan
|
|
is given in Misc mode, and to monitor array reconstruction
|
|
on Monitor mode.
|
|
|
|
|
|
.SS /etc/mdadm.conf
|
|
|
|
The config file lists which devices may be scanned to see if
|
|
they contain MD super block, and gives identifying information
|
|
(e.g. UUID) about known MD arrays. See
|
|
.BR mdadm.conf (5)
|
|
for more details.
|
|
|
|
.SH DEVICE NAMES
|
|
|
|
While entries in the /dev directory can have any format you like,
|
|
.I mdadm
|
|
has an understanding of 'standard' formats which it uses to guide its
|
|
behaviour when creating device files via the
|
|
.I --auto
|
|
option.
|
|
|
|
The standard names for non-partitioned arrays (the only sort of md
|
|
array available in 2.4 and earlier) either of
|
|
.IP
|
|
/dev/mdNN
|
|
.br
|
|
/dev/md/NN
|
|
.PP
|
|
where NN is a number.
|
|
The standard names for partitionable arrays (as available from 2.6
|
|
onwards) is one of
|
|
.IP
|
|
/dev/md/dNN
|
|
.br
|
|
/dev/md_dNN
|
|
.PP
|
|
Partition numbers should be indicated by added "pMM" to these, thus "/dev/md/d1p2".
|
|
|
|
.SH NOTE
|
|
.B mdadm
|
|
was previously known as
|
|
.BR mdctl .
|
|
|
|
.SH SEE ALSO
|
|
For information on the various levels of
|
|
RAID, check out:
|
|
|
|
.IP
|
|
.UR http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
|
|
http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
|
|
.UE
|
|
.PP
|
|
for new releases of the RAID driver check out:
|
|
|
|
.IP
|
|
.UR ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
|
|
ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
|
|
.UE
|
|
.PP
|
|
or
|
|
.IP
|
|
.UR http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
|
|
http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
|
|
.URk
|
|
.PP
|
|
.BR mdadm.conf (5),
|
|
.BR md (4).
|
|
.PP
|
|
.IR raidtab (5),
|
|
.IR raid0run (8),
|
|
.IR raidstop (8),
|
|
.IR mkraid (8)
|