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