.\" -*- nroff -*-
-.TH MDADM 8 "" v2.4.1
+''' 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 8 "" v2.5.6
.SH NAME
mdadm \- manage MD devices
.I aka
'''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
of component devices in RAID level 1/4/5/6 and changing the number of
active devices in RAID1.
+.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
This is for doing things to specific components of an array such as
.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
4K from the start (for 1.2).
.RE
+.TP
+.B --homehost=
+This will over-ride any
+.B HOMEHOST
+setting in the config file and provides the identify of the host which
+should be considered the home for any arrays.
+
+When creating an array, the
+.B homehost
+will be recorded in the superblock. For version-1 superblocks, it will
+be prefixed to the array name. For version-0.90 superblocks part of
+the SHA1 hash of the hostname will be stored in the later half of the
+UUID.
+
+When reporting information about an array, any array which is tagged
+for the given homehost will be reported as such.
+
+When using Auto-Assemble, only arrays tagged for the given homehost
+will be assembled.
+
.SH For create, build, or grow:
.TP
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
number, and there is no entry in /dev for that number and with a
non-standard name.
+.TP
+.BR --symlink = no
+Normally when
+.B --auto
+causes
+.I mdadm
+to create devices in
+.B /dev/md/
+it will also create symlinks from
+.B /dev/
+with names starting with
+.B md
+or
+.BR md_ .
+Use
+.B --symlink=no
+to suppress this, or
+.B --symlink=yes
+to enforce this even if it is suppressing
+.IR mdadm.conf .
+
+
.SH For assemble:
.TP
.TP
.BR -N ", " --name=
Specify the name of the array to assemble. This must be the name
-that was specified when creating the array.
+that was specified when creating the array. It must either match
+then name stored in the superblock exactly, or it must match
+with the current
+.I homehost
+is added to the start of the given name.
.TP
.BR -f ", " --force
.BR homehost ,
.BR resync ,
.BR byteorder ,
+.BR devicesize ,
or
.BR super-minor .
option will update the
.B "preferred 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.
+assembled.
+This can be useful if
+.B --examine
+reports a different "Preferred Minor" to
+.BR --detail .
+In some cases this update will be performed automatically
+by the kernel driver. In particular the update happens automatically
+at the first write to an array with redundancy (RAID level 1 or
+greater) on a 2.6 (or later) kernel.
The
.B uuid
option will change the uuid of the array. If a UUID is given with the
-"--uuid" option that UUID will be used as a new UUID and with
+"--uuid" option that UUID will be used as a new UUID and will
.B NOT
be used to help identify the devices in the array.
If no "--uuid" is given, a random uuid is chosen.
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).
+In that situation, if no suitable arrays are found for this homehost,
+.I mdadm
+will recan for any arrays at all and will assemble them and update the
+homehost to match the current host.
+
.SH For Manage mode:
.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
not use a config file, the "auto=" config option does not apply to
these modes.
+.SS Auto Assembly
+When
+.B --assemble
+is used with
+.B --scan
+and no devices are listed,
+.I mdadm
+will first attempt to assemble all the arrays listed in the config
+file.
+
+If a
+.B homehost
+has been specified (either in the config file or on the command line),
+.I mdadm
+will look further for possible arrays and will try to assemble
+anything that it finds which is tagged as belonging to the given
+homehost. This is the only situation where
+.I mdadm
+will assemble arrays without being given specific device name or
+identify information for the array.
+
+If
+.I mdadm
+finds a consistent set of devices that look like they should comprise
+an array, and if the superblock is tagged as belonging to the given
+home host, it will automatically choose a device name and try to
+assemble the array. If the array uses version-0.90 metadata, then the
+.B minor
+number as recorded in the superblock is used to create a name in
+.B /dev/md/
+so for example
+.BR /dev/md/3 .
+If the array uses version-1 metadata, then the
+.B name
+from the superblock is used to similarly create a name in
+.BR /dev/md .
+The name will have any 'host' prefix stripped first.
+
+If
+.I mdadm
+cannot find any array for the given host at all, and if
+.B --auto-update-homehost
+is given, then
+.I mdadm
+will search again for any array (not just an array created for this
+host) and will assemble each assuming
+.IR --update=homehost .
+This will change the host tag in the superblock so that on the next run,
+these arrays will be found without the second pass. The intention of
+this feature is to support transitioning a set of md arrays to using
+homehost tagging.
+
+The reason for requiring arrays to be tagged with the homehost for
+auto assembly is to guard against problems that can arise when moving
+devices from one host to another.
+
.SH BUILD MODE
.HP 12
.I --force
option.
+When creating an array with version-1 metadata a name for the host is
+required.
+If this is not given with the
+.B --name
+option,
+.I mdadm
+will chose a name based on the last component of the name of the
+device being created. So if
+.B /dev/md3
+is being created, then the name
+.B 3
+will be chosen.
+If
+.B /dev/md/home
+is being created, then the name
+.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.
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,