''' 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.5.6
.SH NAME
mdadm \- manage MD devices
.I aka
.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
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
.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 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).
.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