.\" 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 "" v3.2.1
+.TH MDADM 8 "" v3.2.5
.SH NAME
mdadm \- manage MD devices
.I aka
.I mdadm
will be silent unless there is something really important to report.
+.TP
+.BR \-\-offroot
+Set first character of argv[0] to @ to indicate mdadm was launched
+from initrd/initramfs and should not be shutdown by systemd as part of
+the regular shutdown process. This option is normally only used by
+the system's initscripts. Please see here for more details on how
+systemd handled argv[0]:
+.IP
+.B http://www.freedesktop.org/wiki/Software/systemd/RootStorageDaemons
+.PP
+
+
.TP
.BR \-f ", " \-\-force
Be more forceful about certain operations. See the various modes for
recovery operation can be checkpointed and restarted. The different
sub-versions store the superblock at different locations on the
device, either at the end (for 1.0), at the start (for 1.1) or 4K from
-the start (for 1.2). "1" is equivalent to "1.0".
+the start (for 1.2). "1" is equivalent to "1.2" (the commonly
+preferred 1.x format).
'if '{DEFAULT_METADATA}'1.2' "default" is equivalent to "1.2".
.IP ddf
Use the "Industry Standard" DDF (Disk Data Format) format defined by
by a digit string). See below under
.BR "Auto Assembly" .
+.TP
+.B \-\-prefer=
+When
+.I mdadm
+needs to print the name for a device it normally finds the name in
+.B /dev
+which refers to the device and is shortest. When a path component is
+given with
+.B \-\-prefer
+.I mdadm
+will prefer a longer name if it contains that component. For example
+.B \-\-prefer=by-uuid
+will prefer a name in a subdirectory of
+.B /dev
+called
+.BR by-uuid .
+
+This functionality is currently only provided by
+.B \-\-detail
+and
+.BR \-\-monitor .
+
.SH For create, build, or grow:
.TP
A suffix of 'M' or 'G' can be given to indicate Megabytes or
Gigabytes respectively.
+Sometimes a replacement drive can be a little smaller than the
+original drives though this should be minimised by IDEMA standards.
+Such a replacement drive will be rejected by
+.IR md .
+To guard against this it can be useful to set the initial size
+slightly smaller than the smaller device with the aim that it will
+still be larger than any replacement.
+
This value can be set with
.B \-\-grow
-for RAID level 1/4/5/6. If the array was created with a size smaller
-than the currently active drives, the extra space can be accessed
-using
+for RAID level 1/4/5/6 though
+.B CONTAINER
+based arrays such as those with IMSM metadata may not be able to
+support this.
+If the array was created with a size smaller than the currently
+active drives, the extra space can be accessed using
.BR \-\-grow .
The size can be given as
.B max
.B "\-\-grow \-\-size="
command.
-This value can not be used with
+This value cannot be used when creating a
.B CONTAINER
-metadata such as DDF and IMSM.
+such as with DDF and IMSM metadata, though it perfectly valid when
+creating an array inside a container.
.TP
.BR \-Z ", " \-\-array\-size=
default when Building and array with no persistent metadata is 64KB.
This is only meaningful for RAID0, RAID4, RAID5, RAID6, and RAID10.
+RAID4, RAID5, RAID6, and RAID10 require the chunk size to be a power
+of 2. In any case it must be a multiple of 4KB.
+
A suffix of 'M' or 'G' can be given to indicate Megabytes or
Gigabytes respectively.
actually clean. If that is the case, such as after running
badblocks, this argument can be used to tell mdadm the
facts the operator knows.
+.IP
+When an array is resized to a larger size with
+.B "\-\-grow \-\-size="
+the new space is normally resynced in that same way that the whole
+array is resynced at creation. From Linux version 3.0,
+.B \-\-assume\-clean
+can be used with that command to avoid the automatic resync.
.TP
.BR \-\-backup\-file=
The file must be stored on a separate device, not on the RAID array
being reshaped.
+.TP
+.B \-\-data\-offset=
+Arrays with 1.x metadata can leave a gap between the start of the
+device and the start of array data. This gap can be used for various
+metadata. The start of data is known as the
+.IR data\-offset .
+Normally an appropriate data offset is computed automatically.
+However it can be useful to set it explicitly such as when re-creating
+an array which was originally created using a different version of
+.I mdadm
+which computed a different offset.
+
+Setting the offset explicitly over-rides the default. The value given
+is in Kilobytes unless an 'M' or 'G' suffix is given.
+
+Since Linux 3.4,
+.B \-\-data\-offset
+can also be used with
+.B --grow
+for some RAID levels (initially on RAID10). This allows the
+data-offset to be changed as part of the reshape process. When the
+data offset is changed, no backup file is required as the difference
+in offsets is used to provide the same functionality.
+
+When the new offset is earlier than the old offset, the number of
+devices in the array cannot shrink. When it is after the old offset,
+the number of devices in the array cannot increase.
+
+.TP
+.BR \-\-continue
+This option is complementary to the
+.B \-\-freeze-reshape
+option for assembly. It is needed when
+.B \-\-grow
+operation is interrupted and it is not restarted automatically due to
+.B \-\-freeze-reshape
+usage during array assembly. This option is used together with
+.BR \-G
+, (
+.BR \-\-grow
+) command and device for a pending reshape to be continued.
+All parameters required for reshape continuation will be read from array metadata.
+If initial
+.BR \-\-grow
+command had required
+.BR \-\-backup\-file=
+option to be set, continuation option will require to have exactly the same
+backup file given as well.
+.IP
+Any other parameter passed together with
+.BR \-\-continue
+option will be ignored.
+
.TP
.BR \-N ", " \-\-name=
Set a
.I mdadm
will not try to be so clever.
+.TP
+.BR \-o ", " \-\-readonly
+Start the array
+.B read only
+rather than read-write as normal. No writes will be allowed to the
+array, and no resync, recovery, or reshape will be started.
+
.TP
.BR \-a ", " "\-\-auto{=yes,md,mdp,part,p}{NN}"
Instruct mdadm how to create the device file if needed, possibly allocating
non-standard name. Names that are not in 'standard' format are only
allowed in "/dev/md/".
+This is meaningful with
+.B \-\-create
+or
+.BR \-\-build .
+
.ig XX
.\".TP
.\".BR \-\-symlink = no
.\"
.XX
+.TP
+.BR \-a ", " "\-\-add"
+This option can be used in Grow mode in two cases.
+
+If the target array is a Linear array, then
+.B \-\-add
+can be used to add one or more devices to the array. They
+are simply catenated on to the end of the array. Once added, the
+devices cannot be removed.
+
+If the
+.B \-\-raid\-disks
+option is being used to increase the number of devices in an array,
+then
+.B \-\-add
+can be used to add some extra devices to be included in the array.
+In most cases this is not needed as the extra devices can be added as
+spares first, and then the number of raid-disks can be changed.
+However for RAID0, it is not possible to add spares. So to increase
+the number of devices in a RAID0, it is necessary to set the new
+number of devices, and to add the new devices, in the same command.
+
.SH For assemble:
.TP
.BR \-a ", " "\-\-auto{=no,yes,md,mdp,part}"
See this option under Create and Build options.
-.TP
-.BR \-a ", " "\-\-add"
-This option can be used in Grow mode in two cases.
-
-If the target array is a Linear array, then
-.B \-\-add
-can be used to add one or more devices to the array. They
-are simply catenated on to the end of the array. Once added, the
-devices cannot be removed.
-
-If the
-.B \-\-raid\-disks
-option is being used to increase the number of devices in an array,
-then
-.B \-\-add
-can be used to add some extra devices to be included in the array.
-In most cases this is not needed as the extra devices can be added as
-spares first, and then the number of raid-disks can be changed.
-However for RAID0, it is not possible to add spares. So to increase
-the number of devices in a RAID0, it is necessary to set the new
-number of devices, and to add the new devices, in the same command.
-
.TP
.BR \-b ", " \-\-bitmap=
Specify the bitmap file that was given when the array was created. If
.BR byteorder ,
.BR devicesize ,
.BR no\-bitmap ,
+.BR bbl ,
+.BR no-\bbl ,
or
.BR super\-minor .
corrupt in some way so that assembling the array normally fails. It
will cause any internal bitmap to be ignored.
-.ig
+The
+.B bbl
+option will reserve space in each device for a bad block list. This
+will be 4K in size and positioned near the end of any free space
+between the superblock and the data.
+
+The
+.B no\-bbl
+option will cause any reservation of space for a bad block list to be
+removed. If the bad block list contains entries, this will fail, as
+removing the list could cause data corruption.
+
.TP
-.B \-\-auto\-update\-homehost
-This flag is only meaningful with auto-assembly (see discussion below).
-In that situation, if no suitable arrays are found for this homehost,
-.I mdadm
-will rescan for any arrays at all and will assemble them and update the
-homehost to match the current host.
-..
+.BR \-\-freeze\-reshape
+Option is intended to be used in start-up scripts during initrd boot phase.
+When array under reshape is assembled during initrd phase, this option
+stops reshape after reshape critical section is being restored. This happens
+before file system pivot operation and avoids loss of file system context.
+Losing file system context would cause reshape to be broken.
+
+Reshape can be continued later using the
+.B \-\-continue
+option for the grow command.
.SH For Manage mode:
.BR \-a ", " \-\-add
hot-add listed devices.
If a device appears to have recently been part of the array
-(possibly it failed or was removed) the device is re\-added as describe
+(possibly it failed or was removed) the device is re\-added as described
in the next point.
If that fails or the device was never part of the array, the device is
added as a hot-spare.
it will be assumed that bitmap-based recovery is enough to make the
device fully consistent with the array.
-When
+When used with v1.x metadata,
.B \-\-re\-add
can be accompanied by
-.BR \-\-update=devicesize .
-See the description of this option when used in Assemble mode for an
-explanation of its use.
+.BR \-\-update=devicesize ,
+.BR \-\-update=bbl ", or"
+.BR \-\-update=no\-bbl .
+See the description of these option when used in Assemble mode for an
+explanation of their use.
If the device name given is
.B missing
.TP
.BR \-\-detail\-platform
Print details of the platform's RAID capabilities (firmware / hardware
-topology) for a given metadata format.
+topology) for a given metadata format. If used without argument, mdadm
+will scan all controllers looking for their capabilities. Otherwise, mdadm
+will only look at the controller specified by the argument in form of an
+absolute filepath or a link, e.g.
+.IR /sys/devices/pci0000:00/0000:00:1f.2 .
.TP
.BR \-Y ", " \-\-export
When used with
-.B \-\-detail
+.B \-\-detail , \-\-detail-platform
or
.BR \-\-examine ,
output will be formatted as
.TP
.BR \-\-rebuild\-map ", " \-r
Rebuild the map file
-.RB ( /var/run/mdadm/map )
+.RB ( {MAP_PATH} )
that
.I mdadm
uses to help track which arrays are currently being assembled.
In the second usage example, all devices listed are treated as md
devices and assembly is attempted.
In the third (where no devices are listed) all md devices that are
-listed in the configuration file are assembled. If not arrays are
+listed in the configuration file are assembled. If no arrays are
described by the configuration file, then any arrays that
can be found on unused devices will be assembled.
but leaves that to
.IR udev .
It does record information in
-.B /var/run/mdadm/map
+.B {MAP_PATH}
which will allow
.I udev
to choose the correct name.
will first attempt to assemble all the arrays listed in the config
file.
-In no array at listed in the config (other than those marked
+If no arrays are listed in the config (other than those marked
.BR <ignore> )
it will look through the available devices for possible arrays and
will try to assemble anything that it finds. Arrays which are tagged
.IR mdadm.conf (5)
for further details.
-.ig
-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
-.BR \-\-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.
-..
Note: Auto assembly cannot be used for assembling and activating some
arrays which are undergoing reshape. In particular as the
.B backup\-file
.\".B \-\-size
.\"is given, the apparent size of the smallest drive given is used.
+If the metadata type supports it (currently only 1.x metadata), space
+will be allocated to store a bad block list. This allows a modest
+number of bad blocks to be recorded, allowing the drive to remain in
+service while only partially functional.
+
When creating an array within a
.B CONTAINER
.I mdadm
.IP \(bu 4
increase or decrease the "raid\-devices" attribute of RAID0, RAID1, RAID4,
RAID5, and RAID6.
-.IP \bu 4
+.IP \(bu 4
change the chunk-size and layout of RAID0, RAID4, RAID5 and RAID6.
-.IP \bu 4
+.IP \(bu 4
convert between RAID1 and RAID5, between RAID5 and RAID6, between
-RAID0, RAID5, and RAID5, and between RAID0 and RAID10 (in the near-2 mode).
+RAID0, RAID4, and RAID5, and between RAID0 and RAID10 (in the near-2 mode).
.IP \(bu 4
add a write-intent bitmap to any array which supports these bitmaps, or
remove a write-intent bitmap from such an array.
.PP
-Using GROW on containers is currently only support for Intel's IMSM
+Using GROW on containers is currently supported only for Intel's IMSM
container format. The number of devices in a container can be
increased - which affects all arrays in the container - or an array
in a container can be converted between levels where those levels are
supported by the container, and the conversion is on of those listed
-above.
+above. Resizing arrays in an IMSM container with
+.B "--grow --size"
+is not yet supported.
Grow functionality (e.g. expand a number of raid devices) for Intel's
IMSM container format has an experimental status. It is guarded by the
This is for the following reasons:
.IP 1.
-Intel's native IMSM check-pointing is not fully implemented yet.
-This causes IMSM incompatibility during the grow process: an array
+Intel's native IMSM check-pointing is not fully tested yet.
+This can causes IMSM incompatibility during the grow process: an array
which is growing cannot roam between Microsoft Windows(R) and Linux
systems.
Interrupting a grow operation is not recommended, because it
has not been fully tested for Intel's IMSM container format yet.
+.PP
+Note: Intel's native checkpointing doesn't use
+.B --backup-file
+option and it is transparent for assembly feature.
+
.SS SIZE CHANGES
Normally when an array is built the "size" is taken from the smallest
of the drives. If all the small drives in an arrays are, one at a
are synchronised.
Note that when an array changes size, any filesystem that may be
-stored in the array will not automatically grow for shrink to use or
+stored in the array will not automatically grow or shrink to use or
vacate the space. The
filesystem will need to be explicitly told to use the extra space
after growing, or to reduce its size
Also the size of an array cannot be changed while it has an active
bitmap. If an array has a bitmap, it must be removed before the size
-can be changed. Once the change it complete a new bitmap can be created.
+can be changed. Once the change is complete a new bitmap can be created.
.SS RAID\-DEVICES CHANGES
line.
.IP +
-Does the device have a valid md superblock. If a specific metadata
-version is request with
+Does the device have a valid md superblock? If a specific metadata
+version is requested with
.B \-\-metadata
or
.B \-e
current host, the device will be rejected.
..
+.PP
.I mdadm
keeps a list of arrays that it has partially assembled in
-.B /var/run/mdadm/map
-(or
-.B /var/run/mdadm.map
-if the directory doesn't exist. Or maybe even
-.BR /dev/.mdadm.map ).
+.BR {MAP_PATH} .
If no array exists which matches
the metadata on the new device,
.I mdadm
.B /dev/md0
out of all such devices with a RAID superblock with a minor number of 0.
-.B " mdadm \-\-monitor \-\-scan \-\-daemonise > /var/run/mdadm"
+.B " mdadm \-\-monitor \-\-scan \-\-daemonise > /run/mdadm/mon.pid"
.br
If config file contains a mail address or alert program, run mdadm in
the background in monitor mode monitoring all md devices. Also write
pid of mdadm daemon to
-.BR /var/run/mdadm .
+.BR /run/mdadm/mon.pid .
.B " mdadm \-Iq /dev/somedevice"
.br
Any devices which are components of /dev/md4 will be marked as faulty
and then remove from the array.
-.B " mdadm --grow /dev/md4 --level=6 --backup-file=/root/backup-md4
+.B " mdadm --grow /dev/md4 --level=6 --backup-file=/root/backup-md4"
.br
The array
.B /dev/md4
.BR mdadm.conf (5)
for more details.
-.SS /var/run/mdadm/map
+.SS {MAP_PATH}
When
.B \-\-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. If
-.B /var/run
-is not available (as may be the case during early boot),
-.B /dev/.mdadm.map
-is used on the basis that
-.B /dev
-is usually available very early in boot.
.SH DEVICE NAMES
For further information on mdadm usage, MD and the various levels of
RAID, see:
.IP
-.B http://linux\-raid.osdl.org/
+.B http://raid.wiki.kernel.org/
.PP
(based upon Jakob \(/Ostergaard's Software\-RAID.HOWTO)
.\".PP
projects / thirdparty / mdadm.git / blobdiff