.\" -*- nroff -*-
-.TH MDADM 8
+.TH MDADM 8 "" v1.2.0
.SH NAME
mdadm \- manage MD devices
.I aka
(striping),
.B RAID1
(mirroring),
-.B RAID4
+.BR RAID4 ,
+.BR RAID5 ,
and
-.B RAID5.
-
-Recent kernels (2002) also support a mode known as
.BR MULTIPATH .
-.B mdadm
-only provides limited support for MULTIPATH as yet.
+
+.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 mdadm
is a program that can be used to create, manage, and monitor
.IP \(bu 4
.B mdadm
can perform (almost) all of its functions without having a
-configuration file. Also
+configuration file and does not use one by default. Also
.B mdadm
helps with management of the configuration
file.
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 6 major modes of operation:
.TP
.B "Follow or Monitor"
-Monitor one or more md devices and act on any state changes.
+Monitor one or more md devices and act on any state changes. This is
+only meaningful for raid1, raid5 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.
+
.SH OPTIONS
.TP
.BR -h ", " --help
-Display help message or, after above option, mode specific help message.
+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
.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
.TP
.BR -n ", " --raid-devices=
-number of active devices in array.
+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.
.TP
.BR -x ", " --spare-devices=
-number of spare (eXtra) devices in initial array. Spares can be added
-and removed later.
+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=
/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
.B --run
an attempt will be made to start it anyway.
+.TP
+.BR -U ", " --update=
+Update the superblock on each device while assembling the array. The
+argument given to this flag can be either
+.B sparc2.2
+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 need on 2.6 and later kernels as they make
+this adjustment automatically.
+
+
.SH For Manage mode:
.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
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.
+
.SH ASSEMBLE MODE
.HP 12
Usage:
.B mdadm --assemble
-.I device options...
+.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
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.
-The md device is either given before
+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, that
+.I mdadm
+acts as though
.B --scan
-or is found from the config file. In the latter case, multiple md devices
-can be started with a single mdadm command.
+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 in the config file, or will be taken from the
+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 from the config file. Only devices which have an md
-superblock which contains the right identity will be considered for any device.
+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
+or requested with (a possibly implicit)
.B --scan.
In the later case,
.B /etc/mdadm.conf
can override this caution.
To create a "degraded" array in which some devices are missing, simply
-give the word
-.B missing
+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
-.BR missing .
+"\fBmissing\fP".
For a RAID1 array, only one real device needs to be given. All of the
others can be
-.BR missing .
+"\fBmissing\fP".
'''If the
'''.B --size
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"
+.B " mdadm /dev/md0 -f /dev/hda1 -r /dev/hda1 -a /dev/hda1"
.br
will firstly mark
.B /dev/hda1
.SH EXAMPLES
-To find out if a devices is a raid array or part of one:
+.B " mdadm --query /dev/name-of-device"
.br
-.B " mdadm -Q /dev/name-of-device"
+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.
-To assemble and start all array listed in the standard config file:
+.B " mdadm --assemble --scan"
.br
-.B " mdadm -As"
+This will assemble and start all arrays listed in the standard confile
+file. This command will typically go in a system startup file.
-To shut down all arrays (that are not still in used):
-.br
.B " mdadm --stop --scan"
+.br
+This will shut down all array that can be shut down (i.e. are not
+currently in used). This will typically going in a system shutdown script.
-To monitor all arrays if (and only if) an email address or program
-was given in the config file, but poll every 2 minutes:
+.B " mdadm --follow --scan --delay=120"
.br
-.B " mdadm -Fs --delay=120"
+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.
-To create /dev/md0 as a RAID1 array with /dev/hda1 and /dev/hdc1:
+.B " mdadm --create /dev/md0 --level=1 --raid-devices=2 /dev/hd[ac]1"
.br
-.B " mdadm -C /dev/md0 -l1 -n2 /dev/hd[ac]1"
+Create /dev/md0 as a RAID1 array consisting of /dev/hda1 and /dev/hdc1.
-To create prototype a config file that describes currently
-active arrays that are known to be made from partitions of
-IDE or SCSI drives:
.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.
-To find out what raid arrays could be assembled from existing
-IDE and SCSI whole drives (not partitions):
-.br
.B " echo 'DEVICE /dev/hd[a-z] /dev/sd*[a-z]' > mdadm.conf"
.br
-.B " mdadm -Es -c mdadm.conf >> mdadm.conf"
+.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.
+entries. It should be reviewed and edited before being used as an
+actual config file.
-To get help about Create mode:
+.B " mdadm --examine --brief --scan --config=partitions"
.br
-.B " mdadm --create --help"
+.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.
-To get help about the format of the config file:
+.B " mdadm -Ac partitions -m 0 /dev/md0"
.br
-.B " mdadm --config --help"
+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.
-To get general help:
+.B " mdadm --monitor --scan --daemonise > /var/run/mdadm"
.br
-.B " mdadm --help"
+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