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