.\" -*- nroff -*-
-.TH MDADM 8 "" v1.6.0
+.TH MDADM 8 "" v2.0-devel-1
.SH NAME
mdadm \- manage MD devices
.I aka
.BR RAID4 ,
.BR RAID5 ,
.BR RAID6 ,
+.BR MULTIPATH ,
and
-.BR MULTIPATH .
+.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
.TP
.B Build
-Build a legacy array without per-device superblocks.
+Build an array without per-device superblocks.
.TP
.B Create
.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
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
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
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. Obviously some of these are synonymous.
+raid5, 5, raid6, 6, multipath, mp, fautly. Obviously some of these are synonymous.
When used with
.IR --build ,
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
than the currently active drives, the extra space can be accessed
using
.BR --grow .
+The size can be given as
+.B max
+which means to choose the largest size that fits all on all current drives.
.TP
.BR --assume-clean
.TP
.BR -a ", " "--auto{=no,yes,md,mdp,part,p}{NN}"
-Instruct mdadm to create the device file if needed, and to allocate
-an unused minor number. "yes" or "md" causes a non-partitionable array
+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. The argumentment can also come immediately after
+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".
+If
+.I --scan
+is also given, then any
+.I auto=
+entries in the config file will over-ride the
+.I --auto
+instruction given on the command line.
+
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 an
-underscore, a 'p', and a number, e.g. "/dev/home1_p3". If there is no
+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 -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 .
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
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
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
+.I --force
option.
'''If the
.I devices ...
.PP
-MISC mode includes a number if distinct operations that
+MISC mode includes a number of distinct operations that
operate on distinct devices. The operations are:
.TP
--query
An md array which previously was configured appears to no longer be
configured.
+If
+.I mdadm
+was told to monitor an array which is RAID0 or Linear, then it will
+report
+.B DeviceDisappeared
+with the extra information
+.BR Wrong-Level .
+This is because RAID0 and Linear do not support the device-failed,
+hot-spare and resync operations which are monitored.
+
.TP
.B RebuildStarted
An md array started reconstruction.
.B spare-group
to another to allow a failed drive to be replaced.
+.TP
+.B SparesMissing
+If
+.I mdadm
+has been told, via the config file, that an array should have a certain
+number of spare devices, and
+.I mdadm
+detects that it has fewer that this number when it first sees the
+array, it will report a
+.B SparesMissing
+message.
+
.TP
.B TestMessage
An array was found at startup, and the
.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.
+currently in use). This will typically go in a system shutdown script.
.B " mdadm --follow --scan --delay=120"
.br
.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