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