''' 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 8 "" v2.5.3
+.TH MDADM 8 "" v2.6.1
.SH NAME
mdadm \- manage MD devices
.I aka
.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
+drives or partitions thereof) 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.
'''with a different format and a different purpose.
.SH MODES
-mdadm has 7 major modes of operation:
+mdadm has several major modes of operation:
.TP
.B Assemble
Assemble the parts of a previously created
Grow (or shrink) an array, or otherwise reshape it in some way.
Currently supported growth options including changing the active size
of component devices in RAID level 1/4/5/6 and changing the number of
-active devices in RAID1.
+active devices in RAID1/5/6.
+
+.TP
+.B "Incremental Assembly"
+Add a single device to an appropriate array. If the addition of the
+device makes the array runnable, the array will be started.
+This provides a convenient interface to a
+.I hot-plug
+system. As each device is detected,
+.I mdadm
+has a chance to include it in some array as appropriate.
.TP
.B Manage
.TP
.BR -G ", " --grow
Change the size or shape of an active array.
+
+.TP
+.BE -I ", " --incremental
+Add a single device into an appropriate array, and possibly start the array.
+
.P
If a device is given before any options, or if the first option is
.BR --add ,
.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.
+The default can be overridden by setting the
+.B metadata
+value for the
+.B CREATE
+keyword in
+.BR mdadm.conf .
Options are:
.RS
.TP
.B --homehost=
-This will over-ride any
+This will override any
.B HOMEHOST
setting in the config file and provides the identify of the host which
should be considered the home for any arrays.
.br
This number can only be changed using
.B --grow
-for RAID1 arrays, and only on kernels which provide necessary support.
+for RAID1, RAID5 and RAID6 arrays, and only on kernels which provide
+necessary support.
.TP
.BR -x ", " --spare-devices=
The argument can also come immediately after
"-a". e.g. "-ap".
+If --auto is not given on the command line or in the config file, then
+the default will be
+.BR --auto=yes .
+
If
.I --scan
is also given, then any
.I auto=
-entries in the config file will over-ride the
+entries in the config file will override the
.I --auto
instruction given on the command line.
.BR homehost ,
.BR resync ,
.BR byteorder ,
+.BR devicesize ,
or
.BR super-minor .
option will correct the summaries in the superblock. That is the
counts of total, working, active, failed, and spare devices.
+The
+.B devicesize
+will rarely be of use. It applies to version 1.1 and 1.2 metadata
+only (where the metadata is at the start of the device) and is only
+useful when the component device has changed size (typically become
+larger). The version 1 metadata records the amount of the device that
+can be used to store data, so if a device in a version 1.1 or 1.2
+array becomes larger, the metadata will still be visible, but the
+extra space will not. In this case it might be useful to assemble the
+array with
+.BR --update=devicesize .
+This will cause
+.I mdadm
+to determine the maximum usable amount of space on each device and
+update the relevant field in the metadata.
+
.TP
.B --auto-update-homehost
This flag is only meaning with auto-assembly (see discussion below).
.TP
.B --zero-superblock
If the device contains a valid md superblock, the block is
-over-written with zeros. With
+overwritten with zeros. With
--force
-the block where the superblock would be is over-written even if it
+the block where the superblock would be is overwritten even if it
doesn't appear to be valid.
.TP
.I mdadm
is set to reflect the status of the device.
+.TP
+.BR -W ", " --wait
+For each md device given, wait for any resync, recovery, or reshape
+activity to finish before returning.
+.I mdadm
+will return with success if it actually waited for every device
+listed, otherwise it will return failure.
+
+.SH For Incremental Assembly mode:
+.TP
+.BR --rebuild-map ", " -r
+Rebuild the map file
+.RB ( /var/run/mdadm/map )
+that
+.I mdadm
+uses to help track which arrays are currently being assembled.
+
+.TP
+.BR --run ", " -R
+Run any array assembled as soon as a minimal number of devices are
+available, rather than waiting until all expected devices are present.
+
+.TP
+.BR --scan ", " -s
+Only meaningful with
+.B -R
+this will scan the
+.B map
+file for arrays that are being incrementally assembled and will try to
+start any that are not already started. If any such array is listed
+in
+.B mdadm.conf
+as requiring an external bitmap, that bitmap will be attached first.
+
.SH For Monitor mode:
.TP
.BR -m ", " --mail
.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.
+If the md device does not exist, then it will be created providing the
+intent is clear. i.e. the name must be in a standard form, or the
+.I --auto
+option must be given to clarify how and whether the device should be
+created.
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
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
+be overridden with the
.I --force
option.
.B home
will be used.
+A new array will normally get a randomly assigned 128bit UUID which is
+very likely to be unique. If you have a specific need, you can choose
+a UUID for the array by giving the
+.B --uuid=
+option. Be warned that creating two arrays with the same UUID is a
+recipe for disaster. Also, using
+.B --uuid=
+when creating a v0.90 array will silently override any
+.B --homehost=
+setting.
'''If the
'''.B --size
'''option is given, it is not necessary to list any component-devices in this command.
change the "size" attribute
for RAID1, RAID5 and RAID6.
.IP \(bu 4
-increase the "raid-disks" attribute of RAID1 and RAID5.
+increase the "raid-disks" attribute of RAID1, RAID5, and RAID6.
.IP \(bu 4
add a write-intent bitmap to any array which support these bitmaps, or
remove a write-intent bitmap from such an array.
in a filesystem that is on the raid array being affected, the system
will deadlock. The bitmap must be on a separate filesystem.
+.SH INCREMENTAL MODE
+
+.HP 12
+Usage:
+.B mdadm --incremental
+.RB [ --run ]
+.RB [ --quiet ]
+.I component-device
+.HP 12
+Usage:
+.B mdadm --incremental --rebuild
+.HP 12
+Usage:
+.B mdadm --incremental --run --scan
+
+
+.PP
+This mode is designed to be used in conjunction with a device
+discovery system. As devices are found in a system, they can be
+passed to
+.B "mdadm --incremental"
+to be conditionally added to an appropriate array.
+
+.I mdadm
+performs a number of tests to determine if the device is part of an
+array, and which array is should be part of. If an appropriate array
+is found, or can be created,
+.I mdadm
+adds the device to the array and conditionally starts the array.
+
+Note that
+.I mdadm
+will only add devices to an array which were previously working
+(active or spare) parts of that array. It does not currently support
+automatic inclusion of a new drive as a spare in some array.
+
+.B "mdadm --incremental"
+requires a bug present in all kernels through 2.6.19, to be fixed.
+Hopefully this will be fixed in 2.6.20. Alternately apply the patch
+which is included with the mdadm source distribution. If
+.I mdadm
+detects that this bug is present, it will abort any attempt to use
+.BR --incremental .
+
+The tests that
+.I mdadm
+makes are as follow:
+.IP +
+Is the device permitted by
+.BR mdadm.conf ?
+That is, is it listed in a
+.B DEVICES
+line in that file. If
+.B DEVICES
+is absent then the default it to allow any device. Similar if
+.B DEVICES
+contains the special word
+.B partitions
+then any device is allowed. Otherwise the device name given to
+.I mdadm
+must match one of the names or patterns in a
+.B DEVICES
+line.
+
+.IP +
+Does the device have a valid md superblock. If a specific metadata
+version is request with
+.B --metadata
+or
+.B -e
+then only that style of metadata is accepted, otherwise
+.I mdadm
+finds any known version of metadata. If no
+.I md
+metadata is found, the device is rejected.
+
+.IP +
+Does the metadata match an expected array?
+The metadata can match in two ways. Either there is an array listed
+in
+.B mdadm.conf
+which identifies the array (either by UUID, by name, by device list,
+or by minor-number), the array was created with a
+.B homehost
+specified, and that
+.B homehost
+matches that which is given in
+.B mdadm.conf
+or on the command line.
+If
+.I mdadm
+is not able to positively identify the array as belonging to the
+current host, the device will be rejected.
+
+.IP +
+.I mdadm
+keeps a list of arrays that is has partly assembled in
+.B /var/run/mdadm/map
+(or
+.B /var/run/mdadm.map
+if the directory doesn't exist). If no array exists which matches
+the metadata on the new device,
+.I mdadm
+must choose a device name and unit number. It does this based on any
+name given in
+.B mdadm.conf
+or any name information stored in the metadata. If this name
+suggests a unit number, that number will be used, otherwise a free
+unit number will be chosen. Normally
+.I mdadm
+will prefer to create a partitionable array, however if the
+.B CREATE
+line in
+.B mdadm.conf
+suggests that a non-partitionable array is preferred, that will be
+honoured.
+
+.IP +
+Once an appropriate array is found or created and the device is added,
+.I mdadm
+must decide if the array is ready to be started. It will
+normally compare the number of available (non-spare) devices to the
+number of devices that the metadata suggests need to be active. If
+there are at least that many, the array will be started. This means
+that if any devices are missing the array will not be restarted.
+
+As an alternative,
+.B --run
+may be passed to
+.B mdadm
+in which case the array will be run as soon as there are enough
+devices present for the data to be accessible. For a raid1, that
+means one device will start the array. For a clean raid5, the array
+will be started as soon as all but one drive is present.
+
+Note that neither of these approaches is really ideal. If it is can
+be known that all device discovery has completed, then
+.br
+.B " mdadm -IRs"
+.br
+can be run which will try to start all arrays that are being
+incrementally assembled. They are started in "read-auto" mode in
+which they are read-only until the first write request. This means
+that no metadata updates are made and no attempt at resync or recovery
+happens. Further devices that are found before the first write can
+still be added safely.
+
.SH EXAMPLES
.B " mdadm --query /dev/name-of-device"
pid of mdadm daemon to
.BR /var/run/mdadm .
+.B " mdadm -Iq /dev/somedevice"
+.br
+Try to incorporate newly discovered device into some array as
+appropriate.
+
+.B " mdadm --incremental --rebuild --run --scan"
+.br
+Rebuild the array map from any current arrays, and then start any that
+can be started.
+
.B " mdadm --create --help"
.br
Provide help about the Create mode.
.BR mdadm.conf (5)
for more details.
+.SS /var/run/mdadm/map
+When
+.I --incremental
+mode is used. this file gets a list of arrays currently being created.
+If
+.B /var/run/mdadm
+does not exist as a directory, then
+.B /var/run/mdadm.map
+is used instead.
+
.SH DEVICE NAMES
While entries in the /dev directory can have any format you like,
projects / thirdparty / mdadm.git / blobdiff