.\" 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.5
+.TH MDADM 8 "" v3.3.3
.SH NAME
mdadm \- manage MD devices
.I aka
of component devices and changing the number of active devices in
Linear and RAID levels 0/1/4/5/6,
changing the RAID level between 0, 1, 5, and 6, and between 0 and 10,
-changing the chunk size and layout for RAID 0,4,5,6, as well as adding or
+changing the chunk size and layout for RAID 0,4,5,6,10 as well as adding or
removing a write-intent bitmap.
.TP
.P
If a device is given before any options, or if the first option is
+one of
.BR \-\-add ,
+.BR \-\-re\-add ,
+.BR \-\-add\-spare ,
.BR \-\-fail ,
.BR \-\-remove ,
or
.TP
.BR \-c ", " \-\-config=
-Specify the config file. Default is to use
-.BR /etc/mdadm.conf ,
-or if that is missing then
-.BR /etc/mdadm/mdadm.conf .
+Specify the config file or directory. Default is to use
+.B /etc/mdadm.conf
+and
+.BR /etc/mdadm.conf.d ,
+or if those are missing then
+.B /etc/mdadm/mdadm.conf
+and
+.BR /etc/mdadm/mdadm.conf.d .
If the config file given is
.B "partitions"
then nothing will be read, but
.I mdadm
will act as though the config file contained exactly
-.B "DEVICE partitions containers"
+.br
+.B " DEVICE partitions containers"
+.br
and will read
.B /proc/partitions
to find a list of devices to scan, and
.I mdadm
will act as though the config file were empty.
+If the name given is of a directory, then
+.I mdadm
+will collect all the files contained in the directory with a name ending
+in
+.BR .conf ,
+sort them lexically, and process all of those files as config files.
+
.TP
.BR \-s ", " \-\-scan
Scan config file or
by a digit string). See below under
.BR "Auto Assembly" .
+The special name "\fBany\fP" can be used as a wild card. If an array
+is created with
+.B --homehost=any
+then the name "\fBany\fP" will be stored in the array and it can be
+assembled in the same way on any host. If an array is assembled with
+this option, then the homehost recorded on the array will be ignored.
+
.TP
.B \-\-prefer=
When
.BR \-c ", " \-\-chunk=
Specify chunk size of kibibytes. The default when creating an
array is 512KB. To ensure compatibility with earlier versions, the
-default when Building and array with no persistent metadata is 64KB.
+default when building an 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
.BR devicesize ,
.BR no\-bitmap ,
.BR bbl ,
-.BR no-\bbl ,
+.BR no\-bbl ,
+.BR metadata ,
or
.BR super\-minor .
to determine the maximum usable amount of space on each device and
update the relevant field in the metadata.
+The
+.B metadata
+option only works on v0.90 metadata arrays and will convert them to
+v1.0 metadata. The array must not be dirty (i.e. it must not need a
+sync) and it must not have a write-intent bitmap.
+
+The old metadata will remain on the devices, but will appear older
+than the new metadata and so will usually be ignored. The old metadata
+(or indeed the new metadata) can be removed by giving the appropriate
+.B \-\-metadata=
+option to
+.BR \-\-zero\-superblock .
+
The
.B no\-bitmap
option can be used when an array has an internal bitmap which is
.TP
.BR \-\-re\-add
-re\-add a device that was previous removed from an array.
+re\-add a device that was previously 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
useful if you are certain that the reason for failure has been
resolved.
+.TP
+.B \-\-add\-spare
+Add a device as a spare. This is similar to
+.B \-\-add
+except that it does not attempt
+.B \-\-re\-add
+first. The device will be added as a spare even if it looks like it
+could be an recent member of the array.
+
.TP
.BR \-r ", " \-\-remove
remove listed devices. They must not be active. i.e. they should
.TP
.BR \-Y ", " \-\-export
When used with
-.B \-\-detail , \-\-detail-platform
-or
+.BR \-\-detail ,
+.BR \-\-detail-platform ,
.BR \-\-examine ,
+or
+.B \-\-incremental
output will be formatted as
.B key=value
pairs for easy import into the environment.
+With
+.B \-\-incremental
+The value
+.B MD_STARTED
+indicates whether an array was started
+.RB ( yes )
+or not, which may include a reason
+.RB ( unsafe ", " nothing ", " no ).
+Also the value
+.B MD_FOREIGN
+indicates if the array is expected on this host
+.RB ( no ),
+or seems to be from elsewhere
+.RB ( yes ).
+
.TP
.BR \-E ", " \-\-examine
Print contents of the metadata stored on the named device(s).
.B 1.x
metadata supports bad-blocks lists.
+.TP
+.BI \-\-dump= directory
+.TP
+.BI \-\-restore= directory
+Save metadata from lists devices, or restore metadata to listed devices.
+
.TP
.BR \-R ", " \-\-run
start a partially assembled array. If
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
+spare superblock on the drives. See
+.B \-\-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.
kernel handles dirty-clean transitions at shutdown. No action is taken
if safe-mode handling is disabled.
+.TP
+.B \-\-action=
+Set the "sync_action" for all md devices given to one of
+.BR idle ,
+.BR frozen ,
+.BR check ,
+.BR repair .
+Setting to
+.B idle
+will abort any currently running action though some actions will
+automatically restart.
+Setting to
+.B frozen
+will abort any current action and ensure no other action starts
+automatically.
+
+Details of
+.B check
+and
+.B repair
+can be found it
+.IR md (4)
+under
+.BR "SCRUBBING AND MISMATCHES" .
+
.SH For Incremental Assembly mode:
.TP
.BR \-\-rebuild\-map ", " \-r
.B name
is supported.
-The
+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
+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.
without listing any devices will cause all devices listed in the
config file to be examined.
+.TP
+.BI \-\-dump= directory
+If the device contains RAID metadata, a file will be created in the
+.I directory
+and the metadata will be written to it. The file will be the same
+size as the device and have the metadata written in the file at the
+same locate that it exists in the device. However the file will be "sparse" so
+that only those blocks containing metadata will be allocated. The
+total space used will be small.
+
+The file name used in the
+.I directory
+will be the base name of the device. Further if any links appear in
+.I /dev/disk/by-id
+which point to the device, then hard links to the file will be created
+in
+.I directory
+based on these
+.I by-id
+names.
+
+Multiple devices can be listed and their metadata will all be stored
+in the one directory.
+
+.TP
+.BI \-\-restore= directory
+This is the reverse of
+.BR \-\-dump .
+.I mdadm
+will locate a file in the directory that has a name appropriate for
+the given device and will restore metadata from it. Names that match
+.I /dev/disk/by-id
+names are preferred, however if two of those refer to different files,
+.I mdadm
+will not choose between them but will abort the operation.
+
+If a file name is given instead of a
+.I directory
+then
+.I mdadm
+will restore from that file to a single device, always provided the
+size of the file matches that of the device, and the file contains
+valid metadata.
.TP
.B \-\-stop
The devices should be active md arrays which will be deactivated, as
.TP
.B RebuildStarted
-An md array started reconstruction. (syslog priority: Warning)
+An md array started reconstruction (e.g. recovery, resync, reshape,
+check, repair). (syslog priority: Warning)
.TP
.BI Rebuild NN
increase or decrease the "raid\-devices" attribute of RAID0, RAID1, RAID4,
RAID5, and RAID6.
.IP \(bu 4
-change the chunk-size and layout of RAID0, RAID4, RAID5 and RAID6.
+change the chunk-size and layout of RAID0, RAID4, RAID5, RAID6 and RAID10.
.IP \(bu 4
convert between RAID1 and RAID5, between RAID5 and RAID6, between
RAID0, RAID4, and RAID5, and between RAID0 and RAID10 (in the near-2 mode).
.RB [ \-\-run ]
.RB [ \-\-quiet ]
.I component-device
+.RI [ optional-aliases-for-device ]
.HP 12
Usage:
.B mdadm \-\-incremental \-\-fail
.B DEVICES
line in that file. If
.B DEVICES
-is absent then the default it to allow any device. Similar if
+is absent then the default it to allow any device. Similarly if
.B DEVICES
contains the special word
.B partitions
then any device is allowed. Otherwise the device name given to
-.I mdadm
+.IR mdadm ,
+or one of the aliases given, or an alias found in the filesystem,
must match one of the names or patterns in a
.B DEVICES
line.
+This is the only context where the aliases are used. They are
+usually provided by a
+.I udev
+rules mentioning
+.BR ${DEVLINKS} .
+
.IP +
Does the device have a valid md superblock? If a specific metadata
version is requested with
.I mdadm
will create and devices that are needed.
+.TP
+.B MDADM_NO_SYSTEMCTL
+If
+.I mdadm
+detects that
+.I systemd
+is in use it will normally request
+.I systemd
+to start various background tasks (particularly
+.IR mdmon )
+rather than forking and running them in the background. This can be
+suppressed by setting
+.BR MDADM_NO_SYSTEMCTL=1 .
+
.TP
.B IMSM_NO_PLATFORM
A key value of IMSM metadata is that it allows interoperability with
environment. This can be useful for testing or for disaster
recovery. You should be aware that interoperability may be
compromised by setting this value.
+
+.TP
+.B MDADM_GROW_ALLOW_OLD
+If an array is stopped while it is performing a reshape and that
+reshape was making use of a backup file, then when the array is
+re-assembled
+.I mdadm
+will sometimes complain that the backup file is too old. If this
+happens and you are certain it is the right backup file, you can
+over-ride this check by setting
+.B MDADM_GROW_ALLOW_OLD=1
+in the environment.
+
+.TP
+.B MDADM_CONF_AUTO
+Any string given in this variable is added to the start of the
+.B AUTO
+line in the config file, or treated as the whole
+.B AUTO
+line if none is given. It can be used to disable certain metadata
+types when
+.I mdadm
+is called from a boot script. For example
+.br
+.B " export MDADM_CONF_AUTO='-ddf -imsm'
+.br
+will make sure that
+.I mdadm
+does not automatically assemble any DDF or
+IMSM arrays that are found. This can be useful on systems configured
+to manage such arrays with
+.BR dmraid .
+
+
.SH EXAMPLES
.B " mdadm \-\-query /dev/name-of-device"
.BR mdadm.conf (5)
for more details.
+.SS /etc/mdadm.conf.d
+
+A directory containing configuration files which are read in lexical
+order.
+
.SS {MAP_PATH}
When
.B \-\-incremental
From kernel version 2.6.28 the "non-partitioned array" can actually
be partitioned. So the "md_d\fBNN\fP"
names are no longer needed, and
-partitions such as "/dev/md\fBNN\fPp\fBXX\fp"
+partitions such as "/dev/md\fBNN\fPp\fBXX\fP"
are possible.
.PP
From kernel version 2.6.29 standard names can be non-numeric following
.I mdadm
was previously known as
.IR mdctl .
-.P
-.I mdadm
-is completely separate from the
-.I raidtools
-package, and does not use the
-.I /etc/raidtab
-configuration file at all.
.SH SEE ALSO
For further information on mdadm usage, MD and the various levels of
.B http://raid.wiki.kernel.org/
.PP
(based upon Jakob \(/Ostergaard's Software\-RAID.HOWTO)
-.\".PP
-.\"for new releases of the RAID driver check out:
-.\"
-.\".IP
-.\".UR ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
-.\"ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
-.\".UE
-.\".PP
-.\"or
-.\".IP
-.\".UR http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
-.\"http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
-.\".UE
.PP
The latest version of
.I mdadm
.IR mdmon (8),
.IR mdadm.conf (5),
.IR md (4).
-.PP
-.IR raidtab (5),
-.IR raid0run (8),
-.IR raidstop (8),
-.IR mkraid (8).
projects / thirdparty / mdadm.git / blobdiff