.\" -*- nroff -*-
-.TH MDADM 8 "" v2.4.1
+.TH MDADM 8 "" v2.5
.SH NAME
mdadm \- manage MD devices
.I aka
'''the
'''.B raidtools
'''configuration file, at all. It has a different configuration file
-'''with a different format and an different purpose.
+'''with a different format and a different purpose.
.SH MODES
mdadm has 7 major modes of operation:
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
To set the parity with "--grow", the level of the array ("faulty")
must be specified before the fault mode is specified.
-Finally, the layout options for RAID10 are either 'n' or 'p' followed
+Finally, the layout options for RAID10 are one of 'n', 'o' or 'p' followed
by a small number. The default is 'n2'.
.I n
-signals 'near' copies (multiple copies of one data block are at
-similar offsets in different devices) while
+signals 'near' copies. Multiple copies of one data block are at
+similar offsets in different devices.
+
+.I o
+signals 'offset' copies. Rather than the chunks being duplicated
+within a stripe, whole stripes are duplicated but are rotated by one
+device so duplicate blocks are on different devices. Thus subsequent
+copies of a block are in the next drive, and are one chunk further
+down.
+
.I f
signals 'far' copies
(multiple copies have very different offsets). See md(4) for more
Note: external bitmaps are only known to work on ext2 and ext3.
Storing bitmap files on other filesystems may result in serious problems.
-
.TP
.BR --bitmap-chunk=
Set the chunksize of the bitmap. Each bit corresponds to that many
-Kilobytes of storage. Default is 4 when using a file based bitmap.
+Kilobytes of storage.
+When using a file based bitmap, the default is to use the smallest
+size that is atleast 4 and requires no more than 2^21 chunks.
When using an
.B internal
bitmap, the chunksize is automatically determined to make best use of
.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
.TP
.BR -R ", " --run
-Attempt to start the array even if fewer drives were given than are
-needed for a full array. Normally if not all drives are found and
+Attempt to start the array even if fewer drives were given than were
+present last time the array was active. Normally if not all the
+expected drives are found and
.B --scan
is not used, then the array will be assembled but not started.
With
.B --run
an attempt will be made to start it anyway.
+.TP
+.B --no-degraded
+This is the reverse of
+.B --run
+in that it inhibits the started if array unless all expected drives
+are present. This is only needed with
+.B --scan
+and can be used if you physical connections to devices are
+not as reliable as you would like.
+
.TP
.BR -a ", " "--auto{=no,yes,md,mdp,part}"
See this option under Create and Build options.
.BR sparc2.2 ,
.BR summaries ,
.BR uuid ,
+.BR name ,
+.BR homehost ,
.BR resync ,
.BR byteorder ,
or
be used to help identify the devices in the array.
If no "--uuid" is given, a random uuid is chosen.
+The
+.B name
+option will change the
+.I name
+of the array as stored in the superblock. This is only supported for
+version-1 superblocks.
+
+The
+.B homehost
+option will change the
+.I homehost
+as recorded in the superblock. For version-0 superblocks, this is the
+same as updating the UUID.
+For version-1 superblocks, this involves updating the name.
+
The
.B resync
option will cause the array to be marked
option will correct the summaries in the superblock. That is the
counts of total, working, active, failed, and spare devices.
+.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
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.
+
'''If the
'''.B --size
'''option is given, it is not necessary to list any component-devices in this command.
.TP
.B SpareActive
A spare component device which was being rebuilt to replace a faulty
-device as been successfully rebuild and has been made active.
+device has been successfully rebuilt and has been made active.
(syslog priority: Info)
.TP