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