.\" -*- 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
'''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:
.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
.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 ,
+.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.
+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.
+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
.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.
+
'''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
projects / thirdparty / mdadm.git / blobdiff