.\" 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.1.2
+.TH MDADM 8 "" v3.1.4
.SH NAME
mdadm \- manage MD devices
.I aka
system. As each device is detected,
.I mdadm
has a chance to include it in some array as appropriate.
+Optionally, when the
+.I \-\-fail
+flag is passed in we will remove the device from any active array
+instead of adding it.
If a
.B CONTAINER
.TP
.BR \-I ", " \-\-incremental
-Add a single device into an appropriate array, and possibly start the array.
+Add/remove a single device to/from an appropriate array, and possibly start the array.
.TP
.B \-\-auto-detect
..
Use the original 0.90 format superblock. This format limits arrays to
28 component devices and limits component devices of levels 1 and
-greater to 2 terabytes.
+greater to 2 terabytes. It is also possible for there to be confusion
+about whether the superblock applies to a whole device or just the
+last partition, if that partition starts on a 64K boundary.
.ie '{DEFAULT_METADATA}'0.90'
.IP "1, 1.0, 1.1, 1.2"
.el
.IP "1, 1.0, 1.1, 1.2 default"
..
-Use the new version-1 format superblock. This has few restrictions.
-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".
+Use the new version-1 format superblock. This has fewer restrictions.
+It can easily be moved between hosts with different endian-ness, and a
+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".
'if '{DEFAULT_METADATA}'1.2' "default" is equivalent to "1.2".
.IP ddf
Use the "Industry Standard" DDF (Disk Data Format) format defined by
size, though if there is a variance among the drives of greater than 1%, a warning is
issued.
+A suffix of 'M' or 'G' can be given to indicate Megabytes or
+Gigabytes respectively.
+
This value can be set with
.B \-\-grow
for RAID level 1/4/5/6. If the array was created with a size smaller
.BR \-Z ", " \-\-array-size=
This is only meaningful with
.B \-\-grow
-and its effect is not persistent: when the array is stopped an
+and its effect is not persistent: when the array is stopped and
restarted the default array size will be restored.
Setting the array-size causes the array to appear smaller to programs
is, it is required that the array size is reduced as appropriate
before the number of devices in the array is reduced.
+A suffix of 'M' or 'G' can be given to indicate Megabytes or
+Gigabytes respectively.
+A value of
+.B max
+restores the apparent size of the array to be whatever the real
+amount of available space is.
+
.TP
.BR \-c ", " \-\-chunk=
Specify chunk size of kibibytes. The default when creating an
default when Building and array with no persistent metadata is 64KB.
This is only meaningful for RAID0, RAID4, RAID5, RAID6, and RAID10.
+A suffix of 'M' or 'G' can be given to indicate Megabytes or
+Gigabytes respectively.
+
.TP
.BR \-\-rounding=
Specify rounding factor for a Linear array. The size of each
The default is
.BR left\-symmetric .
-It is also possibly to cause RAID5 to use a RAID4-like layout by
+It is also possible to cause RAID5 to use a RAID4-like layout by
choosing
.BR parity\-first ,
or
bitmap, the chunksize defaults to 64Meg, or larger if necessary to
fit the bitmap into the available space.
+A suffix of 'M' or 'G' can be given to indicate Megabytes or
+Gigabytes respectively.
+
.TP
.BR \-W ", " \-\-write\-mostly
subsequent devices listed in a
.BR \-\-backup\-file=
This is needed when
.B \-\-grow
-is used to increase the number of
-raid-devices in a RAID5 if there are no spare devices available.
-See the GROW MODE section below on RAID\-DEVICES CHANGES. The file
-should be stored on a separate device, not on the RAID array being
-reshaped.
-
-.TP
-.BR \-\-array-size= ", " \-Z
-Set the size of the array which is seen by users of the device such as
-filesystems. This can be less that the real size, but never greater.
-The size set this way does not persist across restarts of the array.
-
-This is most useful when reducing the number of devices in a RAID5 or
-RAID6. Such arrays require the array-size to be reduced before a
-reshape can be performed that reduces the real size.
-
-A value of
-.B max
-restores the apparent size of the array to be whatever the real
-amount of available space is.
+is used to increase the number of raid-devices in a RAID5 or RAID6 if
+there are no spare devices available, or to shrink, change RAID level
+or layout. See the GROW MODE section below on RAID\-DEVICES CHANGES.
+The file must be stored on a separate device, not on the RAID array
+being reshaped.
.TP
.BR \-N ", " \-\-name=
.BR \-\-backup\-file=
If
.B \-\-backup\-file
-was used to grow the number of raid-devices in a RAID5, and the system
-crashed during the critical section, then the same
+was used while reshaping an array (e.g. changing number of devices or
+chunk size) and the system crashed during the critical section, then the same
.B \-\-backup\-file
must be presented to
.B \-\-assemble
-to allow possibly corrupted data to be restored.
+to allow possibly corrupted data to be restored, and the reshape
+to be completed.
+
+.TP
+.BR \-\-invalid\-backup
+If the file needed for the above option is not available for any
+reason an empty file can be given together with this option to
+indicate that the backup file is invalid. In this case the data that
+was being rearranged at the time of the crash could be irrecoverably
+lost, but the rest of the array may still be recoverable. This option
+should only be used as a last resort if there is no way to recover the
+backup file.
+
.TP
.BR \-U ", " \-\-update=
.BR resync ,
.BR byteorder ,
.BR devicesize ,
+.BR no\-bitmap ,
or
.BR super\-minor .
The
.B devicesize
-will rarely be of use. It applies to version 1.1 and 1.2 metadata
+option 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
to determine the maximum usable amount of space on each device and
update the relevant field in the metadata.
+The
+.B no\-bitmap
+option can be used when an array has an internal bitmap which is
+corrupt in some way so that assembling the array normally fails. It
+will cause any internal bitmap to be ignored.
+
.ig
.TP
.B \-\-auto\-update\-homehost
.SH For Manage mode:
+.TP
+.BR \-t ", " \-\-test
+Unless a more serious error occurred,
+.I mdadm
+will exit with a status of 2 if no changes were made to the array and
+0 if at least one change was made.
+This can be useful when an indirect specifier such as
+.BR missing ,
+.B detached
+or
+.B faulty
+is used in requesting an operation on the array.
+.B \-\-test
+will report failure if these specifiers didn't find any match.
+
.TP
.BR \-a ", " \-\-add
-hot-add listed devices. For arrays with redundancy, the listed
-devices become available as spares. If the array is degraded, it will
-immediately start recovering data on to one of these spares.
+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
+in the next point.
+If that fails or the device was never part of the array, the device is
+added as a hot-spare.
+If the array is degraded, it will immediately start to rebuild data
+onto that spare.
+
+Note that this and the following options are only meaningful on array
+with redundancy. They don't apply to RAID0 or Linear.
.TP
.BR \-\-re\-add
-re-add a device that was recently removed from an array. This is only
-needed for arrays that have be built (i.e. with
-.BR --build ).
-For created arrays, devices are always re-added if that is possible.
-When re-adding a device, if nothing has changed on the array since the
-device was removed, no recovery is performed. Also, if the array has
-a write-intent bitmap, then the recovery performed after a re-add will
-be limited to those blocks which, according to the bitmap, might have
-changed since the device was removed.
+re\-add a device that was previous removed from an array.
+If the metadata on the device reports that it is a member of the
+array, and the slot that it used is still vacant, then the device will
+be added back to the array in the same position. This will normally
+cause the data for that device to be recovered. However based on the
+event count on the device, the recovery may only require sections that
+are flagged a write-intent bitmap to be recovered or may not require
+any recovery at all.
+
+When used on an array that has no metadata (i.e. it was built with
+.BR \-\-build)
+it will be assumed that bitmap-based recovery is enough to make the
+device fully consistent with the array.
+
+When
+.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.
+
+If the device name given is
+.B missing
+then mdadm will try to find any device that looks like it should be
+part of the array but isn't and will try to re\-add all such devices.
.TP
.BR \-r ", " \-\-remove
.TP
.BR \-\-write\-mostly
-Subsequent devices that are added or re-added will have the 'write-mostly'
+Subsequent devices that are added or re\-added will have the 'write-mostly'
flag set. This is only valid for RAID1 and means that the 'md' driver
will avoid reading from these devices if possible.
.TP
.BR \-\-readwrite
-Subsequent devices that are added or re-added will have the 'write-mostly'
+Subsequent devices that are added or re\-added will have the 'write-mostly'
flag cleared.
.P
operation.
If an array is using a write-intent bitmap, then devices which have
-been removed can be re-added in a way that avoids a full
+been removed can be re\-added in a way that avoids a full
reconstruction but instead just updates the blocks that have changed
since the device was removed. For arrays with persistent metadata
(superblocks) this is done automatically. For arrays created with
the block where the superblock would be is overwritten even if it
doesn't appear to be valid.
+.TP
+.B \-\-kill\-subarray=
+If the device is a container and the argument to \-\-kill\-subarray
+specifies an inactive subarray in the container, then the subarray is
+deleted. Deleting all subarrays will leave an 'empty-container' or
+spare superblock on the drives. See \-\-zero\-superblock for completely
+removing a superblock. Note that some formats depend on the subarray
+index for generating a UUID, this command will fail if it would change
+the UUID of an active subarray.
+
+.TP
+.B \-\-update\-subarray=
+If the device is a container and the argument to \-\-update\-subarray
+specifies a subarray in the container, then attempt to update the given
+superblock field in the subarray. See below in
+.B MISC MODE
+for details.
+
.TP
.BR \-t ", " \-\-test
When used with
For each md device given, or each device in /proc/mdstat if
.B \-\-scan
is given, arrange for the array to be marked clean as soon as possible.
-Also, quiesce resync so that the monitor for external metadata arrays
-(mdmon) has an opportunity to checkpoint the resync position.
.I mdadm
will return with success if the array uses external metadata and we
successfully waited. For native arrays this returns immediately as the
-kernel handles both dirty-clean transitions and resync checkpointing in
-the kernel at shutdown. No action is taken if safe-mode handling is
-disabled.
+kernel handles dirty-clean transitions at shutdown. No action is taken
+if safe-mode handling is disabled.
.SH For Incremental Assembly mode:
.TP
.B mdadm.conf
as requiring an external bitmap, that bitmap will be attached first.
+.TP
+.BR \-\-fail ", " \-f
+This allows the hot-plug system to remove devices that have fully disappeared
+from the kernel. It will first fail and then remove the device from any
+array it belongs to.
+The device name given should be a kernel device name such as "sda",
+not a name in
+.IR /dev .
+
.SH For Monitor mode:
.TP
.BR \-m ", " \-\-mail
When a device is added to an active array, mdadm checks to see if it
has metadata on it which suggests that it was recently a member of the
-array. If it does, it tried to "re-add" the device. If there have
+array. If it does, it tries to "re\-add" the device. If there have
been no changes since the device was removed, or if the array has a
write-intent bitmap which has recorded whatever changes there were,
then the device will immediately become a full member of the array and
metadata failed to find its platform components on this system
.RE
+.TP
+.B \-\-update\-subarray=
+If the device is a container and the argument to \-\-update\-subarray
+specifies a subarray in the container, then attempt to update the given
+superblock field in the subarray. Similar to updating an array in
+"assemble" mode, the field to update is selected by
+.B \-U
+or
+.B \-\-update=
+option. Currently only
+.B name
+is supported.
+
+The
+.B name
+option updates the subarray name in the metadata, it may not affect the
+device node name or the device node symlink until the subarray is
+re\-assembled. If updating
+.B name
+would change the UUID of an active subarray this operation is blocked,
+and the command will end in an error.
+
.TP
.B \-\-examine
The device should be a component of an md array.
inaccessible. The integrity of any data can then be checked before
the non-reversible reduction in the number of devices is request.
-When relocating the first few stripes on a RAID5, it is not possible
-to keep the data on disk completely consistent and crash-proof. To
-provide the required safety, mdadm disables writes to the array while
-this "critical section" is reshaped, and takes a backup of the data
-that is in that section. This backup is normally stored in any spare
-devices that the array has, however it can also be stored in a
-separate file specified with the
+When relocating the first few stripes on a RAID5 or RAID6, it is not
+possible to keep the data on disk completely consistent and
+crash-proof. To provide the required safety, mdadm disables writes to
+the array while this "critical section" is reshaped, and takes a
+backup of the data that is in that section. For grows, this backup may be
+stored in any spare devices that the array has, however it can also be
+stored in a separate file specified with the
.B \-\-backup\-file
-option. If this option is used, and the system does crash during the
-critical period, the same file must be passed to
+option, and is required to be specified for shrinks, RAID level
+changes and layout changes. If this option is used, and the system
+does crash during the critical period, the same file must be passed to
.B \-\-assemble
-to restore the backup and reassemble the array.
+to restore the backup and reassemble the array. When shrinking rather
+than growing the array, the reshape is done from the end towards the
+beginning, so the "critical section" is at the end of the reshape.
.SS LEVEL CHANGES
Changing the RAID level of any array happens instantaneously. However
-in the RAID to RAID6 case this requires a non-standard layout of the
+in the RAID5 to RAID6 case this requires a non-standard layout of the
RAID6 data, and in the RAID6 to RAID5 case that non-standard layout is
-required before the change can be accomplish. So while the level
+required before the change can be accomplished. So while the level
change is instant, the accompanying layout change can take quite a
-long time.
+long time. A
+.B \-\-backup\-file
+is required. If the array is not simultaneously being grown or
+shrunk, so that the array size will remain the same - for example,
+reshaping a 3-drive RAID5 into a 4-drive RAID6 - the backup file will
+be used not just for a "cricital section" but throughout the reshape
+operation, as described below under LAYOUT CHANGES.
.SS CHUNK-SIZE AND LAYOUT CHANGES
To ensure against data loss in the case of a crash, a
.B --backup-file
must be provided for these changes. Small sections of the array will
-be copied to the backup file while they are being rearranged.
+be copied to the backup file while they are being rearranged. This
+means that all the data is copied twice, once to the backup and once
+to the new layout on the array, so this type of reshape will go very
+slowly.
If the reshape is interrupted for any reason, this backup file must be
-make available to
+made available to
.B "mdadm --assemble"
so the array can be reassembled. Consequently the file cannot be
stored on the device being reshaped.
.I component-device
.HP 12
Usage:
-.B mdadm \-\-incremental \-\-rebuild
+.B mdadm \-\-incremental \-\-fail
+.I component-device
+.HP 12
+Usage:
+.B mdadm \-\-incremental \-\-rebuild\-map
.HP 12
Usage:
.B mdadm \-\-incremental \-\-run \-\-scan
.B "mdadm \-\-incremental"
to be conditionally added to an appropriate array.
+Conversely, it can also be used with the
+.B \-\-fail
+flag to do just the opposite and find whatever array a particular device
+is part of and remove the device from that array.
+
If the device passed is a
.B CONTAINER
device created by a previous call to
Try to incorporate newly discovered device into some array as
appropriate.
-.B " mdadm \-\-incremental \-\-rebuild \-\-run \-\-scan"
+.B " mdadm \-\-incremental \-\-rebuild\-map \-\-run \-\-scan"
.br
Rebuild the array map from any current arrays, and then start any that
can be started.
projects / thirdparty / mdadm.git / blobdiff