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