-A, --assemble
Assemble a pre-existing array.
|
-B, --build
Build a legacy array without superblocks.
|
-C, --create
Create a new array.
|
-F, --follow, --monitor
Select Monitor mode.
|
-G, --grow
Change the size or shape of an active array.
|
-I, --incremental
Add/remove a single device to/from an appropriate array, and possibly start the array.
|
--auto-detect
Request that the kernel starts any auto-detected arrays. This can only work if md is compiled
into the kernel — not if it is a module. Arrays can be auto-detected by the kernel if all the
components are in primary MS-DOS partitions with partition type FD, and all use v0.90 metadata.
In-kernel autodetect is not recommended for new installations. Using mdadm to detect and assemble
arrays — possibly in an initrd — is substantially more flexible and should be preferred.
|
-h, --help
Display general help message or, after one of the above options, a mode-specific help message.
|
--help-options
Display more detailed help about command line parsing and some commonly used options.
|
-V, --version
Print version information for mdadm.
|
-v, --verbose
Be more verbose about what is happening. This can be used twice to be extra-verbose. The extra
verbosity currently only affects --detail --scan and --examine --scan.
|
-q, --quiet
Avoid printing purely informative messages. With this, mdadm will be silent unless there is
something really important to report.
|
-f, --force
Be more forceful about certain operations. See the various modes for the exact meaning of this
option in different contexts.
|
-c, --config=
Specify the config file. Default is to use /etc/mdadm/mdadm.conf, or if that is missing, then
/etc/mdadm.conf. If the config file given is partitions then nothing will be read, but mdadm will
act as though the config file contained exactly DEVICE partitions containers and will read
/proc/partitions to find a list of devices to scan, and /proc/mdstat to find a list of containers
to examine. If the word none is given for the config file, then mdadm will act as though the
config file were empty.
|
-s, --scan
Scan config file or /proc/mdstat for missing information. In general, this option gives mdadm
permission to get any missing information (like component devices, array devices, array
identities, and alert destination) from the configuration file (see previous option); one
exception is MISC mode when using --detail or --stop, in which case --scan says to get a list of
array devices from /proc/mdstat.
|
-e, --metadata=
Declare the style of RAID metadata (superblock) to be used. The default is 1.2 for --create, and
to guess for other operations. The default can be overridden by setting the metadata value for
the CREATE keyword in mdadm.conf.
|
--homehost=
This will override any HOMEHOST setting in the config file and provides the identity of the host
which should be considered the home for any arrays.
|
-n, --raid-devices=
Specify the number of active devices in the array. This, plus the number of spare devices (see
below) must equal the number of component-devices (including "missing" devices) that are listed on
the command line for --create. Setting a value of 1 is probably a mistake and so requires that
--force be specified first. A value of 1 will then be allowed for linear, multipath, RAID0 and
RAID1. It is never allowed for RAID4, RAID5 or RAID6.
This number can only be changed using --grow for RAID1, RAID4, RAID5 and RAID6 arrays, and only on
kernels which provide the necessary support.
|
-x, --spare-devices=
Specify the number of spare (eXtra) devices in the initial array. Spares can also be added and
removed later. The number of component devices listed on the command line must equal the number
of RAID devices plus the number of spare devices.
|
-z, --size=
Amount (in Kibibytes) of space to use from each drive in RAID levels 1/4/5/6. This must be a
multiple of the chunk size, and must leave about 128Kb of space at the end of the drive for the
RAID superblock. If this is not specified (as it normally is not) the smallest drive (or
partition) sets the size, though if there is a variance among the drives of greater than 1%, a
warning is issued.
|
-Z, --array-size=
This is only meaningful with --grow 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 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 --array-size is, it is required that the array size is
reduced as appropriate before the number of devices in the array is reduced.
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
--grow --array-size= command.
A suffix of 'M' or 'G' can be given to indicate Megabytes or Gigabytes respectively. A value of
max restores the apparent size of the array to be whatever the real amount of available space is.
|
-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. 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.
|
--rounding=
Specify rounding factor for a Linear array. The size of each component will be rounded down to a
multiple of this size. This is a synonym for --chunk but highlights the different meaning for
Linear as compared to other RAID levels. The default is 64K if a kernel earlier than 2.6.16 is in
use, and is 0K (i.e. no rounding) in later kernels.
|
-l, --level=
Set RAID level. When used with --create, options are: linear, raid0, 0, stripe, raid1, 1, mirror,
raid4, 4, raid5, 5, raid6, 6, raid10, 10, multipath, mp, faulty, container. Obviously some of
these are synonymous.
When a CONTAINER metadata type is requested, only the container level is permitted, and it does
not need to be explicitly given.
When used with --build, only linear, stripe, raid0, 0, raid1, multipath, mp, and faulty are valid.
Can be used with --grow to change the RAID level in some cases. See LEVEL CHANGES below.
|
-p, --layout=
This option configures the fine details of data layout for RAID5, RAID6, and RAID10 arrays, and
controls the failure modes for faulty.
|
--parity=
same as --layout (thus explaining the p of -p).
|
-b, --bitmap=
Specify a file to store a write-intent bitmap in. The file should not exist unless --force is
also given. The same file should be provided when assembling the array. If the word internal is
given, then the bitmap is stored with the metadata on the array, and so is replicated on all
devices. If the word none is given with --grow mode, then any bitmap that is present is removed.
To help catch typing errors, the filename must contain at least one slash ('/') if it is a real
file (not 'internal' or 'none').
Note: external bitmaps are only known to work on ext2 and ext3. Storing bitmap files on other
filesystems may result in serious problems.
|
--bitmap-chunk=
Set the chunksize of the bitmap. Each bit corresponds to that many Kilobytes of storage. When
using a file based bitmap, the default is to use the smallest size that is at-least 4 and requires
no more than 2^21 chunks. When using an internal 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.
|
-W, --write-mostly
subsequent devices listed in a --build, --create, or --add command will be flagged as 'write-
mostly'. This is valid for RAID1 only and means that the 'md' driver will avoid reading from
these devices if at all possible. This can be useful if mirroring over a slow link.
|
--write-behind=
Specify that write-behind mode should be enabled (valid for RAID1 only). If an argument is
specified, it will set the maximum number of outstanding writes allowed. The default value is
256. A write-intent bitmap is required in order to use write-behind mode, and write-behind is
only attempted on drives marked as write-mostly.
|
--assume-clean
Tell mdadm that the array pre-existed and is known to be clean. It can be useful when trying to
recover from a major failure as you can be sure that no data will be affected unless you actually
write to the array. It can also be used when creating a RAID1 or RAID10 if you want to avoid the
initial resync, however this practice — while normally safe — is not recommended. Use this only
if you really know what you are doing.
When the devices that will be part of a new array were filled with zeros before creation the
operator knows the array is 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.
When an array is resized to a larger size with --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,
--assume-clean can be used with that command to avoid the automatic resync.
|
--backup-file=
This is needed when --grow 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.
|
--continue
This option is complementary to the --freeze-reshape option for assembly. It is needed when --grow
operation is interrupted and it is not restarted automatically due to --freeze-reshape usage
during array assembly. This option is used together with -G , ( --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 --grow command had required --backup-file= option to be set,
continuation option will require to have exactly the same backup file given as well.
Any other parameter passed together with --continue option will be ignored.
|
-N, --name=
Set a name for the array. This is currently only effective when creating an array with a
version-1 superblock, or an array in a DDF container. The name is a simple textual string that
can be used to identify array components when assembling. If name is needed but not specified, it
is taken from the basename of the device that is being created. e.g. when creating /dev/md/home
the name will default to home.
|
-R, --run
Insist that mdadm run the array, even if some of the components appear to be active in another
array or filesystem. Normally mdadm will ask for confirmation before including such components in
an array. This option causes that question to be suppressed.
|
-f, --force
Insist that mdadm accept the geometry and layout specified without question. Normally mdadm will
not allow creation of an array with only one device, and will try to create a RAID5 array with one
missing drive (as this makes the initial resync work faster). With --force, mdadm will not try to
be so clever.
|
-a, --auto{=yes,md,mdp,part,p}{NN}
Instruct mdadm how to create the device file if needed, possibly allocating an unused minor
number. "md" causes a non-partitionable array to be used (though since Linux 2.6.28, these array
devices are in fact partitionable). "mdp", "part" or "p" causes a partitionable array (2.6 and
later) to be used. "yes" requires the named md device to have a 'standard' format, and the type
and minor number will be determined from this. With mdadm 3.0, device creation is normally left
up to udev so this option is unlikely to be needed. See DEVICE NAMES below.
|
-a, --add
This option can be used in Grow mode in two cases.
|
-u, --uuid=
uuid of array to assemble. Devices which don't have this uuid are excluded
|
-m, --super-minor=
Minor number of device that array was created for. Devices which don't have this minor number are
excluded. If you create an array as /dev/md1, then all superblocks will contain the minor number
1, even if the array is later assembled as /dev/md2.
Giving the literal word "dev" for --super-minor will cause mdadm to use the minor number of the md
device that is being assembled. e.g. when assembling /dev/md0, --super-minor=dev will look for
super blocks with a minor number of 0.
--super-minor is only relevant for v0.90 metadata, and should not normally be used. Using --uuid
is much safer.
|
-N, --name=
Specify the name of the array to assemble. This must be the name that was specified when creating
the array. It must either match the name stored in the superblock exactly, or it must match with
the current homehost prefixed to the start of the given name.
|
-f, --force
Assemble the array even if the metadata on some devices appears to be out-of-date. If mdadm
cannot find enough working devices to start the array, but can find some devices that are recorded
as having failed, then it will mark those devices as working so that the array can be started. An
array which requires --force to be started may contain data corruption. Use it carefully.
|
-R, --run
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 --scan is not used, then the
array will be assembled but not started. With --run an attempt will be made to start it anyway.
|
--no-degraded
This is the reverse of --run in that it inhibits the startup of array unless all expected drives
are present. This is only needed with --scan, and can be used if the physical connections to
devices are not as reliable as you would like.
|
-a, --auto{=no,yes,md,mdp,part}
See this option under Create and Build options.
|
-b, --bitmap=
Specify the bitmap file that was given when the array was created. If an array has an internal
bitmap, there is no need to specify this when assembling the array.
|
--backup-file=
If --backup-file 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 --backup-file must be presented
to --assemble to allow possibly corrupted data to be restored, and the reshape to be completed.
|
--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.
|
-U, --update=
Update the superblock on each device while assembling the array. The argument given to this flag
can be one of sparc2.2, summaries, uuid, name, homehost, resync, byteorder, devicesize, no-bitmap,
or super-minor.
|
--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.
|
-t, --test
Unless a more serious error occurred, 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 missing, detached or faulty is used in requesting an operation on the array. --test will
report failure if these specifiers didn't find any match.
|
-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 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.
|
--re-add
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 --build) it will be assumed
that bitmap-based recovery is enough to make the device fully consistent with the array.
When --re-add can be accompanied by --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 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.
|
-r, --remove
remove listed devices. They must not be active. i.e. they should be failed or spare devices. As
well as the name of a device file (e.g. /dev/sda1) the words failed and detached can be given to
--remove. The first causes all failed device to be removed. The second causes any device which
is no longer connected to the system (i.e an 'open' returns ENXIO) to be removed. This will only
succeed for devices that are spares or have already been marked as failed.
|
-f, --fail
mark listed devices as faulty. As well as the name of a device file, the word detached can be
given. This will cause any device that has been detached from the system to be marked as failed.
It can then be removed.
|
--set-faulty
same as --fail.
--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.
|
--readwrite
Subsequent devices that are added or re-added will have the 'write-mostly' flag cleared.
|
-Q, --query
Examine a device to see (1) if it is an md device and (2) if it is a component of an md array.
Information about what is discovered is presented.
|
-D, --detail
Print details of one or more md devices.
|
--detail-platform
Print details of the platform's RAID capabilities (firmware / hardware topology) for a given
metadata format.
|
-Y, --export
When used with --detail or --examine, output will be formatted as key=value pairs for easy import
into the environment.
|
-E, --examine
Print contents of the metadata stored on the named device(s). Note the contrast between --examine
and --detail. --examine applies to devices which are components of an array, while --detail
applies to a whole array which is currently active.
|
-X, --examine-bitmap
Report information about a bitmap file. The argument is either an external bitmap file or an
array component in case of an internal bitmap. Note that running this on an array device (e.g.
/dev/md0) does not report the bitmap for that array.
|
-R, --run
start a partially assembled array. If --assemble did not find enough devices to fully start the
array, it might leaving it partially assembled. If you wish, you can then use --run to start the
array in degraded mode.
|
-S, --stop
deactivate array, releasing all resources.
|
-o, --readonly
mark array as readonly.
|
-w, --readwrite
mark array as readwrite.
|
--zero-superblock
If the device contains a valid md superblock, the block is overwritten with zeros. With --force
the block where the superblock would be is overwritten even if it doesn't appear to be valid.
|
--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.
|
--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 MISC
MODE for details.
|
-t, --test
When used with --detail, the exit status of mdadm is set to reflect the status of the device. See
below in MISC MODE for details.
|
-W, --wait
For each md device given, wait for any resync, recovery, or reshape activity to finish before
returning. mdadm will return with success if it actually waited for every device listed,
otherwise it will return failure.
|
--wait-clean
For each md device given, or each device in /proc/mdstat if --scan is given, arrange for the array
to be marked clean as soon as possible. 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 dirty-clean transitions at shutdown. No action is taken if safe-mode handling is
disabled.
|
--rebuild-map, -r
Rebuild the map file (/var/run/mdadm/map) that mdadm uses to help track which arrays are currently
being assembled.
|
--run, -R
Run any array assembled as soon as a minimal number of devices are available, rather than waiting
until all expected devices are present.
|
--scan, -s
Only meaningful with -R this will scan the map file for arrays that are being incrementally
assembled and will try to start any that are not already started. If any such array is listed in
mdadm.conf as requiring an external bitmap, that bitmap will be attached first.
|
--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 /dev.
|
--path=
Only used with --fail. The 'path' given will be recorded so that if a new device appears at the
same location it can be automatically added to the same array. This allows the failed device to
be automatically replaced by a new device without metadata if it appears at specified path. This
option is normally only set by a udev script.
|
-m, --mail
Give a mail address to send alerts to.
|
-p, --program, --alert
Give a program to be run whenever an event is detected.
|
-y, --syslog
Cause all events to be reported through 'syslog'. The messages have facility of 'daemon' and
varying priorities.
|
-d, --delay
Give a delay in seconds. mdadm polls the md arrays and then waits this many seconds before
polling again. The default is 60 seconds. Since 2.6.16, there is no need to reduce this as the
kernel alerts mdadm immediately when there is any change.
|
-r, --increment
Give a percentage increment. mdadm will generate RebuildNN events with the given percentage
increment.
|
-f, --daemonise
Tell mdadm to run as a background daemon if it decides to monitor anything. This causes it to
fork and run in the child, and to disconnect from the terminal. The process id of the child is
written to stdout. This is useful with --scan which will only continue monitoring if a mail
address or alert program is found in the config file.
|
-i, --pid-file
When mdadm is running in daemon mode, write the pid of the daemon process to the specified file,
instead of printing it on standard output.
|
-1, --oneshot
Check arrays only once. This will generate NewArray events and more significantly DegradedArray
and SparesMissing events. Running
mdadm --monitor --scan -1
from a cron script will ensure regular notification of any degraded arrays.
|
-t, --test
Generate a TestMessage alert for every array found at startup. This alert gets mailed and passed
to the alert program. This can be used for testing that alert message do get through
successfully.
|
--no-sharing
This inhibits the functionality for moving spares between arrays. Only one monitoring process
started with --scan but without this flag is allowed, otherwise the two could interfere with each
other.
|
--run insist on running the array even if some devices look like they might be in use.
|
--readonly
start the array readonly — not supported yet.
|
--query
The device is examined to see if it is (1) an active md array, or (2) a component of an md array.
The information discovered is reported.
|
--detail
The device should be an active md device. mdadm will display a detailed description of the array.
--brief or --scan will cause the output to be less detailed and the format to be suitable for
inclusion in /etc/mdadm/mdadm.conf. The exit status of mdadm will normally be 0 unless mdadm
failed to get useful information about the device(s); however, if the --test option is given, then
the exit status will be:
0 The array is functioning normally.
1 The array has at least one failed device.
2 The array has multiple failed devices such that it is unusable.
4 There was an error while trying to get information about the device.
|
--detail-platform
Print detail of the platform's RAID capabilities (firmware / hardware topology). If the metadata
is specified with -e or --metadata= then the return status will be:
0 metadata successfully enumerated its platform components on this system
1 metadata is platform independent
2 metadata failed to find its platform components on this system
|
--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 -U or --update= option. Currently
only name is supported.
The 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 name would change the
UUID of an active subarray this operation is blocked, and the command will end in an error.
--examine
The device should be a component of an md array. mdadm will read the md superblock of the device
and display the contents. If --brief or --scan is given, then multiple devices that are
components of the one array are grouped together and reported in a single entry suitable for
inclusion in /etc/mdadm/mdadm.conf.
Having --scan without listing any devices will cause all devices listed in the config file to be
examined.
--stop The devices should be active md arrays which will be deactivated, as long as they are not
currently in use.
|
--run This will fully activate a partially assembled md array.
|
--readonly
This will mark an active array as read-only, providing that it is not currently being used.
|
--readwrite
This will change a readonly array back to being read/write.
--scan For all operations except --examine, --scan will cause the operation to be applied to all arrays
listed in /proc/mdstat. For --examine, --scan causes all devices listed in the config file to be
examined.
|
-b, --brief
Be less verbose. This is used with --detail and --examine. Using --brief with --verbose gives an
intermediate level of verbosity.
|