]> git.ipfire.org Git - thirdparty/mdadm.git/blame - mdadm.8.in
Restructure assemble_container_content and improve messages.
[thirdparty/mdadm.git] / mdadm.8.in
CommitLineData
52826846 1.\" -*- nroff -*-
e43d0cda
NB
2.\" Copyright Neil Brown and others.
3.\" This program is free software; you can redistribute it and/or modify
4.\" it under the terms of the GNU General Public License as published by
5.\" the Free Software Foundation; either version 2 of the License, or
6.\" (at your option) any later version.
7.\" See file COPYING in distribution for details.
6f02172d 8.TH MDADM 8 "" v3.3
52826846 9.SH NAME
9a9dab36 10mdadm \- manage MD devices
cd29a5c8 11.I aka
93e790af 12Linux Software RAID
cd29a5c8 13
52826846
NB
14.SH SYNOPSIS
15
e0d19036 16.BI mdadm " [mode] <raiddevice> [options] <component-devices>"
52826846 17
2ae555c3 18.SH DESCRIPTION
52826846 19RAID devices are virtual devices created from two or more
e0fe762a 20real block devices. This allows multiple devices (typically disk
35cc5be4 21drives or partitions thereof) to be combined into a single device to
cd29a5c8 22hold (for example) a single filesystem.
2d465520 23Some RAID levels include redundancy and so can survive some degree of
cd29a5c8
NB
24device failure.
25
2d465520
NB
26Linux Software RAID devices are implemented through the md (Multiple
27Devices) device driver.
cd29a5c8
NB
28
29Currently, Linux supports
30.B LINEAR
31md devices,
32.B RAID0
33(striping),
34.B RAID1
35(mirroring),
d013a55e
NB
36.BR RAID4 ,
37.BR RAID5 ,
98c6faba 38.BR RAID6 ,
1a7dfc35 39.BR RAID10 ,
b5e64645 40.BR MULTIPATH ,
90c8d668 41.BR FAULTY ,
cd29a5c8 42and
90c8d668 43.BR CONTAINER .
d013a55e 44
a9d69660
NB
45.B MULTIPATH
46is not a Software RAID mechanism, but does involve
93e790af 47multiple devices:
d013a55e 48each device is a path to one common physical storage device.
9652457e
N
49New installations should not use md/multipath as it is not well
50supported and has no ongoing development. Use the Device Mapper based
51multipath-tools instead.
d013a55e 52
a9d69660
NB
53.B FAULTY
54is also not true RAID, and it only involves one device. It
b5e64645 55provides a layer over a true device that can be used to inject faults.
52826846 56
4cce4069 57.B CONTAINER
8fd8d9c4
N
58is different again. A
59.B CONTAINER
60is a collection of devices that are
90c8d668
N
61managed as a set. This is similar to the set of devices connected to
62a hardware RAID controller. The set of devices may contain a number
9652457e 63of different RAID arrays each utilising some (or all) of the blocks from a
90c8d668 64number of the devices in the set. For example, two devices in a 5-device set
9652457e 65might form a RAID1 using the whole devices. The remaining three might
90c8d668
N
66have a RAID5 over the first half of each device, and a RAID0 over the
67second half.
68
8fd8d9c4
N
69With a
70.BR CONTAINER ,
71there is one set of metadata that describes all of
72the arrays in the container. So when
73.I mdadm
74creates a
75.B CONTAINER
9652457e
N
76device, the device just represents the metadata. Other normal arrays (RAID1
77etc) can be created inside the container.
52826846
NB
78
79.SH MODES
8382f19b 80mdadm has several major modes of operation:
cd29a5c8
NB
81.TP
82.B Assemble
93e790af 83Assemble the components of a previously created
e0fe762a 84array into an active array. Components can be explicitly given
2ae555c3 85or can be searched for.
51ac42e3 86.I mdadm
cd29a5c8
NB
87checks that the components
88do form a bona fide array, and can, on request, fiddle superblock
89information so as to assemble a faulty array.
90
91.TP
92.B Build
e0fe762a 93Build an array that doesn't have per-device metadata (superblocks). For these
a9d69660
NB
94sorts of arrays,
95.I mdadm
96cannot differentiate between initial creation and subsequent assembly
97of an array. It also cannot perform any checks that appropriate
93e790af 98components have been requested. Because of this, the
a9d69660
NB
99.B Build
100mode should only be used together with a complete understanding of
101what you are doing.
cd29a5c8
NB
102
103.TP
104.B Create
e0fe762a
N
105Create a new array with per-device metadata (superblocks).
106Appropriate metadata is written to each device, and then the array
107comprising those devices is activated. A 'resync' process is started
108to make sure that the array is consistent (e.g. both sides of a mirror
109contain the same data) but the content of the device is left otherwise
110untouched.
111The array can be used as soon as it has been created. There is no
112need to wait for the initial resync to finish.
cd29a5c8 113
cd29a5c8
NB
114.TP
115.B "Follow or Monitor"
5787fa49 116Monitor one or more md devices and act on any state changes. This is
e0fe762a
N
117only meaningful for RAID1, 4, 5, 6, 10 or multipath arrays, as
118only these have interesting state. RAID0 or Linear never have
98c6faba 119missing, spare, or failed drives, so there is nothing to monitor.
5787fa49 120
dd0781e5
NB
121.TP
122.B "Grow"
123Grow (or shrink) an array, or otherwise reshape it in some way.
124Currently supported growth options including changing the active size
c64881d7
N
125of component devices and changing the number of active devices in
126Linear and RAID levels 0/1/4/5/6,
127changing the RAID level between 0, 1, 5, and 6, and between 0 and 10,
17790db6 128changing the chunk size and layout for RAID 0,4,5,6,10 as well as adding or
f24e2d6c 129removing a write-intent bitmap.
cd29a5c8 130
8382f19b
NB
131.TP
132.B "Incremental Assembly"
133Add a single device to an appropriate array. If the addition of the
134device makes the array runnable, the array will be started.
135This provides a convenient interface to a
136.I hot-plug
137system. As each device is detected,
138.I mdadm
139has a chance to include it in some array as appropriate.
29ba4804
N
140Optionally, when the
141.I \-\-fail
142flag is passed in we will remove the device from any active array
143instead of adding it.
9652457e 144
8fd8d9c4
N
145If a
146.B CONTAINER
147is passed to
148.I mdadm
149in this mode, then any arrays within that container will be assembled
150and started.
8382f19b 151
2ae555c3
NB
152.TP
153.B Manage
154This is for doing things to specific components of an array such as
155adding new spares and removing faulty devices.
156
157.TP
158.B Misc
159This is an 'everything else' mode that supports operations on active
160arrays, operations on component devices such as erasing old superblocks, and
161information gathering operations.
e43d0cda
NB
162.\"This mode allows operations on independent devices such as examine MD
163.\"superblocks, erasing old superblocks and stopping active arrays.
2ae555c3 164
1f48664b
NB
165.TP
166.B Auto-detect
167This mode does not act on a specific device or array, but rather it
168requests the Linux Kernel to activate any auto-detected arrays.
52826846
NB
169.SH OPTIONS
170
2ae555c3 171.SH Options for selecting a mode are:
52826846 172
cd29a5c8 173.TP
7e23fc43 174.BR \-A ", " \-\-assemble
2d465520 175Assemble a pre-existing array.
52826846 176
cd29a5c8 177.TP
7e23fc43 178.BR \-B ", " \-\-build
cd29a5c8 179Build a legacy array without superblocks.
52826846 180
cd29a5c8 181.TP
7e23fc43 182.BR \-C ", " \-\-create
cd29a5c8 183Create a new array.
52826846 184
cd29a5c8 185.TP
7e23fc43 186.BR \-F ", " \-\-follow ", " \-\-monitor
cd29a5c8
NB
187Select
188.B Monitor
189mode.
52826846 190
dd0781e5 191.TP
7e23fc43 192.BR \-G ", " \-\-grow
dd0781e5 193Change the size or shape of an active array.
8382f19b
NB
194
195.TP
1f48664b 196.BR \-I ", " \-\-incremental
29ba4804 197Add/remove a single device to/from an appropriate array, and possibly start the array.
8382f19b 198
1f48664b
NB
199.TP
200.B \-\-auto-detect
201Request that the kernel starts any auto-detected arrays. This can only
202work if
203.I md
204is compiled into the kernel \(em not if it is a module.
205Arrays can be auto-detected by the kernel if all the components are in
206primary MS-DOS partitions with partition type
e0fe762a
N
207.BR FD ,
208and all use v0.90 metadata.
1f48664b
NB
209In-kernel autodetect is not recommended for new installations. Using
210.I mdadm
211to detect and assemble arrays \(em possibly in an
212.I initrd
213\(em is substantially more flexible and should be preferred.
214
2ae555c3
NB
215.P
216If a device is given before any options, or if the first option is
f33a71f1 217and of
7e23fc43 218.BR \-\-add ,
f33a71f1
N
219.BR \-\-re\-add ,
220.BR \-\-add\-spare ,
7e23fc43 221.BR \-\-fail ,
7e23fc43 222.BR \-\-remove ,
70c55e36
N
223or
224.BR \-\-replace ,
e0fe762a 225then the MANAGE mode is assumed.
2ae555c3
NB
226Anything other than these will cause the
227.B Misc
228mode to be assumed.
dd0781e5 229
2ae555c3 230.SH Options that are not mode-specific are:
e793c2e5 231
cd29a5c8 232.TP
7e23fc43 233.BR \-h ", " \-\-help
a9d69660 234Display general help message or, after one of the above options, a
93e790af 235mode-specific help message.
56eedc1a
NB
236
237.TP
7e23fc43 238.B \-\-help\-options
56eedc1a
NB
239Display more detailed help about command line parsing and some commonly
240used options.
52826846 241
cd29a5c8 242.TP
7e23fc43 243.BR \-V ", " \-\-version
9a9dab36 244Print version information for mdadm.
52826846 245
cd29a5c8 246.TP
7e23fc43 247.BR \-v ", " \-\-verbose
22892d56
NB
248Be more verbose about what is happening. This can be used twice to be
249extra-verbose.
a9d69660 250The extra verbosity currently only affects
7e23fc43 251.B \-\-detail \-\-scan
22892d56 252and
7e23fc43 253.BR "\-\-examine \-\-scan" .
52826846 254
dab6685f 255.TP
7e23fc43 256.BR \-q ", " \-\-quiet
dab6685f 257Avoid printing purely informative messages. With this,
51ac42e3 258.I mdadm
dab6685f
NB
259will be silent unless there is something really important to report.
260
08ca2adf 261
e0d19036 262.TP
7e23fc43 263.BR \-f ", " \-\-force
93e790af 264Be more forceful about certain operations. See the various modes for
e0d19036
NB
265the exact meaning of this option in different contexts.
266
267.TP
7e23fc43 268.BR \-c ", " \-\-config=
9dc70cbc
N
269Specify the config file or directory. Default is to use
270.B /etc/mdadm.conf
271and
272.BR /etc/mdadm.conf.d ,
273or if those are missing then
274.B /etc/mdadm/mdadm.conf
275and
276.BR /etc/mdadm/mdadm.conf.d .
5787fa49 277If the config file given is
93e790af 278.B "partitions"
5787fa49
NB
279then nothing will be read, but
280.I mdadm
281will act as though the config file contained exactly
9dc70cbc
N
282.br
283.B " DEVICE partitions containers"
284.br
5787fa49
NB
285and will read
286.B /proc/partitions
8fd8d9c4
N
287to find a list of devices to scan, and
288.B /proc/mdstat
289to find a list of containers to examine.
d013a55e 290If the word
93e790af 291.B "none"
d013a55e
NB
292is given for the config file, then
293.I mdadm
294will act as though the config file were empty.
e0d19036 295
9dc70cbc
N
296If the name given is of a directory, then
297.I mdadm
298will collect all the files contained in the directory with a name ending
299in
300.BR .conf ,
301sort them lexically, and process all of those files as config files.
302
e0d19036 303.TP
7e23fc43 304.BR \-s ", " \-\-scan
93e790af 305Scan config file or
e0d19036
NB
306.B /proc/mdstat
307for missing information.
308In general, this option gives
51ac42e3 309.I mdadm
93e790af
SW
310permission to get any missing information (like component devices,
311array devices, array identities, and alert destination) from the
312configuration file (see previous option);
313one exception is MISC mode when using
7e23fc43 314.B \-\-detail
e0d19036 315or
93e790af 316.B \-\-stop,
e0d19036 317in which case
7e23fc43 318.B \-\-scan
e0d19036
NB
319says to get a list of array devices from
320.BR /proc/mdstat .
321
570c0542 322.TP
d16c7af6 323.BR \-e ", " \-\-metadata=
e0fe762a 324Declare the style of RAID metadata (superblock) to be used. The
26f467a9 325default is {DEFAULT_METADATA} for
7e23fc43 326.BR \-\-create ,
53e8b987 327and to guess for other operations.
2790ffe3
GB
328The default can be overridden by setting the
329.B metadata
330value for the
331.B CREATE
332keyword in
333.BR mdadm.conf .
570c0542
NB
334
335Options are:
336.RS
26f467a9 337.ie '{DEFAULT_METADATA}'0.90'
338.IP "0, 0.90, default"
339.el
7d5c3964 340.IP "0, 0.90"
570c0542 341Use the original 0.90 format superblock. This format limits arrays to
93e790af 34228 component devices and limits component devices of levels 1 and
cd19c0cf
JR
343greater to 2 terabytes. It is also possible for there to be confusion
344about whether the superblock applies to a whole device or just the
345last partition, if that partition starts on a 64K boundary.
26f467a9 346.ie '{DEFAULT_METADATA}'0.90'
347.IP "1, 1.0, 1.1, 1.2"
348.el
7d5c3964 349.IP "1, 1.0, 1.1, 1.2 default"
cd19c0cf
JR
350Use the new version-1 format superblock. This has fewer restrictions.
351It can easily be moved between hosts with different endian-ness, and a
352recovery operation can be checkpointed and restarted. The different
353sub-versions store the superblock at different locations on the
354device, either at the end (for 1.0), at the start (for 1.1) or 4K from
7050aa3f
N
355the start (for 1.2). "1" is equivalent to "1.2" (the commonly
356preferred 1.x format).
26f467a9 357'if '{DEFAULT_METADATA}'1.2' "default" is equivalent to "1.2".
8fd8d9c4 358.IP ddf
e0fe762a
N
359Use the "Industry Standard" DDF (Disk Data Format) format defined by
360SNIA.
361When creating a DDF array a
8fd8d9c4
N
362.B CONTAINER
363will be created, and normal arrays can be created in that container.
364.IP imsm
4cce4069 365Use the Intel(R) Matrix Storage Manager metadata format. This creates a
8fd8d9c4 366.B CONTAINER
4cce4069
DW
367which is managed in a similar manner to DDF, and is supported by an
368option-rom on some platforms:
369.IP
370.B http://www.intel.com/design/chipsets/matrixstorage_sb.htm
371.PP
570c0542
NB
372.RE
373
41a3b72a 374.TP
7e23fc43 375.B \-\-homehost=
35cc5be4 376This will override any
41a3b72a 377.B HOMEHOST
93e790af 378setting in the config file and provides the identity of the host which
41a3b72a
NB
379should be considered the home for any arrays.
380
381When creating an array, the
382.B homehost
e0fe762a 383will be recorded in the metadata. For version-1 superblocks, it will
93e790af 384be prefixed to the array name. For version-0.90 superblocks, part of
41a3b72a
NB
385the SHA1 hash of the hostname will be stored in the later half of the
386UUID.
387
388When reporting information about an array, any array which is tagged
389for the given homehost will be reported as such.
390
391When using Auto-Assemble, only arrays tagged for the given homehost
0ac91628 392will be allowed to use 'local' names (i.e. not ending in '_' followed
e0fe762a
N
393by a digit string). See below under
394.BR "Auto Assembly" .
41a3b72a 395
c2ecf5f6
N
396.TP
397.B \-\-prefer=
398When
399.I mdadm
400needs to print the name for a device it normally finds the name in
401.B /dev
402which refers to the device and is shortest. When a path component is
403given with
404.B \-\-prefer
405.I mdadm
406will prefer a longer name if it contains that component. For example
407.B \-\-prefer=by-uuid
408will prefer a name in a subdirectory of
409.B /dev
410called
411.BR by-uuid .
412
413This functionality is currently only provided by
414.B \-\-detail
415and
416.BR \-\-monitor .
417
2ae555c3
NB
418.SH For create, build, or grow:
419
420.TP
7e23fc43 421.BR \-n ", " \-\-raid\-devices=
2ae555c3
NB
422Specify the number of active devices in the array. This, plus the
423number of spare devices (see below) must equal the number of
424.I component-devices
425(including "\fBmissing\fP" devices)
426that are listed on the command line for
e0fe762a 427.BR \-\-create .
2ae555c3
NB
428Setting a value of 1 is probably
429a mistake and so requires that
7e23fc43 430.B \-\-force
2ae555c3 431be specified first. A value of 1 will then be allowed for linear,
e0fe762a 432multipath, RAID0 and RAID1. It is never allowed for RAID4, RAID5 or RAID6.
2ae555c3
NB
433.br
434This number can only be changed using
7e23fc43 435.B \-\-grow
e0fe762a
N
436for RAID1, RAID4, RAID5 and RAID6 arrays, and only on kernels which provide
437the necessary support.
2ae555c3
NB
438
439.TP
7e23fc43 440.BR \-x ", " \-\-spare\-devices=
2ae555c3
NB
441Specify the number of spare (eXtra) devices in the initial array.
442Spares can also be added
443and removed later. The number of component devices listed
e0fe762a 444on the command line must equal the number of RAID devices plus the
2ae555c3
NB
445number of spare devices.
446
2ae555c3 447.TP
7e23fc43 448.BR \-z ", " \-\-size=
e0fe762a 449Amount (in Kibibytes) of space to use from each drive in RAID levels 1/4/5/6.
2ae555c3
NB
450This must be a multiple of the chunk size, and must leave about 128Kb
451of space at the end of the drive for the RAID superblock.
452If this is not specified
453(as it normally is not) the smallest drive (or partition) sets the
454size, though if there is a variance among the drives of greater than 1%, a warning is
455issued.
456
36fad8ec
N
457A suffix of 'M' or 'G' can be given to indicate Megabytes or
458Gigabytes respectively.
459
9ab6e80a
N
460Sometimes a replacement drive can be a little smaller than the
461original drives though this should be minimised by IDEMA standards.
462Such a replacement drive will be rejected by
463.IR md .
464To guard against this it can be useful to set the initial size
465slightly smaller than the smaller device with the aim that it will
466still be larger than any replacement.
467
2ae555c3 468This value can be set with
7e23fc43 469.B \-\-grow
9ab6e80a
N
470for RAID level 1/4/5/6 though
471.B CONTAINER
472based arrays such as those with IMSM metadata may not be able to
473support this.
474If the array was created with a size smaller than the currently
475active drives, the extra space can be accessed using
7e23fc43 476.BR \-\-grow .
2ae555c3
NB
477The size can be given as
478.B max
479which means to choose the largest size that fits on all current drives.
52826846 480
c26d78fe
N
481Before reducing the size of the array (with
482.BR "\-\-grow \-\-size=" )
483you should make sure that space isn't needed. If the device holds a
484filesystem, you would need to resize the filesystem to use less space.
485
486After reducing the array size you should check that the data stored in
487the device is still available. If the device holds a filesystem, then
488an 'fsck' of the filesystem is a minimum requirement. If there are
489problems the array can be made bigger again with no loss with another
490.B "\-\-grow \-\-size="
491command.
492
9ab6e80a 493This value cannot be used when creating a
8fd8d9c4 494.B CONTAINER
9ab6e80a
N
495such as with DDF and IMSM metadata, though it perfectly valid when
496creating an array inside a container.
8fd8d9c4 497
f24e2d6c 498.TP
c26d78fe 499.BR \-Z ", " \-\-array\-size=
f24e2d6c
N
500This is only meaningful with
501.B \-\-grow
36fad8ec 502and its effect is not persistent: when the array is stopped and
f24e2d6c
N
503restarted the default array size will be restored.
504
505Setting the array-size causes the array to appear smaller to programs
506that access the data. This is particularly needed before reshaping an
507array so that it will be smaller. As the reshape is not reversible,
508but setting the size with
509.B \-\-array-size
510is, it is required that the array size is reduced as appropriate
511before the number of devices in the array is reduced.
512
c26d78fe
N
513Before reducing the size of the array you should make sure that space
514isn't needed. If the device holds a filesystem, you would need to
515resize the filesystem to use less space.
516
517After reducing the array size you should check that the data stored in
518the device is still available. If the device holds a filesystem, then
519an 'fsck' of the filesystem is a minimum requirement. If there are
520problems the array can be made bigger again with no loss with another
521.B "\-\-grow \-\-array\-size="
522command.
523
36fad8ec
N
524A suffix of 'M' or 'G' can be given to indicate Megabytes or
525Gigabytes respectively.
526A value of
527.B max
528restores the apparent size of the array to be whatever the real
529amount of available space is.
530
cd29a5c8 531.TP
7e23fc43 532.BR \-c ", " \-\-chunk=
5f175898
N
533Specify chunk size of kibibytes. The default when creating an
534array is 512KB. To ensure compatibility with earlier versions, the
422da715 535default when building an array with no persistent metadata is 64KB.
e0fe762a 536This is only meaningful for RAID0, RAID4, RAID5, RAID6, and RAID10.
52826846 537
a252c078
N
538RAID4, RAID5, RAID6, and RAID10 require the chunk size to be a power
539of 2. In any case it must be a multiple of 4KB.
540
36fad8ec
N
541A suffix of 'M' or 'G' can be given to indicate Megabytes or
542Gigabytes respectively.
543
cd29a5c8 544.TP
7e23fc43 545.BR \-\-rounding=
e0fe762a
N
546Specify rounding factor for a Linear array. The size of each
547component will be rounded down to a multiple of this size.
548This is a synonym for
549.B \-\-chunk
550but highlights the different meaning for Linear as compared to other
5f175898
N
551RAID levels. The default is 64K if a kernel earlier than 2.6.16 is in
552use, and is 0K (i.e. no rounding) in later kernels.
52826846 553
cd29a5c8 554.TP
7e23fc43 555.BR \-l ", " \-\-level=
e0fe762a 556Set RAID level. When used with
7e23fc43 557.BR \-\-create ,
98c6faba 558options are: linear, raid0, 0, stripe, raid1, 1, mirror, raid4, 4,
8fd8d9c4
N
559raid5, 5, raid6, 6, raid10, 10, multipath, mp, faulty, container.
560Obviously some of these are synonymous.
561
562When a
563.B CONTAINER
564metadata type is requested, only the
565.B container
566level is permitted, and it does not need to be explicitly given.
aa88f531
NB
567
568When used with
7e23fc43 569.BR \-\-build ,
a9d69660 570only linear, stripe, raid0, 0, raid1, multipath, mp, and faulty are valid.
52826846 571
fd547b50
N
572Can be used with
573.B \-\-grow
574to change the RAID level in some cases. See LEVEL CHANGES below.
2ae555c3 575
cd29a5c8 576.TP
7e23fc43 577.BR \-p ", " \-\-layout=
f24e2d6c
N
578This option configures the fine details of data layout for RAID5, RAID6,
579and RAID10 arrays, and controls the failure modes for
1a7dfc35
NB
580.IR faulty .
581
e0fe762a 582The layout of the RAID5 parity block can be one of
7e23fc43
PS
583.BR left\-asymmetric ,
584.BR left\-symmetric ,
585.BR right\-asymmetric ,
586.BR right\-symmetric ,
53e8b987
PS
587.BR la ", " ra ", " ls ", " rs .
588The default is
7e23fc43 589.BR left\-symmetric .
52826846 590
cd19c0cf 591It is also possible to cause RAID5 to use a RAID4-like layout by
e0fe762a
N
592choosing
593.BR parity\-first ,
594or
595.BR parity\-last .
596
597Finally for RAID5 there are DDF\-compatible layouts,
598.BR ddf\-zero\-restart ,
599.BR ddf\-N\-restart ,
600and
601.BR ddf\-N\-continue .
602
603These same layouts are available for RAID6. There are also 4 layouts
604that will provide an intermediate stage for converting between RAID5
605and RAID6. These provide a layout which is identical to the
606corresponding RAID5 layout on the first N\-1 devices, and has the 'Q'
607syndrome (the second 'parity' block used by RAID6) on the last device.
608These layouts are:
609.BR left\-symmetric\-6 ,
610.BR right\-symmetric\-6 ,
611.BR left\-asymmetric\-6 ,
612.BR right\-asymmetric\-6 ,
613and
10adfe9a 614.BR parity\-first\-6 .
e0fe762a 615
93e790af
SW
616When setting the failure mode for level
617.I faulty,
1a7dfc35 618the options are:
7e23fc43
PS
619.BR write\-transient ", " wt ,
620.BR read\-transient ", " rt ,
621.BR write\-persistent ", " wp ,
622.BR read\-persistent ", " rp ,
623.BR write\-all ,
624.BR read\-fixable ", " rf ,
53e8b987 625.BR clear ", " flush ", " none .
b5e64645 626
93e790af 627Each failure mode can be followed by a number, which is used as a period
b5e64645
NB
628between fault generation. Without a number, the fault is generated
629once on the first relevant request. With a number, the fault will be
93e790af 630generated after that many requests, and will continue to be generated
b5e64645
NB
631every time the period elapses.
632
633Multiple failure modes can be current simultaneously by using the
7e23fc43 634.B \-\-grow
53e8b987 635option to set subsequent failure modes.
b5e64645
NB
636
637"clear" or "none" will remove any pending or periodic failure modes,
2ae555c3 638and "flush" will clear any persistent faults.
b5e64645 639
6f9a21a7 640Finally, the layout options for RAID10 are one of 'n', 'o' or 'f' followed
93e790af 641by a small number. The default is 'n2'. The supported options are:
1a7dfc35 642
93e790af 643.I 'n'
e0fe762a 644signals 'near' copies. Multiple copies of one data block are at
b578481c
NB
645similar offsets in different devices.
646
93e790af 647.I 'o'
b578481c
NB
648signals 'offset' copies. Rather than the chunks being duplicated
649within a stripe, whole stripes are duplicated but are rotated by one
650device so duplicate blocks are on different devices. Thus subsequent
651copies of a block are in the next drive, and are one chunk further
652down.
653
93e790af 654.I 'f'
1a7dfc35 655signals 'far' copies
93e790af 656(multiple copies have very different offsets).
e0fe762a 657See md(4) for more detail about 'near', 'offset', and 'far'.
1a7dfc35
NB
658
659The number is the number of copies of each datablock. 2 is normal, 3
660can be useful. This number can be at most equal to the number of
661devices in the array. It does not need to divide evenly into that
662number (e.g. it is perfectly legal to have an 'n2' layout for an array
663with an odd number of devices).
664
f24e2d6c
N
665When an array is converted between RAID5 and RAID6 an intermediate
666RAID6 layout is used in which the second parity block (Q) is always on
667the last device. To convert a RAID5 to RAID6 and leave it in this new
668layout (which does not require re-striping) use
669.BR \-\-layout=preserve .
670This will try to avoid any restriping.
671
672The converse of this is
673.B \-\-layout=normalise
674which will change a non-standard RAID6 layout into a more standard
675arrangement.
676
cd29a5c8 677.TP
7e23fc43 678.BR \-\-parity=
53e8b987 679same as
7e23fc43 680.B \-\-layout
53e8b987 681(thus explaining the p of
7e23fc43 682.BR \-p ).
52826846 683
e793c2e5 684.TP
7e23fc43 685.BR \-b ", " \-\-bitmap=
e793c2e5 686Specify a file to store a write-intent bitmap in. The file should not
53e8b987 687exist unless
7e23fc43 688.B \-\-force
53e8b987 689is also given. The same file should be provided
2ae555c3 690when assembling the array. If the word
93e790af 691.B "internal"
2ae555c3
NB
692is given, then the bitmap is stored with the metadata on the array,
693and so is replicated on all devices. If the word
93e790af 694.B "none"
2ae555c3 695is given with
7e23fc43 696.B \-\-grow
2ae555c3 697mode, then any bitmap that is present is removed.
e793c2e5 698
2ae555c3
NB
699To help catch typing errors, the filename must contain at least one
700slash ('/') if it is a real file (not 'internal' or 'none').
701
702Note: external bitmaps are only known to work on ext2 and ext3.
703Storing bitmap files on other filesystems may result in serious problems.
e793c2e5 704
748952f7
N
705When creating an array on devices which are 100G or larger,
706.I mdadm
707automatically adds an internal bitmap as it will usually be
708beneficial. This can be suppressed with
709.B "\-\-bitmap=none".
710
cd29a5c8 711.TP
7e23fc43 712.BR \-\-bitmap\-chunk=
e0fe762a 713Set the chunksize of the bitmap. Each bit corresponds to that many
1bfdbe01
NB
714Kilobytes of storage.
715When using a file based bitmap, the default is to use the smallest
93e790af 716size that is at-least 4 and requires no more than 2^21 chunks.
2ae555c3
NB
717When using an
718.B internal
b8ab2a50
N
719bitmap, the chunksize defaults to 64Meg, or larger if necessary to
720fit the bitmap into the available space.
5787fa49 721
36fad8ec
N
722A suffix of 'M' or 'G' can be given to indicate Megabytes or
723Gigabytes respectively.
724
cd29a5c8 725.TP
7e23fc43 726.BR \-W ", " \-\-write\-mostly
e0fe762a 727subsequent devices listed in a
7e23fc43
PS
728.BR \-\-build ,
729.BR \-\-create ,
2ae555c3 730or
7e23fc43 731.B \-\-add
2ae555c3
NB
732command will be flagged as 'write-mostly'. This is valid for RAID1
733only and means that the 'md' driver will avoid reading from these
734devices if at all possible. This can be useful if mirroring over a
735slow link.
52826846 736
2ae555c3 737.TP
7e23fc43 738.BR \-\-write\-behind=
2ae555c3 739Specify that write-behind mode should be enabled (valid for RAID1
e0fe762a
N
740only). If an argument is specified, it will set the maximum number
741of outstanding writes allowed. The default value is 256.
2ae555c3
NB
742A write-intent bitmap is required in order to use write-behind
743mode, and write-behind is only attempted on drives marked as
744.IR write-mostly .
dd0781e5
NB
745
746.TP
7e23fc43 747.BR \-\-assume\-clean
dd0781e5
NB
748Tell
749.I mdadm
47d79ef8
NB
750that the array pre-existed and is known to be clean. It can be useful
751when trying to recover from a major failure as you can be sure that no
752data will be affected unless you actually write to the array. It can
753also be used when creating a RAID1 or RAID10 if you want to avoid the
b3f1c093 754initial resync, however this practice \(em while normally safe \(em is not
e0fe762a 755recommended. Use this only if you really know what you are doing.
6acad481
ME
756.IP
757When the devices that will be part of a new array were filled
758with zeros before creation the operator knows the array is
759actually clean. If that is the case, such as after running
760badblocks, this argument can be used to tell mdadm the
761facts the operator knows.
ce52f92f
N
762.IP
763When an array is resized to a larger size with
764.B "\-\-grow \-\-size="
765the new space is normally resynced in that same way that the whole
6cbf8fb8 766array is resynced at creation. From Linux version 3.0,
ce52f92f
N
767.B \-\-assume\-clean
768can be used with that command to avoid the automatic resync.
dd0781e5 769
2ae555c3 770.TP
7e23fc43 771.BR \-\-backup\-file=
53e8b987 772This is needed when
7e23fc43 773.B \-\-grow
cd19c0cf
JR
774is used to increase the number of raid-devices in a RAID5 or RAID6 if
775there are no spare devices available, or to shrink, change RAID level
776or layout. See the GROW MODE section below on RAID\-DEVICES CHANGES.
777The file must be stored on a separate device, not on the RAID array
778being reshaped.
2ae555c3 779
40c9a66a
N
780.TP
781.B \-\-data\-offset=
782Arrays with 1.x metadata can leave a gap between the start of the
783device and the start of array data. This gap can be used for various
784metadata. The start of data is known as the
785.IR data\-offset .
786Normally an appropriate data offset is computed automatically.
787However it can be useful to set it explicitly such as when re-creating
788an array which was originally created using a different version of
789.I mdadm
790which computed a different offset.
791
792Setting the offset explicitly over-rides the default. The value given
793is in Kilobytes unless an 'M' or 'G' suffix is given.
794
795Since Linux 3.4,
796.B \-\-data\-offset
797can also be used with
798.B --grow
799for some RAID levels (initially on RAID10). This allows the
72ca9bcf 800data\-offset to be changed as part of the reshape process. When the
40c9a66a
N
801data offset is changed, no backup file is required as the difference
802in offsets is used to provide the same functionality.
803
804When the new offset is earlier than the old offset, the number of
805devices in the array cannot shrink. When it is after the old offset,
806the number of devices in the array cannot increase.
807
72ca9bcf
N
808When creating an array,
809.B \-\-data\-offset
810can be specified as
811.BR variable .
812In the case each member device is expected to have a offset appended
813to the name, separated by a colon. This makes it possible to recreate
814exactly an array which has varying data offsets (as can happen when
815different versions of
816.I mdadm
817are used to add different devices).
818
f211a137
AK
819.TP
820.BR \-\-continue
821This option is complementary to the
822.B \-\-freeze-reshape
823option for assembly. It is needed when
824.B \-\-grow
825operation is interrupted and it is not restarted automatically due to
826.B \-\-freeze-reshape
827usage during array assembly. This option is used together with
828.BR \-G
829, (
830.BR \-\-grow
831) command and device for a pending reshape to be continued.
832All parameters required for reshape continuation will be read from array metadata.
833If initial
834.BR \-\-grow
835command had required
836.BR \-\-backup\-file=
837option to be set, continuation option will require to have exactly the same
838backup file given as well.
839.IP
840Any other parameter passed together with
841.BR \-\-continue
842option will be ignored.
843
947fd4dd 844.TP
7e23fc43 845.BR \-N ", " \-\-name=
947fd4dd
NB
846Set a
847.B name
848for the array. This is currently only effective when creating an
e0fe762a
N
849array with a version-1 superblock, or an array in a DDF container.
850The name is a simple textual string that can be used to identify array
851components when assembling. If name is needed but not specified, it
852is taken from the basename of the device that is being created.
853e.g. when creating
854.I /dev/md/home
855the
856.B name
857will default to
858.IR home .
947fd4dd 859
dd0781e5 860.TP
7e23fc43 861.BR \-R ", " \-\-run
dd0781e5
NB
862Insist that
863.I mdadm
864run the array, even if some of the components
865appear to be active in another array or filesystem. Normally
866.I mdadm
867will ask for confirmation before including such components in an
868array. This option causes that question to be suppressed.
869
870.TP
7e23fc43 871.BR \-f ", " \-\-force
dd0781e5
NB
872Insist that
873.I mdadm
874accept the geometry and layout specified without question. Normally
875.I mdadm
876will not allow creation of an array with only one device, and will try
e0fe762a 877to create a RAID5 array with one missing drive (as this makes the
dd0781e5 878initial resync work faster). With
7e23fc43 879.BR \-\-force ,
dd0781e5
NB
880.I mdadm
881will not try to be so clever.
882
0ea8f5b1
N
883.TP
884.BR \-o ", " \-\-readonly
885Start the array
886.B read only
887rather than read-write as normal. No writes will be allowed to the
888array, and no resync, recovery, or reshape will be started.
889
dd0781e5 890.TP
257c1dc2
N
891.BR \-a ", " "\-\-auto{=yes,md,mdp,part,p}{NN}"
892Instruct mdadm how to create the device file if needed, possibly allocating
48f7b27a 893an unused minor number. "md" causes a non-partitionable array
257c1dc2
N
894to be used (though since Linux 2.6.28, these array devices are in fact
895partitionable). "mdp", "part" or "p" causes a partitionable array (2.6 and
2ae555c3 896later) to be used. "yes" requires the named md device to have
f9c25f1d 897a 'standard' format, and the type and minor number will be determined
257c1dc2
N
898from this. With mdadm 3.0, device creation is normally left up to
899.I udev
900so this option is unlikely to be needed.
901See DEVICE NAMES below.
48f7b27a 902
a9d69660 903The argument can also come immediately after
7e23fc43 904"\-a". e.g. "\-ap".
dd0781e5 905
53e8b987 906If
7e23fc43 907.B \-\-auto
53e8b987 908is not given on the command line or in the config file, then
75723446 909the default will be
7e23fc43 910.BR \-\-auto=yes .
75723446 911
1337546d 912If
7e23fc43 913.B \-\-scan
1337546d
NB
914is also given, then any
915.I auto=
35cc5be4 916entries in the config file will override the
7e23fc43 917.B \-\-auto
1337546d
NB
918instruction given on the command line.
919
dd0781e5
NB
920For partitionable arrays,
921.I mdadm
922will create the device file for the whole array and for the first 4
923partitions. A different number of partitions can be specified at the
924end of this option (e.g.
7e23fc43 925.BR \-\-auto=p7 ).
2ae555c3 926If the device name ends with a digit, the partition names add a 'p',
e0fe762a
N
927and a number, e.g.
928.IR /dev/md/home1p3 .
929If there is no trailing digit, then the partition names just have a
930number added, e.g.
931.IR /dev/md/scratch3 .
dd0781e5 932
48f7b27a
NB
933If the md device name is in a 'standard' format as described in DEVICE
934NAMES, then it will be created, if necessary, with the appropriate
e0fe762a
N
935device number based on that name. If the device name is not in one of these
936formats, then a unused device number will be allocated. The device
48f7b27a
NB
937number will be considered unused if there is no active array for that
938number, and there is no entry in /dev for that number and with a
e0fe762a 939non-standard name. Names that are not in 'standard' format are only
8fd8d9c4
N
940allowed in "/dev/md/".
941
3c7efacb
NK
942This is meaningful with
943.B \-\-create
944or
945.BR \-\-build .
946
3c7efacb
NK
947.TP
948.BR \-a ", " "\-\-add"
949This option can be used in Grow mode in two cases.
950
951If the target array is a Linear array, then
952.B \-\-add
953can be used to add one or more devices to the array. They
954are simply catenated on to the end of the array. Once added, the
955devices cannot be removed.
956
957If the
958.B \-\-raid\-disks
959option is being used to increase the number of devices in an array,
960then
961.B \-\-add
962can be used to add some extra devices to be included in the array.
963In most cases this is not needed as the extra devices can be added as
964spares first, and then the number of raid-disks can be changed.
965However for RAID0, it is not possible to add spares. So to increase
966the number of devices in a RAID0, it is necessary to set the new
967number of devices, and to add the new devices, in the same command.
968
52826846
NB
969.SH For assemble:
970
cd29a5c8 971.TP
7e23fc43 972.BR \-u ", " \-\-uuid=
e0fe762a 973uuid of array to assemble. Devices which don't have this uuid are
cd29a5c8
NB
974excluded
975
976.TP
7e23fc43 977.BR \-m ", " \-\-super\-minor=
cd29a5c8
NB
978Minor number of device that array was created for. Devices which
979don't have this minor number are excluded. If you create an array as
2d465520 980/dev/md1, then all superblocks will contain the minor number 1, even if
cd29a5c8
NB
981the array is later assembled as /dev/md2.
982
d013a55e 983Giving the literal word "dev" for
7e23fc43 984.B \-\-super\-minor
d013a55e
NB
985will cause
986.I mdadm
987to use the minor number of the md device that is being assembled.
988e.g. when assembling
989.BR /dev/md0 ,
51ac42e3 990.B \-\-super\-minor=dev
d013a55e
NB
991will look for super blocks with a minor number of 0.
992
e0fe762a
N
993.B \-\-super\-minor
994is only relevant for v0.90 metadata, and should not normally be used.
995Using
996.B \-\-uuid
997is much safer.
998
947fd4dd 999.TP
7e23fc43 1000.BR \-N ", " \-\-name=
947fd4dd 1001Specify the name of the array to assemble. This must be the name
624920bb 1002that was specified when creating the array. It must either match
93e790af 1003the name stored in the superblock exactly, or it must match
41a3b72a 1004with the current
624920bb 1005.I homehost
93e790af 1006prefixed to the start of the given name.
947fd4dd 1007
cd29a5c8 1008.TP
7e23fc43 1009.BR \-f ", " \-\-force
e0fe762a
N
1010Assemble the array even if the metadata on some devices appears to be
1011out-of-date. If
1012.I mdadm
1013cannot find enough working devices to start the array, but can find
1014some devices that are recorded as having failed, then it will mark
1015those devices as working so that the array can be started.
1016An array which requires
1017.B \-\-force
1018to be started may contain data corruption. Use it carefully.
52826846 1019
cd29a5c8 1020.TP
7e23fc43 1021.BR \-R ", " \-\-run
b8a8ccf9
NB
1022Attempt to start the array even if fewer drives were given than were
1023present last time the array was active. Normally if not all the
1024expected drives are found and
7e23fc43 1025.B \-\-scan
cd29a5c8
NB
1026is not used, then the array will be assembled but not started.
1027With
7e23fc43 1028.B \-\-run
cd29a5c8 1029an attempt will be made to start it anyway.
52826846 1030
b8a8ccf9 1031.TP
7e23fc43 1032.B \-\-no\-degraded
b8a8ccf9 1033This is the reverse of
7e23fc43 1034.B \-\-run
93e790af 1035in that it inhibits the startup of array unless all expected drives
b8a8ccf9 1036are present. This is only needed with
93e790af
SW
1037.B \-\-scan,
1038and can be used if the physical connections to devices are
b8a8ccf9
NB
1039not as reliable as you would like.
1040
dd0781e5 1041.TP
7e23fc43 1042.BR \-a ", " "\-\-auto{=no,yes,md,mdp,part}"
dd0781e5
NB
1043See this option under Create and Build options.
1044
e793c2e5 1045.TP
7e23fc43 1046.BR \-b ", " \-\-bitmap=
2ae555c3
NB
1047Specify the bitmap file that was given when the array was created. If
1048an array has an
1049.B internal
1050bitmap, there is no need to specify this when assembling the array.
1051
1052.TP
7e23fc43 1053.BR \-\-backup\-file=
2ae555c3 1054If
7e23fc43 1055.B \-\-backup\-file
87f26d14
N
1056was used while reshaping an array (e.g. changing number of devices or
1057chunk size) and the system crashed during the critical section, then the same
7e23fc43 1058.B \-\-backup\-file
53e8b987 1059must be presented to
7e23fc43 1060.B \-\-assemble
cd19c0cf
JR
1061to allow possibly corrupted data to be restored, and the reshape
1062to be completed.
e793c2e5 1063
87f26d14
N
1064.TP
1065.BR \-\-invalid\-backup
1066If the file needed for the above option is not available for any
1067reason an empty file can be given together with this option to
1068indicate that the backup file is invalid. In this case the data that
1069was being rearranged at the time of the crash could be irrecoverably
1070lost, but the rest of the array may still be recoverable. This option
1071should only be used as a last resort if there is no way to recover the
1072backup file.
1073
1074
5787fa49 1075.TP
7e23fc43 1076.BR \-U ", " \-\-update=
5787fa49 1077Update the superblock on each device while assembling the array. The
feb716e9
NB
1078argument given to this flag can be one of
1079.BR sparc2.2 ,
1080.BR summaries ,
7d99579f 1081.BR uuid ,
c4f12c13 1082.BR name ,
0237e0ca 1083.BR homehost ,
e5329c37 1084.BR resync ,
586ed405 1085.BR byteorder ,
bee8ec56 1086.BR devicesize ,
5a31170d 1087.BR no\-bitmap ,
688e99a7
N
1088.BR bbl ,
1089.BR no-\bbl ,
afa368f4 1090.BR metadata ,
5787fa49 1091or
7e23fc43 1092.BR super\-minor .
5787fa49
NB
1093
1094The
1095.B sparc2.2
7d99579f 1096option will adjust the superblock of an array what was created on a Sparc
5787fa49
NB
1097machine running a patched 2.2 Linux kernel. This kernel got the
1098alignment of part of the superblock wrong. You can use the
7e23fc43 1099.B "\-\-examine \-\-sparc2.2"
5787fa49
NB
1100option to
1101.I mdadm
1102to see what effect this would have.
1103
1104The
7e23fc43 1105.B super\-minor
5787fa49 1106option will update the
2ae555c3 1107.B "preferred minor"
5787fa49 1108field on each superblock to match the minor number of the array being
45c073c9
NB
1109assembled.
1110This can be useful if
7e23fc43 1111.B \-\-examine
45c073c9 1112reports a different "Preferred Minor" to
7e23fc43 1113.BR \-\-detail .
45c073c9 1114In some cases this update will be performed automatically
e0fe762a 1115by the kernel driver. In particular the update happens automatically
45c073c9
NB
1116at the first write to an array with redundancy (RAID level 1 or
1117greater) on a 2.6 (or later) kernel.
5787fa49 1118
7d99579f
NB
1119The
1120.B uuid
1121option will change the uuid of the array. If a UUID is given with the
7e23fc43 1122.B \-\-uuid
53e8b987 1123option that UUID will be used as a new UUID and will
7d99579f
NB
1124.B NOT
1125be used to help identify the devices in the array.
53e8b987 1126If no
7e23fc43 1127.B \-\-uuid
53e8b987 1128is given, a random UUID is chosen.
7d99579f 1129
c4f12c13
NB
1130The
1131.B name
1132option will change the
1133.I name
1134of the array as stored in the superblock. This is only supported for
1135version-1 superblocks.
1136
0237e0ca
NB
1137The
1138.B homehost
1139option will change the
1140.I homehost
1141as recorded in the superblock. For version-0 superblocks, this is the
1142same as updating the UUID.
1143For version-1 superblocks, this involves updating the name.
1144
e5329c37
NB
1145The
1146.B resync
1147option will cause the array to be marked
1148.I dirty
e0fe762a
N
1149meaning that any redundancy in the array (e.g. parity for RAID5,
1150copies for RAID1) may be incorrect. This will cause the RAID system
e5329c37
NB
1151to perform a "resync" pass to make sure that all redundant information
1152is correct.
1153
586ed405
NB
1154The
1155.B byteorder
1156option allows arrays to be moved between machines with different
1157byte-order.
2ae555c3 1158When assembling such an array for the first time after a move, giving
7e23fc43 1159.B "\-\-update=byteorder"
586ed405
NB
1160will cause
1161.I mdadm
1162to expect superblocks to have their byteorder reversed, and will
1163correct that order before assembling the array. This is only valid
2ae555c3 1164with original (Version 0.90) superblocks.
586ed405 1165
feb716e9
NB
1166The
1167.B summaries
e0fe762a 1168option will correct the summaries in the superblock. That is the
feb716e9 1169counts of total, working, active, failed, and spare devices.
5787fa49 1170
bee8ec56
NB
1171The
1172.B devicesize
5a31170d 1173option will rarely be of use. It applies to version 1.1 and 1.2 metadata
bee8ec56
NB
1174only (where the metadata is at the start of the device) and is only
1175useful when the component device has changed size (typically become
1176larger). The version 1 metadata records the amount of the device that
1177can be used to store data, so if a device in a version 1.1 or 1.2
1178array becomes larger, the metadata will still be visible, but the
1179extra space will not. In this case it might be useful to assemble the
1180array with
7e23fc43 1181.BR \-\-update=devicesize .
bee8ec56
NB
1182This will cause
1183.I mdadm
1184to determine the maximum usable amount of space on each device and
1185update the relevant field in the metadata.
1186
afa368f4
N
1187The
1188.B metadata
1189option only works on v0.90 metadata arrays and will convert them to
1190v1.0 metadata. The array must not be dirty (i.e. it must not need a
1191sync) and it must not have a write-intent bitmap.
1192
1193The old metadata will remain on the devices, but will appear older
1194than the new metadata and so will usually be ignored. The old metadata
1195(or indeed the new metadata) can be removed by giving the appropriate
1196.B \-\-metadata=
1197option to
1198.BR \-\-zero\-superblock .
1199
5a31170d
N
1200The
1201.B no\-bitmap
1202option can be used when an array has an internal bitmap which is
1203corrupt in some way so that assembling the array normally fails. It
1204will cause any internal bitmap to be ignored.
1205
688e99a7
N
1206The
1207.B bbl
1208option will reserve space in each device for a bad block list. This
1209will be 4K in size and positioned near the end of any free space
1210between the superblock and the data.
1211
1212The
1213.B no\-bbl
1214option will cause any reservation of space for a bad block list to be
1215removed. If the bad block list contains entries, this will fail, as
1216removing the list could cause data corruption.
1217
afd0a969
AK
1218.TP
1219.BR \-\-freeze\-reshape
1220Option is intended to be used in start-up scripts during initrd boot phase.
1221When array under reshape is assembled during initrd phase, this option
1222stops reshape after reshape critical section is being restored. This happens
1223before file system pivot operation and avoids loss of file system context.
1224Losing file system context would cause reshape to be broken.
1225
a6482415
N
1226Reshape can be continued later using the
1227.B \-\-continue
1228option for the grow command.
afd0a969 1229
e0d19036 1230.SH For Manage mode:
52826846 1231
3d5279b0
N
1232.TP
1233.BR \-t ", " \-\-test
1234Unless a more serious error occurred,
1235.I mdadm
1236will exit with a status of 2 if no changes were made to the array and
12370 if at least one change was made.
1238This can be useful when an indirect specifier such as
1239.BR missing ,
1240.B detached
1241or
1242.B faulty
1243is used in requesting an operation on the array.
1244.B \-\-test
1245will report failure if these specifiers didn't find any match.
1246
cd29a5c8 1247.TP
7e23fc43 1248.BR \-a ", " \-\-add
3d5279b0
N
1249hot-add listed devices.
1250If a device appears to have recently been part of the array
342460cb 1251(possibly it failed or was removed) the device is re\-added as described
3d5279b0
N
1252in the next point.
1253If that fails or the device was never part of the array, the device is
1254added as a hot-spare.
1255If the array is degraded, it will immediately start to rebuild data
1256onto that spare.
1257
1258Note that this and the following options are only meaningful on array
1259with redundancy. They don't apply to RAID0 or Linear.
52826846 1260
fe80f49b 1261.TP
7e23fc43 1262.BR \-\-re\-add
eae6b036 1263re\-add a device that was previously removed from an array.
3d5279b0
N
1264If the metadata on the device reports that it is a member of the
1265array, and the slot that it used is still vacant, then the device will
1266be added back to the array in the same position. This will normally
1267cause the data for that device to be recovered. However based on the
1268event count on the device, the recovery may only require sections that
1269are flagged a write-intent bitmap to be recovered or may not require
1270any recovery at all.
1271
1272When used on an array that has no metadata (i.e. it was built with
1273.BR \-\-build)
1274it will be assumed that bitmap-based recovery is enough to make the
1275device fully consistent with the array.
fe80f49b 1276
688e99a7 1277When used with v1.x metadata,
833bb0f8
N
1278.B \-\-re\-add
1279can be accompanied by
688e99a7
N
1280.BR \-\-update=devicesize ,
1281.BR \-\-update=bbl ", or"
1282.BR \-\-update=no\-bbl .
1283See the description of these option when used in Assemble mode for an
1284explanation of their use.
833bb0f8 1285
a4e13010
N
1286If the device name given is
1287.B missing
262e3b7f
N
1288then
1289.I mdadm
1290will try to find any device that looks like it should be
a4e13010
N
1291part of the array but isn't and will try to re\-add all such devices.
1292
262e3b7f
N
1293If the device name given is
1294.B faulty
1295then
1296.I mdadm
1297will find all devices in the array that are marked
1298.BR faulty ,
1299remove them and attempt to immediately re\-add them. This can be
1300useful if you are certain that the reason for failure has been
1301resolved.
1302
f33a71f1
N
1303.TP
1304.B \-\-add\-spare
1305Add a device as a spare. This is similar to
1306.B \-\-add
1307except that it does not attempt
1308.B \-\-re\-add
1309first. The device will be added as a spare even if it looks like it
1310could be an recent member of the array.
1311
cd29a5c8 1312.TP
7e23fc43 1313.BR \-r ", " \-\-remove
2d465520 1314remove listed devices. They must not be active. i.e. they should
64a78416
N
1315be failed or spare devices.
1316
1317As well as the name of a device file
b80da661
NB
1318(e.g.
1319.BR /dev/sda1 )
1320the words
64a78416 1321.BR failed ,
b80da661 1322.B detached
64a78416
N
1323and names like
1324.B set-A
b80da661
NB
1325can be given to
1326.BR \-\-remove .
1327The first causes all failed device to be removed. The second causes
93e790af 1328any device which is no longer connected to the system (i.e an 'open'
b80da661
NB
1329returns
1330.BR ENXIO )
64a78416
N
1331to be removed.
1332The third will remove a set as describe below under
1333.BR \-\-fail .
52826846 1334
cd29a5c8 1335.TP
7e23fc43 1336.BR \-f ", " \-\-fail
70c55e36 1337Mark listed devices as faulty.
b80da661
NB
1338As well as the name of a device file, the word
1339.B detached
64a78416
N
1340or a set name like
1341.B set\-A
1342can be given. The former will cause any device that has been detached from
b80da661 1343the system to be marked as failed. It can then be removed.
52826846 1344
64a78416
N
1345For RAID10 arrays where the number of copies evenly divides the number
1346of devices, the devices can be conceptually divided into sets where
1347each set contains a single complete copy of the data on the array.
1348Sometimes a RAID10 array will be configured so that these sets are on
1349separate controllers. In this case all the devices in one set can be
1350failed by giving a name like
1351.B set\-A
1352or
1353.B set\-B
1354to
1355.BR \-\-fail .
1356The appropriate set names are reported by
1357.BR \-\-detail .
1358
cd29a5c8 1359.TP
7e23fc43 1360.BR \-\-set\-faulty
53e8b987 1361same as
7e23fc43 1362.BR \-\-fail .
52826846 1363
70c55e36
N
1364.TP
1365.B \-\-replace
1366Mark listed devices as requiring replacement. As soon as a spare is
1367available, it will be rebuilt and will replace the marked device.
1368This is similar to marking a device as faulty, but the device remains
1369in service during the recovery process to increase resilience against
1370multiple failures. When the replacement process finishes, the
1371replaced device will be marked as faulty.
1372
1373.TP
1374.B \-\-with
1375This can follow a list of
1376.B \-\-replace
1377devices. The devices listed after
1378.B \-\-with
1379will be preferentially used to replace the devices listed after
1380.BR \-\-replace .
1381These device must already be spare devices in the array.
1382
b3d31955
N
1383.TP
1384.BR \-\-write\-mostly
a4e13010 1385Subsequent devices that are added or re\-added will have the 'write-mostly'
e0fe762a 1386flag set. This is only valid for RAID1 and means that the 'md' driver
b3d31955
N
1387will avoid reading from these devices if possible.
1388.TP
1389.BR \-\-readwrite
a4e13010 1390Subsequent devices that are added or re\-added will have the 'write-mostly'
b3d31955
N
1391flag cleared.
1392
2ae555c3 1393.P
e0fe762a 1394Each of these options requires that the first device listed is the array
93e790af 1395to be acted upon, and the remainder are component devices to be added,
e0fe762a 1396removed, marked as faulty, etc. Several different operations can be
2ae555c3
NB
1397specified for different devices, e.g.
1398.in +5
7e23fc43 1399mdadm /dev/md0 \-\-add /dev/sda1 \-\-fail /dev/sdb1 \-\-remove /dev/sdb1
2ae555c3
NB
1400.in -5
1401Each operation applies to all devices listed until the next
93e790af 1402operation.
2ae555c3
NB
1403
1404If an array is using a write-intent bitmap, then devices which have
a4e13010 1405been removed can be re\-added in a way that avoids a full
93e790af 1406reconstruction but instead just updates the blocks that have changed
2ae555c3
NB
1407since the device was removed. For arrays with persistent metadata
1408(superblocks) this is done automatically. For arrays created with
7e23fc43 1409.B \-\-build
2ae555c3 1410mdadm needs to be told that this device we removed recently with
7e23fc43 1411.BR \-\-re\-add .
2ae555c3
NB
1412
1413Devices can only be removed from an array if they are not in active
93e790af
SW
1414use, i.e. that must be spares or failed devices. To remove an active
1415device, it must first be marked as
1416.B faulty.
2ae555c3
NB
1417
1418.SH For Misc mode:
1419
1420.TP
7e23fc43 1421.BR \-Q ", " \-\-query
2ae555c3
NB
1422Examine a device to see
1423(1) if it is an md device and (2) if it is a component of an md
1424array.
1425Information about what is discovered is presented.
1426
1427.TP
7e23fc43 1428.BR \-D ", " \-\-detail
e0fe762a 1429Print details of one or more md devices.
5787fa49 1430
4cce4069
DW
1431.TP
1432.BR \-\-detail\-platform
e0fe762a 1433Print details of the platform's RAID capabilities (firmware / hardware
9eafa1de
MN
1434topology) for a given metadata format. If used without argument, mdadm
1435will scan all controllers looking for their capabilities. Otherwise, mdadm
1436will only look at the controller specified by the argument in form of an
1437absolute filepath or a link, e.g.
1438.IR /sys/devices/pci0000:00/0000:00:1f.2 .
4cce4069 1439
54bad364
KS
1440.TP
1441.BR \-Y ", " \-\-export
1442When used with
e50cf220 1443.B \-\-detail , \-\-detail-platform
0d726f17
KS
1444or
1445.BR \-\-examine ,
54bad364
KS
1446output will be formatted as
1447.B key=value
1448pairs for easy import into the environment.
1449
2ae555c3 1450.TP
7e23fc43 1451.BR \-E ", " \-\-examine
e0fe762a
N
1452Print contents of the metadata stored on the named device(s).
1453Note the contrast between
1454.B \-\-examine
1455and
1456.BR \-\-detail .
1457.B \-\-examine
1458applies to devices which are components of an array, while
1459.B \-\-detail
1460applies to a whole array which is currently active.
5787fa49 1461.TP
7e23fc43 1462.B \-\-sparc2.2
e0fe762a
N
1463If an array was created on a SPARC machine with a 2.2 Linux kernel
1464patched with RAID support, the superblock will have been created
1465incorrectly, or at least incompatibly with 2.4 and later kernels.
1466Using the
7e23fc43 1467.B \-\-sparc2.2
5787fa49 1468flag with
7e23fc43 1469.B \-\-examine
5787fa49
NB
1470will fix the superblock before displaying it. If this appears to do
1471the right thing, then the array can be successfully assembled using
7e23fc43 1472.BR "\-\-assemble \-\-update=sparc2.2" .
5787fa49 1473
2ae555c3 1474.TP
7e23fc43 1475.BR \-X ", " \-\-examine\-bitmap
2ae555c3 1476Report information about a bitmap file.
01d9299c 1477The argument is either an external bitmap file or an array component
e0fe762a
N
1478in case of an internal bitmap. Note that running this on an array
1479device (e.g.
1480.BR /dev/md0 )
1481does not report the bitmap for that array.
e0d19036 1482
6d388a88
N
1483.TP
1484.B \-\-examine\-badblocks
1485List the bad-blocks recorded for the device, if a bad-blocks list has
1486been configured. Currently only
1487.B 1.x
1488metadata supports bad-blocks lists.
1489
74db60b0
N
1490.TP
1491.BI \-\-dump= directory
1492.TP
1493.BI \-\-restore= directory
1494Save metadata from lists devices, or restore metadata to listed devices.
1495
cd29a5c8 1496.TP
7e23fc43 1497.BR \-R ", " \-\-run
e0fe762a
N
1498start a partially assembled array. If
1499.B \-\-assemble
1500did not find enough devices to fully start the array, it might leaving
1501it partially assembled. If you wish, you can then use
1502.B \-\-run
1503to start the array in degraded mode.
52826846 1504
cd29a5c8 1505.TP
7e23fc43 1506.BR \-S ", " \-\-stop
cd29a5c8 1507deactivate array, releasing all resources.
52826846 1508
cd29a5c8 1509.TP
7e23fc43 1510.BR \-o ", " \-\-readonly
cd29a5c8 1511mark array as readonly.
52826846 1512
cd29a5c8 1513.TP
7e23fc43 1514.BR \-w ", " \-\-readwrite
cd29a5c8 1515mark array as readwrite.
52826846 1516
e0d19036 1517.TP
7e23fc43 1518.B \-\-zero\-superblock
e0d19036 1519If the device contains a valid md superblock, the block is
35cc5be4 1520overwritten with zeros. With
7e23fc43 1521.B \-\-force
35cc5be4 1522the block where the superblock would be is overwritten even if it
e0d19036 1523doesn't appear to be valid.
52826846 1524
33414a01
DW
1525.TP
1526.B \-\-kill\-subarray=
1527If the device is a container and the argument to \-\-kill\-subarray
1528specifies an inactive subarray in the container, then the subarray is
1529deleted. Deleting all subarrays will leave an 'empty-container' or
afa368f4
N
1530spare superblock on the drives. See
1531.B \-\-zero\-superblock
1532for completely
33414a01
DW
1533removing a superblock. Note that some formats depend on the subarray
1534index for generating a UUID, this command will fail if it would change
1535the UUID of an active subarray.
1536
aa534678
DW
1537.TP
1538.B \-\-update\-subarray=
1539If the device is a container and the argument to \-\-update\-subarray
1540specifies a subarray in the container, then attempt to update the given
1541superblock field in the subarray. See below in
1542.B MISC MODE
1543for details.
1544
feb716e9 1545.TP
7e23fc43 1546.BR \-t ", " \-\-test
feb716e9 1547When used with
7e23fc43 1548.BR \-\-detail ,
feb716e9
NB
1549the exit status of
1550.I mdadm
e0fe762a
N
1551is set to reflect the status of the device. See below in
1552.B MISC MODE
1553for details.
feb716e9 1554
b90c0e9a 1555.TP
7e23fc43 1556.BR \-W ", " \-\-wait
b90c0e9a
NB
1557For each md device given, wait for any resync, recovery, or reshape
1558activity to finish before returning.
1559.I mdadm
1560will return with success if it actually waited for every device
1561listed, otherwise it will return failure.
1562
1770662b
DW
1563.TP
1564.BR \-\-wait\-clean
fabbfd48
DW
1565For each md device given, or each device in /proc/mdstat if
1566.B \-\-scan
1567is given, arrange for the array to be marked clean as soon as possible.
7146ec6a
DW
1568.I mdadm
1569will return with success if the array uses external metadata and we
1570successfully waited. For native arrays this returns immediately as the
6a0ee6a0
DW
1571kernel handles dirty-clean transitions at shutdown. No action is taken
1572if safe-mode handling is disabled.
1770662b 1573
8382f19b
NB
1574.SH For Incremental Assembly mode:
1575.TP
7e23fc43 1576.BR \-\-rebuild\-map ", " \-r
8382f19b 1577Rebuild the map file
96fd06ed 1578.RB ( {MAP_PATH} )
8382f19b
NB
1579that
1580.I mdadm
1581uses to help track which arrays are currently being assembled.
1582
1583.TP
7e23fc43 1584.BR \-\-run ", " \-R
8382f19b
NB
1585Run any array assembled as soon as a minimal number of devices are
1586available, rather than waiting until all expected devices are present.
1587
1588.TP
7e23fc43 1589.BR \-\-scan ", " \-s
8382f19b 1590Only meaningful with
7e23fc43 1591.B \-R
8382f19b
NB
1592this will scan the
1593.B map
1594file for arrays that are being incrementally assembled and will try to
1595start any that are not already started. If any such array is listed
1596in
1597.B mdadm.conf
1598as requiring an external bitmap, that bitmap will be attached first.
1599
29ba4804
N
1600.TP
1601.BR \-\-fail ", " \-f
1602This allows the hot-plug system to remove devices that have fully disappeared
1603from the kernel. It will first fail and then remove the device from any
1604array it belongs to.
1605The device name given should be a kernel device name such as "sda",
1606not a name in
1607.IR /dev .
1608
210597d1
PC
1609.TP
1610.BR \-\-path=
87eb4fab
N
1611Only used with \-\-fail. The 'path' given will be recorded so that if
1612a new device appears at the same location it can be automatically
1613added to the same array. This allows the failed device to be
1614automatically replaced by a new device without metadata if it appears
1615at specified path. This option is normally only set by a
1616.I udev
1617script.
210597d1 1618
e0d19036
NB
1619.SH For Monitor mode:
1620.TP
7e23fc43 1621.BR \-m ", " \-\-mail
e0d19036
NB
1622Give a mail address to send alerts to.
1623
1624.TP
7e23fc43 1625.BR \-p ", " \-\-program ", " \-\-alert
e0d19036
NB
1626Give a program to be run whenever an event is detected.
1627
773135f5 1628.TP
7e23fc43 1629.BR \-y ", " \-\-syslog
773135f5
NB
1630Cause all events to be reported through 'syslog'. The messages have
1631facility of 'daemon' and varying priorities.
1632
e0d19036 1633.TP
7e23fc43 1634.BR \-d ", " \-\-delay
e0d19036 1635Give a delay in seconds.
51ac42e3 1636.I mdadm
e0d19036 1637polls the md arrays and then waits this many seconds before polling
e0fe762a
N
1638again. The default is 60 seconds. Since 2.6.16, there is no need to
1639reduce this as the kernel alerts
1640.I mdadm
1641immediately when there is any change.
e0d19036 1642
9a36a9b7
ZB
1643.TP
1644.BR \-r ", " \-\-increment
1645Give a percentage increment.
1646.I mdadm
1647will generate RebuildNN events with the given percentage increment.
1648
d013a55e 1649.TP
7e23fc43 1650.BR \-f ", " \-\-daemonise
d013a55e 1651Tell
51ac42e3 1652.I mdadm
d013a55e 1653to run as a background daemon if it decides to monitor anything. This
e0fe762a 1654causes it to fork and run in the child, and to disconnect from the
d013a55e
NB
1655terminal. The process id of the child is written to stdout.
1656This is useful with
7e23fc43 1657.B \-\-scan
d013a55e
NB
1658which will only continue monitoring if a mail address or alert program
1659is found in the config file.
1660
b5e64645 1661.TP
7e23fc43 1662.BR \-i ", " \-\-pid\-file
b5e64645 1663When
51ac42e3 1664.I mdadm
b5e64645
NB
1665is running in daemon mode, write the pid of the daemon process to
1666the specified file, instead of printing it on standard output.
1667
aa88f531 1668.TP
7e23fc43 1669.BR \-1 ", " \-\-oneshot
aa88f531
NB
1670Check arrays only once. This will generate
1671.B NewArray
1672events and more significantly
1673.B DegradedArray
a9d69660
NB
1674and
1675.B SparesMissing
aa88f531
NB
1676events. Running
1677.in +5
7e23fc43 1678.B " mdadm \-\-monitor \-\-scan \-1"
aa88f531
NB
1679.in -5
1680from a cron script will ensure regular notification of any degraded arrays.
1681
98c6faba 1682.TP
7e23fc43 1683.BR \-t ", " \-\-test
98c6faba
NB
1684Generate a
1685.B TestMessage
1686alert for every array found at startup. This alert gets mailed and
1687passed to the alert program. This can be used for testing that alert
a9d69660 1688message do get through successfully.
98c6faba 1689
210597d1
PC
1690.TP
1691.BR \-\-no\-sharing
87eb4fab 1692This inhibits the functionality for moving spares between arrays.
210597d1
PC
1693Only one monitoring process started with
1694.B \-\-scan
87eb4fab
N
1695but without this flag is allowed, otherwise the two could interfere
1696with each other.
210597d1 1697
e0d19036 1698.SH ASSEMBLE MODE
52826846 1699
cd29a5c8
NB
1700.HP 12
1701Usage:
7e23fc43 1702.B mdadm \-\-assemble
5787fa49
NB
1703.I md-device options-and-component-devices...
1704.HP 12
1705Usage:
7e23fc43 1706.B mdadm \-\-assemble \-\-scan
e0fe762a 1707.I md-devices-and-options...
cd29a5c8
NB
1708.HP 12
1709Usage:
7e23fc43 1710.B mdadm \-\-assemble \-\-scan
e0fe762a 1711.I options...
52826846 1712
cd29a5c8 1713.PP
e0fe762a 1714This usage assembles one or more RAID arrays from pre-existing components.
9a9dab36 1715For each array, mdadm needs to know the md device, the identity of the
e0fe762a 1716array, and a number of component-devices. These can be found in a number of ways.
52826846 1717
5787fa49 1718In the first usage example (without the
7e23fc43 1719.BR \-\-scan )
5787fa49
NB
1720the first device given is the md device.
1721In the second usage example, all devices listed are treated as md
1722devices and assembly is attempted.
1723In the third (where no devices are listed) all md devices that are
cb77f620 1724listed in the configuration file are assembled. If no arrays are
e0fe762a
N
1725described by the configuration file, then any arrays that
1726can be found on unused devices will be assembled.
52826846 1727
d013a55e 1728If precisely one device is listed, but
7e23fc43 1729.B \-\-scan
dd0781e5 1730is not given, then
d013a55e
NB
1731.I mdadm
1732acts as though
7e23fc43 1733.B \-\-scan
93e790af 1734was given and identity information is extracted from the configuration file.
d013a55e 1735
2ae555c3 1736The identity can be given with the
7e23fc43 1737.B \-\-uuid
e0fe762a
N
1738option, the
1739.B \-\-name
1740option, or the
7e23fc43 1741.B \-\-super\-minor
93e790af
SW
1742option, will be taken from the md-device record in the config file, or
1743will be taken from the super block of the first component-device
1744listed on the command line.
52826846 1745
2ae555c3 1746Devices can be given on the
7e23fc43 1747.B \-\-assemble
e0fe762a 1748command line or in the config file. Only devices which have an md
5787fa49
NB
1749superblock which contains the right identity will be considered for
1750any array.
52826846 1751
2ae555c3 1752The config file is only used if explicitly named with
7e23fc43 1753.B \-\-config
d013a55e 1754or requested with (a possibly implicit)
7e23fc43 1755.BR \-\-scan .
52826846 1756In the later case,
9a9dab36 1757.B /etc/mdadm.conf
8fd8d9c4
N
1758or
1759.B /etc/mdadm/mdadm.conf
52826846
NB
1760is used.
1761
2ae555c3 1762If
7e23fc43 1763.B \-\-scan
cd29a5c8
NB
1764is not given, then the config file will only be used to find the
1765identity of md arrays.
52826846 1766
2d465520 1767Normally the array will be started after it is assembled. However if
7e23fc43 1768.B \-\-scan
e0fe762a
N
1769is not given and not all expected drives were listed, then the array
1770is not started (to guard against usage errors). To insist that the
1771array be started in this case (as may work for RAID1, 4, 5, 6, or 10),
1772give the
7e23fc43 1773.B \-\-run
cd29a5c8 1774flag.
52826846 1775
e0fe762a
N
1776If
1777.I udev
1778is active,
1779.I mdadm
1780does not create any entries in
dd0781e5 1781.B /dev
e0fe762a
N
1782but leaves that to
1783.IR udev .
1784It does record information in
96fd06ed 1785.B {MAP_PATH}
e0fe762a
N
1786which will allow
1787.I udev
1788to choose the correct name.
dd0781e5 1789
e0fe762a
N
1790If
1791.I mdadm
1792detects that udev is not configured, it will create the devices in
1793.B /dev
1794itself.
dd0781e5 1795
e0fe762a
N
1796In Linux kernels prior to version 2.6.28 there were two distinctly
1797different types of md devices that could be created: one that could be
1798partitioned using standard partitioning tools and one that could not.
1799Since 2.6.28 that distinction is no longer relevant as both type of
1800devices can be partitioned.
1801.I mdadm
1802will normally create the type that originally could not be partitioned
1803as it has a well defined major number (9).
dd0781e5 1804
e0fe762a
N
1805Prior to 2.6.28, it is important that mdadm chooses the correct type
1806of array device to use. This can be controlled with the
1807.B \-\-auto
1808option. In particular, a value of "mdp" or "part" or "p" tells mdadm
1809to use a partitionable device rather than the default.
dd0781e5 1810
e0fe762a
N
1811In the no-udev case, the value given to
1812.B \-\-auto
1813can be suffixed by a number. This tells
1814.I mdadm
1815to create that number of partition devices rather than the default of 4.
dd0781e5 1816
e0fe762a 1817The value given to
7e23fc43 1818.B \-\-auto
e0fe762a
N
1819can also be given in the configuration file as a word starting
1820.B auto=
1821on the ARRAY line for the relevant array.
52826846 1822
41a3b72a
NB
1823.SS Auto Assembly
1824When
7e23fc43 1825.B \-\-assemble
41a3b72a 1826is used with
7e23fc43 1827.B \-\-scan
41a3b72a
NB
1828and no devices are listed,
1829.I mdadm
1830will first attempt to assemble all the arrays listed in the config
1831file.
1832
cb77f620 1833If no arrays are listed in the config (other than those marked
e0fe762a
N
1834.BR <ignore> )
1835it will look through the available devices for possible arrays and
1836will try to assemble anything that it finds. Arrays which are tagged
1837as belonging to the given homehost will be assembled and started
1838normally. Arrays which do not obviously belong to this host are given
1839names that are expected not to conflict with anything local, and are
1840started "read-auto" so that nothing is written to any device until the
1841array is written to. i.e. automatic resync etc is delayed.
41a3b72a
NB
1842
1843If
1844.I mdadm
1845finds a consistent set of devices that look like they should comprise
1846an array, and if the superblock is tagged as belonging to the given
1847home host, it will automatically choose a device name and try to
1848assemble the array. If the array uses version-0.90 metadata, then the
1849.B minor
1850number as recorded in the superblock is used to create a name in
1851.B /dev/md/
1852so for example
1853.BR /dev/md/3 .
1854If the array uses version-1 metadata, then the
1855.B name
1856from the superblock is used to similarly create a name in
e0fe762a 1857.B /dev/md/
93e790af 1858(the name will have any 'host' prefix stripped first).
41a3b72a 1859
c64ba03a
N
1860This behaviour can be modified by the
1861.I AUTO
1862line in the
1863.I mdadm.conf
1864configuration file. This line can indicate that specific metadata
1865type should, or should not, be automatically assembled. If an array
1866is found which is not listed in
1867.I mdadm.conf
1868and has a metadata format that is denied by the
1869.I AUTO
1870line, then it will not be assembled.
1871The
1872.I AUTO
1873line can also request that all arrays identified as being for this
1874homehost should be assembled regardless of their metadata type.
1875See
1876.IR mdadm.conf (5)
1877for further details.
1878
246cebdb
AK
1879Note: Auto assembly cannot be used for assembling and activating some
1880arrays which are undergoing reshape. In particular as the
1881.B backup\-file
1882cannot be given, any reshape which requires a backup-file to continue
1883cannot be started by auto assembly. An array which is growing to more
1884devices and has passed the critical section can be assembled using
1885auto-assembly.
41a3b72a 1886
cd29a5c8 1887.SH BUILD MODE
52826846 1888
cd29a5c8
NB
1889.HP 12
1890Usage:
7e23fc43 1891.B mdadm \-\-build
93e790af 1892.I md-device
7e23fc43
PS
1893.BI \-\-chunk= X
1894.BI \-\-level= Y
1895.BI \-\-raid\-devices= Z
cd29a5c8
NB
1896.I devices
1897
1898.PP
2ae555c3 1899This usage is similar to
7e23fc43 1900.BR \-\-create .
e0fe762a 1901The difference is that it creates an array without a superblock. With
cd29a5c8 1902these arrays there is no difference between initially creating the array and
52826846
NB
1903subsequently assembling the array, except that hopefully there is useful
1904data there in the second case.
1905
e0fe762a
N
1906The level may raid0, linear, raid1, raid10, multipath, or faulty, or
1907one of their synonyms. All devices must be listed and the array will
1908be started once complete. It will often be appropriate to use
1909.B \-\-assume\-clean
1910with levels raid1 or raid10.
cd29a5c8
NB
1911
1912.SH CREATE MODE
1913
1914.HP 12
1915Usage:
7e23fc43 1916.B mdadm \-\-create
93e790af 1917.I md-device
7e23fc43
PS
1918.BI \-\-chunk= X
1919.BI \-\-level= Y
cd29a5c8 1920.br
7e23fc43 1921.BI \-\-raid\-devices= Z
e0fe762a 1922.I devices
cd29a5c8
NB
1923
1924.PP
1925This usage will initialise a new md array, associate some devices with
1926it, and activate the array.
1927
e0fe762a
N
1928The named device will normally not exist when
1929.I "mdadm \-\-create"
1930is run, but will be created by
1931.I udev
1932once the array becomes active.
dd0781e5 1933
e0fe762a
N
1934As devices are added, they are checked to see if they contain RAID
1935superblocks or filesystems. They are also checked to see if the variance in
cd29a5c8
NB
1936device size exceeds 1%.
1937
1938If any discrepancy is found, the array will not automatically be run, though
2ae555c3 1939the presence of a
7e23fc43 1940.B \-\-run
cd29a5c8
NB
1941can override this caution.
1942
2d465520 1943To create a "degraded" array in which some devices are missing, simply
d013a55e 1944give the word "\fBmissing\fP"
2d465520 1945in place of a device name. This will cause
51ac42e3 1946.I mdadm
2d465520
NB
1947to leave the corresponding slot in the array empty.
1948For a RAID4 or RAID5 array at most one slot can be
98c6faba 1949"\fBmissing\fP"; for a RAID6 array at most two slots.
2d465520
NB
1950For a RAID1 array, only one real device needs to be given. All of the
1951others can be
d013a55e 1952"\fBmissing\fP".
2d465520 1953
feb716e9 1954When creating a RAID5 array,
51ac42e3 1955.I mdadm
feb716e9 1956will automatically create a degraded array with an extra spare drive.
e0fe762a
N
1957This is because building the spare into a degraded array is in general
1958faster than resyncing the parity on a non-degraded, but not clean,
1959array. This feature can be overridden with the
7e23fc43 1960.B \-\-force
feb716e9
NB
1961option.
1962
0ee4da98 1963When creating an array with version-1 metadata a name for the array is
41a3b72a
NB
1964required.
1965If this is not given with the
7e23fc43 1966.B \-\-name
41a3b72a
NB
1967option,
1968.I mdadm
0ee4da98 1969will choose a name based on the last component of the name of the
41a3b72a
NB
1970device being created. So if
1971.B /dev/md3
1972is being created, then the name
1973.B 3
1974will be chosen.
1975If
1976.B /dev/md/home
1977is being created, then the name
1978.B home
1979will be used.
1980
e0fe762a
N
1981When creating a partition based array, using
1982.I mdadm
1983with version-1.x metadata, the partition type should be set to
e0f31f50 1984.B 0xDA
e0fe762a 1985(non fs-data). This type selection allows for greater precision since
e0f31f50
PC
1986using any other [RAID auto-detect (0xFD) or a GNU/Linux partition (0x83)],
1987might create problems in the event of array recovery through a live cdrom.
1988
3d3dd91e
NB
1989A new array will normally get a randomly assigned 128bit UUID which is
1990very likely to be unique. If you have a specific need, you can choose
1991a UUID for the array by giving the
7e23fc43 1992.B \-\-uuid=
3d3dd91e
NB
1993option. Be warned that creating two arrays with the same UUID is a
1994recipe for disaster. Also, using
7e23fc43 1995.B \-\-uuid=
3d3dd91e 1996when creating a v0.90 array will silently override any
7e23fc43 1997.B \-\-homehost=
3d3dd91e 1998setting.
e43d0cda
NB
1999.\"If the
2000.\".B \-\-size
2001.\"option is given, it is not necessary to list any component-devices in this command.
2002.\"They can be added later, before a
2003.\".B \-\-run.
2004.\"If no
2005.\".B \-\-size
2006.\"is given, the apparent size of the smallest drive given is used.
cd29a5c8 2007
748952f7
N
2008If the array type supports a write-intent bitmap, and if the devices
2009in the array exceed 100G is size, an internal write-intent bitmap
2010will automatically be added unless some other option is explicitly
2011requested with the
2012.B \-\-bitmap
2013option. In any case space for a bitmap will be reserved so that one
2014can be added layer with
2015.BR "\-\-grow \-\-bitmap=internal" .
2016
bf95d0f3
N
2017If the metadata type supports it (currently only 1.x metadata), space
2018will be allocated to store a bad block list. This allows a modest
2019number of bad blocks to be recorded, allowing the drive to remain in
2020service while only partially functional.
2021
8fd8d9c4
N
2022When creating an array within a
2023.B CONTAINER
2024.I mdadm
2025can be given either the list of devices to use, or simply the name of
2026the container. The former case gives control over which devices in
2027the container will be used for the array. The latter case allows
2028.I mdadm
2029to automatically choose which devices to use based on how much spare
2030space is available.
2031
53e8b987 2032The General Management options that are valid with
7e23fc43 2033.B \-\-create
53e8b987 2034are:
cd29a5c8 2035.TP
7e23fc43 2036.B \-\-run
dd0781e5 2037insist on running the array even if some devices look like they might
cd29a5c8
NB
2038be in use.
2039
2040.TP
7e23fc43 2041.B \-\-readonly
b3f1c093 2042start the array readonly \(em not supported yet.
52826846 2043
e0d19036 2044.SH MANAGE MODE
cd29a5c8
NB
2045.HP 12
2046Usage:
e0d19036
NB
2047.B mdadm
2048.I device
2049.I options... devices...
cd29a5c8
NB
2050.PP
2051
e0d19036
NB
2052This usage will allow individual devices in an array to be failed,
2053removed or added. It is possible to perform multiple operations with
e0fe762a 2054on command. For example:
e0d19036 2055.br
7e23fc43 2056.B " mdadm /dev/md0 \-f /dev/hda1 \-r /dev/hda1 \-a /dev/hda1"
e0d19036
NB
2057.br
2058will firstly mark
2059.B /dev/hda1
2060as faulty in
2061.B /dev/md0
2062and will then remove it from the array and finally add it back
2d465520 2063in as a spare. However only one md array can be affected by a single
2ae555c3 2064command.
e0d19036 2065
e0fe762a
N
2066When a device is added to an active array, mdadm checks to see if it
2067has metadata on it which suggests that it was recently a member of the
a4e13010 2068array. If it does, it tries to "re\-add" the device. If there have
e0fe762a
N
2069been no changes since the device was removed, or if the array has a
2070write-intent bitmap which has recorded whatever changes there were,
2071then the device will immediately become a full member of the array and
2072those differences recorded in the bitmap will be resolved.
2073
e0d19036
NB
2074.SH MISC MODE
2075.HP 12
2076Usage:
9a9dab36 2077.B mdadm
e0d19036 2078.I options ...
e0fe762a 2079.I devices ...
e0d19036 2080.PP
cd29a5c8 2081
b5e64645 2082MISC mode includes a number of distinct operations that
e0d19036
NB
2083operate on distinct devices. The operations are:
2084.TP
962a108f 2085.B \-\-query
e0d19036
NB
2086The device is examined to see if it is
2087(1) an active md array, or
2088(2) a component of an md array.
2089The information discovered is reported.
2090
2091.TP
962a108f 2092.B \-\-detail
2d465520 2093The device should be an active md device.
e0fe762a 2094.B mdadm
2d465520 2095will display a detailed description of the array.
7e23fc43 2096.B \-\-brief
2d465520 2097or
7e23fc43 2098.B \-\-scan
2d465520 2099will cause the output to be less detailed and the format to be
e0d19036 2100suitable for inclusion in
87eb4fab 2101.BR mdadm.conf .
feb716e9
NB
2102The exit status of
2103.I mdadm
2104will normally be 0 unless
2105.I mdadm
93e790af 2106failed to get useful information about the device(s); however, if the
7e23fc43 2107.B \-\-test
feb716e9
NB
2108option is given, then the exit status will be:
2109.RS
2110.TP
21110
2112The array is functioning normally.
2113.TP
21141
2115The array has at least one failed device.
2116.TP
21172
a77be586 2118The array has multiple failed devices such that it is unusable.
feb716e9
NB
2119.TP
21204
2121There was an error while trying to get information about the device.
2122.RE
cd29a5c8 2123
4cce4069
DW
2124.TP
2125.B \-\-detail\-platform
e0fe762a 2126Print detail of the platform's RAID capabilities (firmware / hardware
4cce4069
DW
2127topology). If the metadata is specified with
2128.B \-e
2129or
2130.B \-\-metadata=
2131then the return status will be:
2132.RS
2133.TP
21340
2135metadata successfully enumerated its platform components on this system
2136.TP
21371
2138metadata is platform independent
2139.TP
21402
2141metadata failed to find its platform components on this system
2142.RE
2143
aa534678
DW
2144.TP
2145.B \-\-update\-subarray=
2146If the device is a container and the argument to \-\-update\-subarray
2147specifies a subarray in the container, then attempt to update the given
2148superblock field in the subarray. Similar to updating an array in
2149"assemble" mode, the field to update is selected by
2150.B \-U
2151or
2152.B \-\-update=
2153option. Currently only
2154.B name
2155is supported.
2156
2157The
2158.B name
2159option updates the subarray name in the metadata, it may not affect the
2160device node name or the device node symlink until the subarray is
2161re\-assembled. If updating
2162.B name
2163would change the UUID of an active subarray this operation is blocked,
2164and the command will end in an error.
2165
e0d19036 2166.TP
962a108f 2167.B \-\-examine
2d465520 2168The device should be a component of an md array.
51ac42e3 2169.I mdadm
2d465520 2170will read the md superblock of the device and display the contents.
e0d19036 2171If
7e23fc43 2172.B \-\-brief
93e790af 2173or
7e23fc43 2174.B \-\-scan
93e790af 2175is given, then multiple devices that are components of the one array
e0d19036
NB
2176are grouped together and reported in a single entry suitable
2177for inclusion in
87eb4fab 2178.BR mdadm.conf .
e0d19036 2179
2d465520 2180Having
7e23fc43 2181.B \-\-scan
e0d19036
NB
2182without listing any devices will cause all devices listed in the
2183config file to be examined.
2184
74db60b0
N
2185.TP
2186.BI \-\-dump= directory
2187If the device contains RAID metadata, a file will be created in the
2188.I directory
2189and the metadata will be written to it. The file will be the same
2190size as the device and have the metadata written in the file at the
2191same locate that it exists in the device. However the file will be "sparse" so
2192that only those blocks containing metadata will be allocated. The
2193total space used will be small.
2194
2195The file name used in the
2196.I directory
2197will be the base name of the device. Further if any links appear in
2198.I /dev/disk/by-id
2199which point to the device, then hard links to the file will be created
2200in
2201.I directory
2202based on these
2203.I by-id
2204names.
2205
2206Multiple devices can be listed and their metadata will all be stored
2207in the one directory.
2208
2209.TP
2210.BI \-\-restore= directory
2211This is the reverse of
2212.BR \-\-dump .
2213.I mdadm
2214will locate a file in the directory that has a name appropriate for
2215the given device and will restore metadata from it. Names that match
2216.I /dev/disk/by-id
2217names are preferred, however if two of those refer to different files,
2218.I mdadm
2219will not choose between them but will abort the operation.
2220
2221If a file name is given instead of a
2222.I directory
2223then
2224.I mdadm
2225will restore from that file to a single device, always provided the
2226size of the file matches that of the device, and the file contains
2227valid metadata.
e0d19036 2228.TP
962a108f 2229.B \-\-stop
98c6faba
NB
2230The devices should be active md arrays which will be deactivated, as
2231long as they are not currently in use.
e0d19036
NB
2232
2233.TP
962a108f 2234.B \-\-run
e0d19036
NB
2235This will fully activate a partially assembled md array.
2236
2237.TP
962a108f 2238.B \-\-readonly
e0d19036
NB
2239This will mark an active array as read-only, providing that it is
2240not currently being used.
2241
2242.TP
962a108f 2243.B \-\-readwrite
e0d19036
NB
2244This will change a
2245.B readonly
2246array back to being read/write.
2247
2d465520 2248.TP
962a108f 2249.B \-\-scan
2d465520 2250For all operations except
7e23fc43
PS
2251.BR \-\-examine ,
2252.B \-\-scan
2d465520
NB
2253will cause the operation to be applied to all arrays listed in
2254.BR /proc/mdstat .
2255For
7e23fc43
PS
2256.BR \-\-examine,
2257.B \-\-scan
2d465520
NB
2258causes all devices listed in the config file to be examined.
2259
a1331cc4
N
2260.TP
2261.BR \-b ", " \-\-brief
2262Be less verbose. This is used with
2263.B \-\-detail
2264and
2265.BR \-\-examine .
2266Using
2267.B \-\-brief
2268with
2269.B \-\-verbose
2270gives an intermediate level of verbosity.
2271
e0d19036
NB
2272.SH MONITOR MODE
2273
cd29a5c8
NB
2274.HP 12
2275Usage:
7e23fc43 2276.B mdadm \-\-monitor
e0d19036
NB
2277.I options... devices...
2278
cd29a5c8 2279.PP
e0d19036 2280This usage causes
51ac42e3 2281.I mdadm
e0d19036
NB
2282to periodically poll a number of md arrays and to report on any events
2283noticed.
51ac42e3 2284.I mdadm
e0d19036
NB
2285will never exit once it decides that there are arrays to be checked,
2286so it should normally be run in the background.
2287
2d465520 2288As well as reporting events,
51ac42e3 2289.I mdadm
2d465520
NB
2290may move a spare drive from one array to another if they are in the
2291same
2292.B spare-group
210597d1
PC
2293or
2294.B domain
a9d69660 2295and if the destination array has a failed drive but no spares.
2d465520 2296
e0d19036 2297If any devices are listed on the command line,
51ac42e3 2298.I mdadm
e0fe762a 2299will only monitor those devices. Otherwise all arrays listed in the
e0d19036 2300configuration file will be monitored. Further, if
7e23fc43 2301.B \-\-scan
e0d19036
NB
2302is given, then any other md devices that appear in
2303.B /proc/mdstat
2304will also be monitored.
2305
2306The result of monitoring the arrays is the generation of events.
bd526cee 2307These events are passed to a separate program (if specified) and may
2d465520 2308be mailed to a given E-mail address.
e0d19036 2309
93e790af
SW
2310When passing events to a program, the program is run once for each event,
2311and is given 2 or 3 command-line arguments: the first is the
2312name of the event (see below), the second is the name of the
bd526cee 2313md device which is affected, and the third is the name of a related
93e790af 2314device if relevant (such as a component device that has failed).
cd29a5c8
NB
2315
2316If
7e23fc43 2317.B \-\-scan
e0d19036
NB
2318is given, then a program or an E-mail address must be specified on the
2319command line or in the config file. If neither are available, then
51ac42e3 2320.I mdadm
e0d19036
NB
2321will not monitor anything.
2322Without
93e790af 2323.B \-\-scan,
51ac42e3 2324.I mdadm
2d465520 2325will continue monitoring as long as something was found to monitor. If
e0d19036
NB
2326no program or email is given, then each event is reported to
2327.BR stdout .
cd29a5c8 2328
e0d19036
NB
2329The different events are:
2330
2331.RS 4
2332.TP
2333.B DeviceDisappeared
2d465520 2334An md array which previously was configured appears to no longer be
773135f5 2335configured. (syslog priority: Critical)
e0d19036 2336
b8f72a62
NB
2337If
2338.I mdadm
2339was told to monitor an array which is RAID0 or Linear, then it will
2340report
2341.B DeviceDisappeared
2342with the extra information
2343.BR Wrong-Level .
2344This is because RAID0 and Linear do not support the device-failed,
2345hot-spare and resync operations which are monitored.
2346
e0d19036
NB
2347.TP
2348.B RebuildStarted
773135f5 2349An md array started reconstruction. (syslog priority: Warning)
e0d19036
NB
2350
2351.TP
2352.BI Rebuild NN
2353Where
2354.I NN
9a36a9b7
ZB
2355is a two-digit number (ie. 05, 48). This indicates that rebuild
2356has passed that many percent of the total. The events are generated
2357with fixed increment since 0. Increment size may be specified with
2358a commandline option (default is 20). (syslog priority: Warning)
e0d19036 2359
98c6faba
NB
2360.TP
2361.B RebuildFinished
2362An md array that was rebuilding, isn't any more, either because it
773135f5 2363finished normally or was aborted. (syslog priority: Warning)
98c6faba 2364
e0d19036
NB
2365.TP
2366.B Fail
773135f5
NB
2367An active component device of an array has been marked as
2368faulty. (syslog priority: Critical)
e0d19036
NB
2369
2370.TP
2371.B FailSpare
2372A spare component device which was being rebuilt to replace a faulty
93e790af 2373device has failed. (syslog priority: Critical)
e0d19036
NB
2374
2375.TP
2376.B SpareActive
2377A spare component device which was being rebuilt to replace a faulty
98b24a2a 2378device has been successfully rebuilt and has been made active.
773135f5 2379(syslog priority: Info)
e0d19036
NB
2380
2381.TP
2382.B NewArray
2383A new md array has been detected in the
2384.B /proc/mdstat
e0fe762a 2385file. (syslog priority: Info)
e0d19036 2386
aa88f531
NB
2387.TP
2388.B DegradedArray
2389A newly noticed array appears to be degraded. This message is not
2390generated when
2391.I mdadm
2392notices a drive failure which causes degradation, but only when
2393.I mdadm
2394notices that an array is degraded when it first sees the array.
93e790af 2395(syslog priority: Critical)
aa88f531 2396
e0d19036
NB
2397.TP
2398.B MoveSpare
2399A spare drive has been moved from one array in a
2400.B spare-group
210597d1
PC
2401or
2402.B domain
e0d19036 2403to another to allow a failed drive to be replaced.
773135f5 2404(syslog priority: Info)
e0d19036 2405
b8f72a62
NB
2406.TP
2407.B SparesMissing
2408If
2409.I mdadm
2410has been told, via the config file, that an array should have a certain
2411number of spare devices, and
2412.I mdadm
93e790af 2413detects that it has fewer than this number when it first sees the
b8f72a62
NB
2414array, it will report a
2415.B SparesMissing
2416message.
d1732eeb 2417(syslog priority: Warning)
b8f72a62 2418
98c6faba
NB
2419.TP
2420.B TestMessage
2421An array was found at startup, and the
7e23fc43 2422.B \-\-test
98c6faba 2423flag was given.
773135f5 2424(syslog priority: Info)
e0d19036
NB
2425.RE
2426
2427Only
93e790af
SW
2428.B Fail,
2429.B FailSpare,
2430.B DegradedArray,
2431.B SparesMissing
e0d19036 2432and
98c6faba 2433.B TestMessage
e0d19036 2434cause Email to be sent. All events cause the program to be run.
93e790af 2435The program is run with two or three arguments: the event
e0d19036
NB
2436name, the array device and possibly a second device.
2437
2438Each event has an associated array device (e.g.
2439.BR /dev/md1 )
2440and possibly a second device. For
2441.BR Fail ,
2442.BR FailSpare ,
2443and
2444.B SpareActive
2445the second device is the relevant component device.
2446For
2447.B MoveSpare
2448the second device is the array that the spare was moved from.
2449
2450For
51ac42e3 2451.I mdadm
e0d19036 2452to move spares from one array to another, the different arrays need to
93e790af 2453be labeled with the same
e0d19036 2454.B spare-group
210597d1 2455or the spares must be allowed to migrate through matching POLICY domains
e0d19036
NB
2456in the configuration file. The
2457.B spare-group
93e790af 2458name can be any string; it is only necessary that different spare
2d465520 2459groups use different names.
e0d19036
NB
2460
2461When
51ac42e3 2462.I mdadm
93e790af 2463detects that an array in a spare group has fewer active
e0d19036
NB
2464devices than necessary for the complete array, and has no spare
2465devices, it will look for another array in the same spare group that
2466has a full complement of working drive and a spare. It will then
2467attempt to remove the spare from the second drive and add it to the
2468first.
2469If the removal succeeds but the adding fails, then it is added back to
2470the original array.
2471
210597d1
PC
2472If the spare group for a degraded array is not defined,
2473.I mdadm
2474will look at the rules of spare migration specified by POLICY lines in
87eb4fab 2475.B mdadm.conf
210597d1
PC
2476and then follow similar steps as above if a matching spare is found.
2477
dd0781e5
NB
2478.SH GROW MODE
2479The GROW mode is used for changing the size or shape of an active
2480array.
2481For this to work, the kernel must support the necessary change.
c64881d7 2482Various types of growth are being added during 2.6 development.
dd0781e5 2483
c64881d7 2484Currently the supported changes include
dfd4d8ee 2485.IP \(bu 4
c64881d7 2486change the "size" attribute for RAID1, RAID4, RAID5 and RAID6.
dfd4d8ee 2487.IP \(bu 4
c64881d7
N
2488increase or decrease the "raid\-devices" attribute of RAID0, RAID1, RAID4,
2489RAID5, and RAID6.
cb77f620 2490.IP \(bu 4
17790db6 2491change the chunk-size and layout of RAID0, RAID4, RAID5, RAID6 and RAID10.
cb77f620 2492.IP \(bu 4
c64881d7 2493convert between RAID1 and RAID5, between RAID5 and RAID6, between
cb77f620 2494RAID0, RAID4, and RAID5, and between RAID0 and RAID10 (in the near-2 mode).
dfd4d8ee 2495.IP \(bu 4
93e790af 2496add a write-intent bitmap to any array which supports these bitmaps, or
2ae555c3 2497remove a write-intent bitmap from such an array.
dfd4d8ee 2498.PP
dd0781e5 2499
9ab6e80a 2500Using GROW on containers is currently supported only for Intel's IMSM
c64881d7
N
2501container format. The number of devices in a container can be
2502increased - which affects all arrays in the container - or an array
2503in a container can be converted between levels where those levels are
2504supported by the container, and the conversion is on of those listed
9ab6e80a
N
2505above. Resizing arrays in an IMSM container with
2506.B "--grow --size"
2507is not yet supported.
8fd8d9c4 2508
ca24ddb0
AK
2509Grow functionality (e.g. expand a number of raid devices) for Intel's
2510IMSM container format has an experimental status. It is guarded by the
2511.B MDADM_EXPERIMENTAL
2512environment variable which must be set to '1' for a GROW command to
2513succeed.
2514This is for the following reasons:
2515
2516.IP 1.
0de8d44d
AK
2517Intel's native IMSM check-pointing is not fully tested yet.
2518This can causes IMSM incompatibility during the grow process: an array
ca24ddb0
AK
2519which is growing cannot roam between Microsoft Windows(R) and Linux
2520systems.
2521
2522.IP 2.
2523Interrupting a grow operation is not recommended, because it
2524has not been fully tested for Intel's IMSM container format yet.
2525
0de8d44d
AK
2526.PP
2527Note: Intel's native checkpointing doesn't use
2528.B --backup-file
2529option and it is transparent for assembly feature.
2530
2ae555c3 2531.SS SIZE CHANGES
c64881d7 2532Normally when an array is built the "size" is taken from the smallest
dd0781e5
NB
2533of the drives. If all the small drives in an arrays are, one at a
2534time, removed and replaced with larger drives, then you could have an
2535array of large drives with only a small amount used. In this
2536situation, changing the "size" with "GROW" mode will allow the extra
2537space to start being used. If the size is increased in this way, a
2538"resync" process will start to make sure the new parts of the array
2539are synchronised.
2540
2541Note that when an array changes size, any filesystem that may be
cb77f620 2542stored in the array will not automatically grow or shrink to use or
88b496c2 2543vacate the space. The
666bba9b
N
2544filesystem will need to be explicitly told to use the extra space
2545after growing, or to reduce its size
2546.B prior
2547to shrinking the array.
dd0781e5 2548
e0fe762a
N
2549Also the size of an array cannot be changed while it has an active
2550bitmap. If an array has a bitmap, it must be removed before the size
cb77f620 2551can be changed. Once the change is complete a new bitmap can be created.
e0fe762a
N
2552
2553.SS RAID\-DEVICES CHANGES
2ae555c3 2554
dd0781e5
NB
2555A RAID1 array can work with any number of devices from 1 upwards
2556(though 1 is not very useful). There may be times which you want to
2557increase or decrease the number of active devices. Note that this is
2558different to hot-add or hot-remove which changes the number of
2559inactive devices.
2560
2561When reducing the number of devices in a RAID1 array, the slots which
2562are to be removed from the array must already be vacant. That is, the
93e790af 2563devices which were in those slots must be failed and removed.
dd0781e5
NB
2564
2565When the number of devices is increased, any hot spares that are
a9d69660 2566present will be activated immediately.
dd0781e5 2567
f24e2d6c 2568Changing the number of active devices in a RAID5 or RAID6 is much more
2ae555c3 2569effort. Every block in the array will need to be read and written
f24e2d6c 2570back to a new location. From 2.6.17, the Linux Kernel is able to
ca4f89a3
N
2571increase the number of devices in a RAID5 safely, including restarting
2572an interrupted "reshape". From 2.6.31, the Linux Kernel is able to
f24e2d6c
N
2573increase or decrease the number of devices in a RAID5 or RAID6.
2574
c64881d7
N
2575From 2.6.35, the Linux Kernel is able to convert a RAID0 in to a RAID4
2576or RAID5.
2577.I mdadm
2578uses this functionality and the ability to add
2579devices to a RAID4 to allow devices to be added to a RAID0. When
2580requested to do this,
2581.I mdadm
2582will convert the RAID0 to a RAID4, add the necessary disks and make
2583the reshape happen, and then convert the RAID4 back to RAID0.
2584
f24e2d6c
N
2585When decreasing the number of devices, the size of the array will also
2586decrease. If there was data in the array, it could get destroyed and
666bba9b
N
2587this is not reversible, so you should firstly shrink the filesystem on
2588the array to fit within the new size. To help prevent accidents,
f24e2d6c
N
2589.I mdadm
2590requires that the size of the array be decreased first with
2591.BR "mdadm --grow --array-size" .
2592This is a reversible change which simply makes the end of the array
2593inaccessible. The integrity of any data can then be checked before
2594the non-reversible reduction in the number of devices is request.
2ae555c3 2595
cd19c0cf
JR
2596When relocating the first few stripes on a RAID5 or RAID6, it is not
2597possible to keep the data on disk completely consistent and
2598crash-proof. To provide the required safety, mdadm disables writes to
2599the array while this "critical section" is reshaped, and takes a
2600backup of the data that is in that section. For grows, this backup may be
2601stored in any spare devices that the array has, however it can also be
2602stored in a separate file specified with the
7e23fc43 2603.B \-\-backup\-file
cd19c0cf
JR
2604option, and is required to be specified for shrinks, RAID level
2605changes and layout changes. If this option is used, and the system
2606does crash during the critical period, the same file must be passed to
7e23fc43 2607.B \-\-assemble
cd19c0cf
JR
2608to restore the backup and reassemble the array. When shrinking rather
2609than growing the array, the reshape is done from the end towards the
2610beginning, so the "critical section" is at the end of the reshape.
2ae555c3 2611
f24e2d6c
N
2612.SS LEVEL CHANGES
2613
2614Changing the RAID level of any array happens instantaneously. However
cd19c0cf 2615in the RAID5 to RAID6 case this requires a non-standard layout of the
f24e2d6c 2616RAID6 data, and in the RAID6 to RAID5 case that non-standard layout is
cd19c0cf 2617required before the change can be accomplished. So while the level
f24e2d6c 2618change is instant, the accompanying layout change can take quite a
cd19c0cf
JR
2619long time. A
2620.B \-\-backup\-file
2621is required. If the array is not simultaneously being grown or
2622shrunk, so that the array size will remain the same - for example,
2623reshaping a 3-drive RAID5 into a 4-drive RAID6 - the backup file will
2624be used not just for a "cricital section" but throughout the reshape
2625operation, as described below under LAYOUT CHANGES.
f24e2d6c
N
2626
2627.SS CHUNK-SIZE AND LAYOUT CHANGES
2628
2629Changing the chunk-size of layout without also changing the number of
2630devices as the same time will involve re-writing all blocks in-place.
2631To ensure against data loss in the case of a crash, a
2632.B --backup-file
2633must be provided for these changes. Small sections of the array will
cd19c0cf
JR
2634be copied to the backup file while they are being rearranged. This
2635means that all the data is copied twice, once to the backup and once
2636to the new layout on the array, so this type of reshape will go very
2637slowly.
f24e2d6c
N
2638
2639If the reshape is interrupted for any reason, this backup file must be
cd19c0cf 2640made available to
f24e2d6c
N
2641.B "mdadm --assemble"
2642so the array can be reassembled. Consequently the file cannot be
2643stored on the device being reshaped.
2644
2645
2ae555c3
NB
2646.SS BITMAP CHANGES
2647
2648A write-intent bitmap can be added to, or removed from, an active
93e790af 2649array. Either internal bitmaps, or bitmaps stored in a separate file,
fe80f49b 2650can be added. Note that if you add a bitmap stored in a file which is
e0fe762a 2651in a filesystem that is on the RAID array being affected, the system
fe80f49b
NB
2652will deadlock. The bitmap must be on a separate filesystem.
2653
8382f19b
NB
2654.SH INCREMENTAL MODE
2655
2656.HP 12
2657Usage:
7e23fc43
PS
2658.B mdadm \-\-incremental
2659.RB [ \-\-run ]
2660.RB [ \-\-quiet ]
8382f19b
NB
2661.I component-device
2662.HP 12
2663Usage:
29ba4804
N
2664.B mdadm \-\-incremental \-\-fail
2665.I component-device
2666.HP 12
2667Usage:
7e6140e6 2668.B mdadm \-\-incremental \-\-rebuild\-map
8382f19b
NB
2669.HP 12
2670Usage:
7e23fc43 2671.B mdadm \-\-incremental \-\-run \-\-scan
8382f19b 2672
8382f19b
NB
2673.PP
2674This mode is designed to be used in conjunction with a device
2675discovery system. As devices are found in a system, they can be
2676passed to
7e23fc43 2677.B "mdadm \-\-incremental"
8382f19b
NB
2678to be conditionally added to an appropriate array.
2679
29ba4804
N
2680Conversely, it can also be used with the
2681.B \-\-fail
2682flag to do just the opposite and find whatever array a particular device
2683is part of and remove the device from that array.
2684
8fd8d9c4
N
2685If the device passed is a
2686.B CONTAINER
2687device created by a previous call to
2688.IR mdadm ,
2689then rather than trying to add that device to an array, all the arrays
2690described by the metadata of the container will be started.
2691
8382f19b
NB
2692.I mdadm
2693performs a number of tests to determine if the device is part of an
93e790af 2694array, and which array it should be part of. If an appropriate array
8382f19b
NB
2695is found, or can be created,
2696.I mdadm
2697adds the device to the array and conditionally starts the array.
2698
2699Note that
2700.I mdadm
87eb4fab
N
2701will normally only add devices to an array which were previously working
2702(active or spare) parts of that array. The support for automatic
210597d1
PC
2703inclusion of a new drive as a spare in some array requires
2704a configuration through POLICY in config file.
8382f19b 2705
8382f19b
NB
2706The tests that
2707.I mdadm
2708makes are as follow:
2709.IP +
2710Is the device permitted by
2711.BR mdadm.conf ?
2712That is, is it listed in a
2713.B DEVICES
2714line in that file. If
2715.B DEVICES
2716is absent then the default it to allow any device. Similar if
2717.B DEVICES
2718contains the special word
2719.B partitions
2720then any device is allowed. Otherwise the device name given to
2721.I mdadm
2722must match one of the names or patterns in a
2723.B DEVICES
2724line.
2725
2726.IP +
cb77f620
NK
2727Does the device have a valid md superblock? If a specific metadata
2728version is requested with
7e23fc43 2729.B \-\-metadata
8382f19b 2730or
7e23fc43 2731.B \-e
8382f19b
NB
2732then only that style of metadata is accepted, otherwise
2733.I mdadm
2734finds any known version of metadata. If no
2735.I md
210597d1
PC
2736metadata is found, the device may be still added to an array
2737as a spare if POLICY allows.
8382f19b 2738
d1302dd8 2739.ig
8382f19b
NB
2740.IP +
2741Does the metadata match an expected array?
2742The metadata can match in two ways. Either there is an array listed
2743in
2744.B mdadm.conf
2745which identifies the array (either by UUID, by name, by device list,
93e790af 2746or by minor-number), or the array was created with a
8382f19b 2747.B homehost
93e790af 2748specified and that
8382f19b 2749.B homehost
93e790af 2750matches the one in
8382f19b
NB
2751.B mdadm.conf
2752or on the command line.
2753If
2754.I mdadm
2755is not able to positively identify the array as belonging to the
2756current host, the device will be rejected.
d1302dd8 2757..
8382f19b 2758
cb77f620 2759.PP
8382f19b 2760.I mdadm
93e790af 2761keeps a list of arrays that it has partially assembled in
96fd06ed 2762.BR {MAP_PATH} .
e0fe762a 2763If no array exists which matches
8382f19b
NB
2764the metadata on the new device,
2765.I mdadm
2766must choose a device name and unit number. It does this based on any
2767name given in
2768.B mdadm.conf
2769or any name information stored in the metadata. If this name
2770suggests a unit number, that number will be used, otherwise a free
2771unit number will be chosen. Normally
2772.I mdadm
2773will prefer to create a partitionable array, however if the
2774.B CREATE
2775line in
2776.B mdadm.conf
2777suggests that a non-partitionable array is preferred, that will be
2778honoured.
2779
e0fe762a
N
2780If the array is not found in the config file and its metadata does not
2781identify it as belonging to the "homehost", then
2782.I mdadm
2783will choose a name for the array which is certain not to conflict with
2784any array which does belong to this host. It does this be adding an
2785underscore and a small number to the name preferred by the metadata.
2786
8382f19b
NB
2787Once an appropriate array is found or created and the device is added,
2788.I mdadm
2789must decide if the array is ready to be started. It will
2790normally compare the number of available (non-spare) devices to the
2791number of devices that the metadata suggests need to be active. If
2792there are at least that many, the array will be started. This means
2793that if any devices are missing the array will not be restarted.
2794
2795As an alternative,
7e23fc43 2796.B \-\-run
8382f19b 2797may be passed to
51ac42e3 2798.I mdadm
8382f19b 2799in which case the array will be run as soon as there are enough
e0fe762a
N
2800devices present for the data to be accessible. For a RAID1, that
2801means one device will start the array. For a clean RAID5, the array
8382f19b
NB
2802will be started as soon as all but one drive is present.
2803
93e790af 2804Note that neither of these approaches is really ideal. If it can
8382f19b
NB
2805be known that all device discovery has completed, then
2806.br
7e23fc43 2807.B " mdadm \-IRs"
8382f19b
NB
2808.br
2809can be run which will try to start all arrays that are being
2810incrementally assembled. They are started in "read-auto" mode in
2811which they are read-only until the first write request. This means
2812that no metadata updates are made and no attempt at resync or recovery
2813happens. Further devices that are found before the first write can
2814still be added safely.
2815
5545fa6d
DW
2816.SH ENVIRONMENT
2817This section describes environment variables that affect how mdadm
2818operates.
2819
2820.TP
2821.B MDADM_NO_MDMON
2822Setting this value to 1 will prevent mdadm from automatically launching
2823mdmon. This variable is intended primarily for debugging mdadm/mdmon.
2824
8fd8d9c4
N
2825.TP
2826.B MDADM_NO_UDEV
2827Normally,
2828.I mdadm
2829does not create any device nodes in /dev, but leaves that task to
2830.IR udev .
2831If
2832.I udev
2833appears not to be configured, or if this environment variable is set
2834to '1', the
2835.I mdadm
2836will create and devices that are needed.
2837
401f095c
N
2838.TP
2839.B IMSM_NO_PLATFORM
2840A key value of IMSM metadata is that it allows interoperability with
2841boot ROMs on Intel platforms, and with other major operating systems.
2842Consequently,
2843.I mdadm
2844will only allow an IMSM array to be created or modified if detects
2845that it is running on an Intel platform which supports IMSM, and
2846supports the particular configuration of IMSM that is being requested
2847(some functionality requires newer OROM support).
2848
2849These checks can be suppressed by setting IMSM_NO_PLATFORM=1 in the
2850environment. This can be useful for testing or for disaster
2851recovery. You should be aware that interoperability may be
2852compromised by setting this value.
2dfb675b
N
2853
2854.TP
2855.B MDADM_CONF_AUTO
2856Any string given in this variable is added to the start of the
2857.B AUTO
2858line in the config file, or treated as the whole
2859.B AUTO
2860line if none is given. It can be used to disable certain metadata
2861types when
2862.I mdadm
2863is called from a boot script. For example
2864.br
2865.B " export MDADM_CONF_AUTO='-ddf -imsm'
2866.br
2867will make sure that
2868.I mdadm
2869does not automatically assemble any DDF or
2870IMSM arrays that are found. This can be useful on systems configured
2871to manage such arrays with
2872.BR dmraid .
2873
2874
2d465520
NB
2875.SH EXAMPLES
2876
7e23fc43 2877.B " mdadm \-\-query /dev/name-of-device"
2d465520 2878.br
e0fe762a 2879This will find out if a given device is a RAID array, or is part of
5787fa49 2880one, and will provide brief information about the device.
2d465520 2881
7e23fc43 2882.B " mdadm \-\-assemble \-\-scan"
2d465520 2883.br
93e790af 2884This will assemble and start all arrays listed in the standard config
5787fa49 2885file. This command will typically go in a system startup file.
2d465520 2886
7e23fc43 2887.B " mdadm \-\-stop \-\-scan"
5787fa49 2888.br
93e790af 2889This will shut down all arrays that can be shut down (i.e. are not
19f8b8fc 2890currently in use). This will typically go in a system shutdown script.
2d465520 2891
7e23fc43 2892.B " mdadm \-\-follow \-\-scan \-\-delay=120"
2d465520 2893.br
5787fa49
NB
2894If (and only if) there is an Email address or program given in the
2895standard config file, then
2896monitor the status of all arrays listed in that file by
2897polling them ever 2 minutes.
2d465520 2898
7e23fc43 2899.B " mdadm \-\-create /dev/md0 \-\-level=1 \-\-raid\-devices=2 /dev/hd[ac]1"
2d465520 2900.br
5787fa49 2901Create /dev/md0 as a RAID1 array consisting of /dev/hda1 and /dev/hdc1.
2d465520 2902
2d465520 2903.br
7e23fc43 2904.B " echo 'DEVICE /dev/hd*[0\-9] /dev/sd*[0\-9]' > mdadm.conf"
2d465520 2905.br
7e23fc43 2906.B " mdadm \-\-detail \-\-scan >> mdadm.conf"
2d465520 2907.br
5787fa49
NB
2908This will create a prototype config file that describes currently
2909active arrays that are known to be made from partitions of IDE or SCSI drives.
2d465520
NB
2910This file should be reviewed before being used as it may
2911contain unwanted detail.
2912
7e23fc43 2913.B " echo 'DEVICE /dev/hd[a\-z] /dev/sd*[a\-z]' > mdadm.conf"
2d465520 2914.br
7e23fc43 2915.B " mdadm \-\-examine \-\-scan \-\-config=mdadm.conf >> mdadm.conf"
93e790af
SW
2916.br
2917This will find arrays which could be assembled from existing IDE and
2918SCSI whole drives (not partitions), and store the information in the
5787fa49 2919format of a config file.
2d465520
NB
2920This file is very likely to contain unwanted detail, particularly
2921the
2922.B devices=
5787fa49
NB
2923entries. It should be reviewed and edited before being used as an
2924actual config file.
2d465520 2925
7e23fc43 2926.B " mdadm \-\-examine \-\-brief \-\-scan \-\-config=partitions"
2d465520 2927.br
7e23fc43 2928.B " mdadm \-Ebsc partitions"
5787fa49
NB
2929.br
2930Create a list of devices by reading
2931.BR /proc/partitions ,
2932scan these for RAID superblocks, and printout a brief listing of all
93e790af 2933that were found.
2d465520 2934
7e23fc43 2935.B " mdadm \-Ac partitions \-m 0 /dev/md0"
2d465520 2936.br
5787fa49
NB
2937Scan all partitions and devices listed in
2938.BR /proc/partitions
2939and assemble
2940.B /dev/md0
2941out of all such devices with a RAID superblock with a minor number of 0.
2d465520 2942
96fd06ed 2943.B " mdadm \-\-monitor \-\-scan \-\-daemonise > /run/mdadm/mon.pid"
d013a55e
NB
2944.br
2945If config file contains a mail address or alert program, run mdadm in
2946the background in monitor mode monitoring all md devices. Also write
2947pid of mdadm daemon to
96fd06ed 2948.BR /run/mdadm/mon.pid .
d013a55e 2949
7e23fc43 2950.B " mdadm \-Iq /dev/somedevice"
8382f19b
NB
2951.br
2952Try to incorporate newly discovered device into some array as
2953appropriate.
2954
7e6140e6 2955.B " mdadm \-\-incremental \-\-rebuild\-map \-\-run \-\-scan"
8382f19b
NB
2956.br
2957Rebuild the array map from any current arrays, and then start any that
2958can be started.
2959
b80da661
NB
2960.B " mdadm /dev/md4 --fail detached --remove detached"
2961.br
2962Any devices which are components of /dev/md4 will be marked as faulty
2963and then remove from the array.
2964
cb77f620 2965.B " mdadm --grow /dev/md4 --level=6 --backup-file=/root/backup-md4"
f24e2d6c
N
2966.br
2967The array
2968.B /dev/md4
2969which is currently a RAID5 array will be converted to RAID6. There
2970should normally already be a spare drive attached to the array as a
2971RAID6 needs one more drive than a matching RAID5.
2972
8fd8d9c4
N
2973.B " mdadm --create /dev/md/ddf --metadata=ddf --raid-disks 6 /dev/sd[a-f]"
2974.br
2975Create a DDF array over 6 devices.
2976
2977.B " mdadm --create /dev/md/home -n3 -l5 -z 30000000 /dev/md/ddf"
2978.br
e0fe762a 2979Create a RAID5 array over any 3 devices in the given DDF set. Use
8fd8d9c4
N
2980only 30 gigabytes of each device.
2981
2982.B " mdadm -A /dev/md/ddf1 /dev/sd[a-f]"
2983.br
2984Assemble a pre-exist ddf array.
2985
2986.B " mdadm -I /dev/md/ddf1"
2987.br
2988Assemble all arrays contained in the ddf array, assigning names as
2989appropriate.
2990
7e23fc43 2991.B " mdadm \-\-create \-\-help"
2d465520 2992.br
2ae555c3 2993Provide help about the Create mode.
2d465520 2994
7e23fc43 2995.B " mdadm \-\-config \-\-help"
5787fa49
NB
2996.br
2997Provide help about the format of the config file.
2d465520 2998
7e23fc43 2999.B " mdadm \-\-help"
5787fa49
NB
3000.br
3001Provide general help.
cd29a5c8 3002
cd29a5c8
NB
3003.SH FILES
3004
3005.SS /proc/mdstat
3006
2ae555c3
NB
3007If you're using the
3008.B /proc
cd29a5c8
NB
3009filesystem,
3010.B /proc/mdstat
2d465520 3011lists all active md devices with information about them.
51ac42e3 3012.I mdadm
2d465520 3013uses this to find arrays when
7e23fc43 3014.B \-\-scan
2d465520
NB
3015is given in Misc mode, and to monitor array reconstruction
3016on Monitor mode.
3017
9a9dab36 3018.SS /etc/mdadm.conf
cd29a5c8 3019
11a3e71d
NB
3020The config file lists which devices may be scanned to see if
3021they contain MD super block, and gives identifying information
3022(e.g. UUID) about known MD arrays. See
3023.BR mdadm.conf (5)
3024for more details.
cd29a5c8 3025
9dc70cbc
N
3026.SS /etc/mdadm.conf.d
3027
3028A directory containing configuration files which are read in lexical
3029order.
3030
96fd06ed 3031.SS {MAP_PATH}
8382f19b 3032When
7e23fc43 3033.B \-\-incremental
93e790af 3034mode is used, this file gets a list of arrays currently being created.
8382f19b 3035
48f7b27a
NB
3036.SH DEVICE NAMES
3037
48f7b27a 3038.I mdadm
8fd8d9c4
N
3039understand two sorts of names for array devices.
3040
3041The first is the so-called 'standard' format name, which matches the
3042names used by the kernel and which appear in
3043.IR /proc/mdstat .
3044
3045The second sort can be freely chosen, but must reside in
3046.IR /dev/md/ .
3047When giving a device name to
3048.I mdadm
3049to create or assemble an array, either full path name such as
3050.I /dev/md0
3051or
3052.I /dev/md/home
3053can be given, or just the suffix of the second sort of name, such as
3054.I home
3055can be given.
3056
3057When
3058.I mdadm
e0fe762a
N
3059chooses device names during auto-assembly or incremental assembly, it
3060will sometimes add a small sequence number to the end of the name to
3061avoid conflicted between multiple arrays that have the same name. If
8fd8d9c4
N
3062.I mdadm
3063can reasonably determine that the array really is meant for this host,
3064either by a hostname in the metadata, or by the presence of the array
87eb4fab
N
3065in
3066.BR mdadm.conf ,
3067then it will leave off the suffix if possible.
e0fe762a
N
3068Also if the homehost is specified as
3069.B <ignore>
3070.I mdadm
3071will only use a suffix if a different array of the same name already
3072exists or is listed in the config file.
48f7b27a
NB
3073
3074The standard names for non-partitioned arrays (the only sort of md
8fd8d9c4 3075array available in 2.4 and earlier) are of the form
48f7b27a 3076.IP
eca944fa 3077.RB /dev/md NN
48f7b27a
NB
3078.PP
3079where NN is a number.
3080The standard names for partitionable arrays (as available from 2.6
eca944fa 3081onwards) are of the form:
48f7b27a 3082.IP
eca944fa 3083.RB /dev/md_d NN
48f7b27a 3084.PP
eca944fa 3085Partition numbers should be indicated by adding "pMM" to these, thus "/dev/md/d1p2".
8fd8d9c4 3086.PP
eca944fa
N
3087From kernel version 2.6.28 the "non-partitioned array" can actually
3088be partitioned. So the "md_d\fBNN\fP"
3089names are no longer needed, and
3090partitions such as "/dev/md\fBNN\fPp\fBXX\fp"
3091are possible.
3092.PP
3093From kernel version 2.6.29 standard names can be non-numeric following
3094the form:
3095.IP
3096.RB /dev/md_ XXX
3097.PP
3098where
3099.B XXX
3100is any string. These names are supported by
3101.I mdadm
3102since version 3.3 provided they are enabled in
3103.IR mdadm.conf .
52826846 3104
2d465520 3105.SH NOTE
51ac42e3 3106.I mdadm
2d465520 3107was previously known as
51ac42e3 3108.IR mdctl .
a9d69660 3109
52826846 3110.SH SEE ALSO
75f74377 3111For further information on mdadm usage, MD and the various levels of
3cdfb6a7 3112RAID, see:
3cdfb6a7 3113.IP
cb77f620 3114.B http://raid.wiki.kernel.org/
75f74377
DG
3115.PP
3116(based upon Jakob \(/Ostergaard's Software\-RAID.HOWTO)
cd29a5c8 3117.PP
2ae555c3 3118The latest version of
a9d69660
NB
3119.I mdadm
3120should always be available from
cd29a5c8 3121.IP
11cd8b79
N
3122.B http://www.kernel.org/pub/linux/utils/raid/mdadm/
3123.PP
3124Related man pages:
cd29a5c8 3125.PP
e0fe762a 3126.IR mdmon (8),
a9d69660
NB
3127.IR mdadm.conf (5),
3128.IR md (4).