-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 Kilobytes) 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.
A suffix of 'K', 'M', 'G' or 'T' can be given to indicate
Kilobytes, Megabytes, Gigabytes or Terabytes 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 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 --grow for RAID level 1/4/5/6
though DDF arrays 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
--grow. The size can be given as max which means to
choose the largest size that fits on all current drives.
Before reducing the size of the array (with --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 --grow --size= command.
This value cannot be used when creating a CONTAINER such
as with DDF and IMSM metadata, though it perfectly valid
when creating an array inside a container.
-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 'K', 'M', 'G' or 'T' can be given to indicate
Kilobytes, Megabytes, Gigabytes or Terabytes respectively.
A value of max restores the apparent size of the array to
be whatever the real amount of available space is.
Clustered arrays do not support this parameter yet.
-c, --chunk=
Specify chunk size of kilobytes. The default when
creating an array is 512KB. To ensure compatibility with
earlier versions, the 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 of 2. In any case it must be a multiple of
4KB.
A suffix of 'K', 'M', 'G' or 'T' can be given to indicate
Kilobytes, Megabytes, Gigabytes or Terabytes 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. It can also be used for working around
a kernel bug with RAID0, but generally doesn't need to be
used explicitly.
The layout of the RAID5 parity block can be one of
left-asymmetric, left-symmetric, right-asymmetric,
right-symmetric, la, ra, ls, rs. The default is
left-symmetric.
It is also possible to cause RAID5 to use a RAID4-like
layout by choosing parity-first, or parity-last.
Finally for RAID5 there are DDF-compatible layouts,
ddf-zero-restart, ddf-N-restart, and ddf-N-continue.
These same layouts are available for RAID6. There are
also 4 layouts that will provide an intermediate stage for
converting between RAID5 and RAID6. These provide a
layout which is identical to the corresponding RAID5
layout on the first N-1 devices, and has the 'Q' syndrome
(the second 'parity' block used by RAID6) on the last
device. These layouts are: left-symmetric-6,
right-symmetric-6, left-asymmetric-6, right-asymmetric-6,
and parity-first-6.
When setting the failure mode for level faulty, the
options are: write-transient, wt, read-transient, rt,
write-persistent, wp, read-persistent, rp, write-all,
read-fixable, rf, clear, flush, none.
Each failure mode can be followed by a number, which is
used as a period between fault generation. Without a
number, the fault is generated once on the first relevant
request. With a number, the fault will be generated after
that many requests, and will continue to be generated
every time the period elapses.
Multiple failure modes can be current simultaneously by
using the --grow option to set subsequent failure modes.
"clear" or "none" will remove any pending or periodic
failure modes, and "flush" will clear any persistent
faults.
The layout options for RAID10 are one of 'n', 'o' or 'f'
followed by a small number. The default is 'n2'. The
supported options are:
'n' signals 'near' copies. Multiple copies of one data
block are at similar offsets in different devices.
'o' signals 'offset' copies. Rather than the chunks being
duplicated within a stripe, whole stripes are duplicated
but are rotated by one device so duplicate blocks are on
different devices. Thus subsequent copies of a block are
in the next drive, and are one chunk further down.
'f' signals 'far' copies (multiple copies have very
different offsets). See md(4) for more detail about
'near', 'offset', and 'far'.
The number is the number of copies of each datablock. 2
is normal, 3 can be useful. This number can be at most
equal to the number of devices in the array. It does not
need to divide evenly into that number (e.g. it is
perfectly legal to have an 'n2' layout for an array with
an odd number of devices).
A bug introduced in Linux 3.14 means that RAID0 arrays
with devices of differing sizes started using a different
layout. This could lead to data corruption. Since Linux
5.4 (and various stable releases that received backports),
the kernel will not accept such an array unless a layout
is explictly set. It can be set to 'original' or
'alternate'. When creating a new array, mdadm will select
'original' by default, so the layout does not normally
need to be set. An array created for either 'original' or
'alternate' will not be recognized by an (unpatched)
kernel prior to 5.4. To create a RAID0 array with devices
of differing sizes that can be used on an older kernel,
you can set the layout to 'dangerous'. This will use
whichever layout the running kernel supports, so the data
on the array may become corrupt when changing kernel from
pre-3.14 to a later kernel.
When an array is converted between RAID5 and RAID6 an
intermediate RAID6 layout is used in which the second
parity block (Q) is always on the last device. To convert
a RAID5 to RAID6 and leave it in this new layout (which
does not require re-striping) use --layout=preserve. This
will try to avoid any restriping.
The converse of this is --layout=normalise which will
change a non-standard RAID6 layout into a more standard
arrangement.
--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. If the word
clustered is given, the array is created for a clustered
environment. One bitmap is created for each node as
defined by the --nodes parameter and are stored
internally.
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.
When creating an array on devices which are 100G or
larger, mdadm automatically adds an internal bitmap as it
will usually be beneficial. This can be suppressed with
--bitmap=none or by selecting a different consistency
policy with --consistency-policy.
--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 'K', 'M', 'G' or 'T' can be given to indicate
Kilobytes, Megabytes, Gigabytes or Terabytes 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.
--failfast
subsequent devices listed in a --create or --add command
will be flagged as 'failfast'. This is valid for RAID1
and RAID10 only. IO requests to these devices will be
encouraged to fail quickly rather than cause long delays
due to error handling. Also no attempt is made to repair
a read error on these devices.
If an array becomes degraded so that the 'failfast' device
is the only usable device, the 'failfast' flag will then
be ignored and extended delays will be preferred to
complete failure.
The 'failfast' flag is appropriate for storage arrays
which have a low probability of true failure, but which
may sometimes cause unacceptable delays due to internal
maintenance functions.
--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.
--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 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 mdadm
which computed a different offset.
Setting the offset explicitly over-rides the default. The
value given is in Kilobytes unless a suffix of 'K', 'M',
'G' or 'T' is used to explicitly indicate Kilobytes,
Megabytes, Gigabytes or Terabytes respectively.
Since Linux 3.4, --data-offset can also be used with
--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.
When creating an array, --data-offset can be specified as
variable. In the case each member device is expected to
have a offset appended to the name, separated by a colon.
This makes it possible to recreate exactly an array which
has varying data offsets (as can happen when different
versions of mdadm are used to add different devices).
--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.
-o, --readonly
Start the array 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. It works
with Create, Assemble, Manage and Misc mode.
-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.
The argument can also come immediately after "-a". e.g.
"-ap".
If --auto is not given on the command line or in the
config file, then the default will be --auto=yes.
If --scan is also given, then any auto= entries in the
config file will override the --auto instruction given on
the command line.
For partitionable arrays, mdadm will create the device
file for the whole array and for the first 4 partitions.
A different number of partitions can be specified at the
end of this option (e.g. --auto=p7). If the device name
ends with a digit, the partition names add a 'p', and a
number, e.g. /dev/md/home1p3. If there is no trailing
digit, then the partition names just have a number added,
e.g. /dev/md/scratch3.
If the md device name is in a 'standard' format as
described in DEVICE NAMES, then it will be created, if
necessary, with the appropriate device number based on
that name. If the device name is not in one of these
formats, then a unused device number will be allocated.
The device number will be considered unused if there is no
active array for that number, and there is no entry in
/dev for that number and with a non-standard name. Names
that are not in 'standard' format are only allowed in
"/dev/md/".
This is meaningful with --create or --build.
-a, --add
This option can be used in Grow mode in two cases.
If the target array is a Linear array, then --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 --raid-disks option is being used to increase the
number of devices in an array, then --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.
--nodes
Only works when the array is for clustered environment. It
specifies the maximum number of nodes in the cluster that
will use this device simultaneously. If not specified,
this defaults to 4.
--write-journal
Specify journal device for the RAID-4/5/6 array. The
journal device should be a SSD with reasonable lifetime.
--symlinks
Auto creation of symlinks in /dev to /dev/md, option
--symlinks must be 'no' or 'yes' and work with --create
and --build.
-k, --consistency-policy=
Specify how the array maintains consistency in case of
unexpected shutdown. Only relevant for RAID levels with
redundancy. Currently supported options are:
resync Full resync is performed and all redundancy is
regenerated when the array is started after unclean
shutdown.
bitmap Resync assisted by a write-intent bitmap.
Implicitly selected when using --bitmap.
journal
For RAID levels 4/5/6, journal device is used to
log transactions and replay after unclean shutdown.
Implicitly selected when using --write-journal.
ppl For RAID5 only, Partial Parity Log is used to close
the write hole and eliminate resync. PPL is stored
in the metadata region of RAID member drives, no
additional journal drive is needed.
Can be used with --grow to change the consistency policy
of an active array in some cases. See CONSISTENCY POLICY
CHANGES below.
