.\" 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.3
+.TH MDADM 8 "" v3.1.4
.SH NAME
mdadm \- manage MD devices
.I aka
..
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
.B max
which means to choose the largest size that fits on all current drives.
+Before reducing the size of the array (with
+.BR "\-\-grow \-\-size=" )
+you should make sure that space isn't needed. If the device holds a
+filesystem, you would need to resize the filesystem to use less space.
+
+After reducing the array size you should check that the data stored in
+the device is still available. If the device holds a filesystem, then
+an 'fsck' of the filesystem is a minimum requirement. If there are
+problems the array can be made bigger again with no loss with another
+.B "\-\-grow \-\-size="
+command.
+
This value can not be used with
.B CONTAINER
metadata such as DDF and IMSM.
-.TP
-.BR \-Z ", " \-\-array-size=
-This is only meaningful with
-.B \-\-grow
-and its effect is not persistent: when the array is stopped an
-restarted the default array size will be restored.
-
-Setting the array-size causes the array to appear smaller to programs
-that access the data. This is particularly needed before reshaping an
-array so that it will be smaller. As the reshape is not reversible,
-but setting the size with
-.B \-\-array-size
-is, it is required that the array size is reduced as appropriate
-before the number of devices in the array is reduced.
-
.TP
.BR \-c ", " \-\-chunk=
Specify chunk size of kibibytes. The default when creating an
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
.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.
+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 \-\-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 only meaningful with
+.B \-\-grow
+and its effect is not persistent: when the array is stopped an
+restarted the default array size will be restored.
-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.
+Setting the array-size causes the array to appear smaller to programs
+that access the data. This is particularly needed before reshaping an
+array so that it will be smaller. As the reshape is not reversible,
+but setting the size with
+.B \-\-array-size
+is, it is required that the array size is reduced as appropriate
+before the number of devices in the array is reduced.
A value of
.B max
restores the apparent size of the array to be whatever the real
amount of available space is.
+Before reducing the size of the array you should make sure that space
+isn't needed. If the device holds a filesystem, you would need to
+resize the filesystem to use less space.
+
+After reducing the array size you should check that the data stored in
+the device is still available. If the device holds a filesystem, then
+an 'fsck' of the filesystem is a minimum requirement. If there are
+problems the array can be made bigger again with no loss with another
+.B "\-\-grow \-\-array\-size="
+command.
+
.TP
.BR \-N ", " \-\-name=
Set a
.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 when requesting a grow, shrink, RAID level change or other
+reshape, 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 \-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
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.
projects / thirdparty / mdadm.git / blobdiff