Default to --auto=yes
[thirdparty/mdadm.git] / mdadm.8
CommitLineData
52826846 1.\" -*- nroff -*-
90fc992e
NB
2''' Copyright Neil Brown and others.
3''' This program is free software; you can redistribute it and/or modify
4''' it under the terms of the GNU General Public License as published by
5''' the Free Software Foundation; either version 2 of the License, or
6''' (at your option) any later version.
7''' See file COPYING in distribution for details.
9255bbc8 8.TH MDADM 8 "" v2.5.6
52826846 9.SH NAME
9a9dab36 10mdadm \- manage MD devices
cd29a5c8
NB
11.I aka
12Linux Software Raid.
13
52826846
NB
14.SH SYNOPSIS
15
e0d19036 16.BI mdadm " [mode] <raiddevice> [options] <component-devices>"
52826846 17
2ae555c3 18.SH DESCRIPTION
52826846 19RAID devices are virtual devices created from two or more
cd29a5c8
NB
20real block devices. This allows multiple devices (typically disk
21drives or partitions there-of) to be combined into a single device to
22hold (for example) a single filesystem.
2d465520 23Some RAID levels include redundancy and so can survive some degree of
cd29a5c8
NB
24device failure.
25
2d465520
NB
26Linux Software RAID devices are implemented through the md (Multiple
27Devices) device driver.
cd29a5c8
NB
28
29Currently, Linux supports
30.B LINEAR
31md devices,
32.B RAID0
33(striping),
34.B RAID1
35(mirroring),
d013a55e
NB
36.BR RAID4 ,
37.BR RAID5 ,
98c6faba 38.BR RAID6 ,
1a7dfc35 39.BR RAID10 ,
b5e64645 40.BR MULTIPATH ,
cd29a5c8 41and
b5e64645 42.BR FAULTY .
d013a55e 43
a9d69660
NB
44.B MULTIPATH
45is not a Software RAID mechanism, but does involve
d013a55e
NB
46multiple devices. For
47.B MULTIPATH
48each device is a path to one common physical storage device.
49
a9d69660
NB
50.B FAULTY
51is also not true RAID, and it only involves one device. It
b5e64645 52provides a layer over a true device that can be used to inject faults.
52826846 53
a9d69660
NB
54'''.B mdadm
55'''is a program that can be used to create, manage, and monitor
56'''MD devices. As
57'''such it provides a similar set of functionality to the
58'''.B raidtools
59'''packages.
60'''The key differences between
61'''.B mdadm
62'''and
63'''.B raidtools
64'''are:
65'''.IP \(bu 4
66'''.B mdadm
67'''is a single program and not a collection of programs.
68'''.IP \(bu 4
69'''.B mdadm
70'''can perform (almost) all of its functions without having a
71'''configuration file and does not use one by default. Also
72'''.B mdadm
73'''helps with management of the configuration
74'''file.
75'''.IP \(bu 4
76'''.B mdadm
77'''can provide information about your arrays (through Query, Detail, and Examine)
78'''that
79'''.B raidtools
80'''cannot.
81'''.P
82'''.I mdadm
83'''does not use
84'''.IR /etc/raidtab ,
85'''the
86'''.B raidtools
87'''configuration file, at all. It has a different configuration file
98b24a2a 88'''with a different format and a different purpose.
52826846
NB
89
90.SH MODES
dd0781e5 91mdadm has 7 major modes of operation:
cd29a5c8
NB
92.TP
93.B Assemble
94Assemble the parts of a previously created
52826846 95array into an active array. Components can be explicitly given
2ae555c3 96or can be searched for.
9a9dab36 97.B mdadm
cd29a5c8
NB
98checks that the components
99do form a bona fide array, and can, on request, fiddle superblock
100information so as to assemble a faulty array.
101
102.TP
103.B Build
a9d69660
NB
104Build an array that doesn't have per-device superblocks. For these
105sorts of arrays,
106.I mdadm
107cannot differentiate between initial creation and subsequent assembly
108of an array. It also cannot perform any checks that appropriate
109devices have been requested. Because of this, the
110.B Build
111mode should only be used together with a complete understanding of
112what you are doing.
cd29a5c8
NB
113
114.TP
115.B Create
116Create a new array with per-device superblocks.
117'''It can progress
118'''in several step create-add-add-run or it can all happen with one command.
119
cd29a5c8
NB
120.TP
121.B "Follow or Monitor"
5787fa49 122Monitor one or more md devices and act on any state changes. This is
1a7dfc35 123only meaningful for raid1, 4, 5, 6, 10 or multipath arrays as
98c6faba
NB
124only these have interesting state. raid0 or linear never have
125missing, spare, or failed drives, so there is nothing to monitor.
5787fa49 126
dd0781e5
NB
127.TP
128.B "Grow"
129Grow (or shrink) an array, or otherwise reshape it in some way.
130Currently supported growth options including changing the active size
2ae555c3 131of component devices in RAID level 1/4/5/6 and changing the number of
dd0781e5 132active devices in RAID1.
cd29a5c8 133
2ae555c3
NB
134.TP
135.B Manage
136This is for doing things to specific components of an array such as
137adding new spares and removing faulty devices.
138
139.TP
140.B Misc
141This is an 'everything else' mode that supports operations on active
142arrays, operations on component devices such as erasing old superblocks, and
143information gathering operations.
144'''This mode allows operations on independent devices such as examine MD
145'''superblocks, erasing old superblocks and stopping active arrays.
146
52826846
NB
147.SH OPTIONS
148
2ae555c3 149.SH Options for selecting a mode are:
52826846 150
cd29a5c8
NB
151.TP
152.BR -A ", " --assemble
2d465520 153Assemble a pre-existing array.
52826846 154
cd29a5c8
NB
155.TP
156.BR -B ", " --build
157Build a legacy array without superblocks.
52826846 158
cd29a5c8
NB
159.TP
160.BR -C ", " --create
161Create a new array.
52826846 162
cd29a5c8
NB
163.TP
164.BR -F ", " --follow ", " --monitor
165Select
166.B Monitor
167mode.
52826846 168
dd0781e5
NB
169.TP
170.BR -G ", " --grow
171Change the size or shape of an active array.
2ae555c3
NB
172.P
173If a device is given before any options, or if the first option is
174.BR --add ,
175.BR --fail ,
176or
177.BR --remove ,
178then the MANAGE mode is assume.
179Anything other than these will cause the
180.B Misc
181mode to be assumed.
dd0781e5 182
2ae555c3 183.SH Options that are not mode-specific are:
e793c2e5 184
cd29a5c8
NB
185.TP
186.BR -h ", " --help
a9d69660
NB
187Display general help message or, after one of the above options, a
188mode specific help message.
56eedc1a
NB
189
190.TP
191.B --help-options
192Display more detailed help about command line parsing and some commonly
193used options.
52826846 194
cd29a5c8
NB
195.TP
196.BR -V ", " --version
9a9dab36 197Print version information for mdadm.
52826846 198
cd29a5c8
NB
199.TP
200.BR -v ", " --verbose
22892d56
NB
201Be more verbose about what is happening. This can be used twice to be
202extra-verbose.
a9d69660 203The extra verbosity currently only affects
22892d56
NB
204.B --detail --scan
205and
206.BR "--examine --scan" .
52826846 207
dab6685f
NB
208.TP
209.BR -q ", " --quiet
210Avoid printing purely informative messages. With this,
211.B mdadm
212will be silent unless there is something really important to report.
213
cd29a5c8
NB
214.TP
215.BR -b ", " --brief
216Be less verbose. This is used with
217.B --detail
218and
219.BR --examine .
22892d56
NB
220Using
221.B --brief
222with
223.B --verbose
224gives an intermediate level of verbosity.
52826846 225
e0d19036
NB
226.TP
227.BR -f ", " --force
228Be more forceful about certain operations. See the various modes of
229the exact meaning of this option in different contexts.
230
231.TP
232.BR -c ", " --config=
2ae555c3
NB
233Specify the config file. Default is to use
234.BR /etc/mdadm.conf ,
235or if that is missing, then
236.BR /etc/mdadm/mdadm.conf .
5787fa49
NB
237If the config file given is
238.B partitions
239then nothing will be read, but
240.I mdadm
241will act as though the config file contained exactly
242.B "DEVICE partitions"
243and will read
244.B /proc/partitions
245to find a list of devices to scan.
d013a55e
NB
246If the word
247.B none
248is given for the config file, then
249.I mdadm
250will act as though the config file were empty.
e0d19036
NB
251
252.TP
253.BR -s ", " --scan
254scan config file or
255.B /proc/mdstat
256for missing information.
257In general, this option gives
258.B mdadm
259permission to get any missing information, like component devices,
260array devices, array identities, and alert destination from the
261configuration file:
262.BR /etc/mdadm.conf .
263One exception is MISC mode when using
264.B --detail
265or
266.B --stop
267in which case
268.B --scan
269says to get a list of array devices from
270.BR /proc/mdstat .
271
570c0542
NB
272.TP
273.B -e ", " --metadata=
274Declare the style of superblock (raid metadata) to be used. The
275default is 0.90 for --create, and to guess for other operations.
2790ffe3
GB
276The default can be overridden by setting the
277.B metadata
278value for the
279.B CREATE
280keyword in
281.BR mdadm.conf .
570c0542
NB
282
283Options are:
284.RS
285.IP "0, 0.90, default"
286Use the original 0.90 format superblock. This format limits arrays to
28728 componenet devices and limits component devices of levels 1 and
288greater to 2 terabytes.
289.IP "1, 1.0, 1.1, 1.2"
290Use the new version-1 format superblock. This has few restrictions.
291The different subversion store the superblock at different locations
292on the device, either at the end (for 1.0), at the start (for 1.1) or
2934K from the start (for 1.2).
294.RE
295
41a3b72a
NB
296.TP
297.B --homehost=
298This will over-ride any
299.B HOMEHOST
300setting in the config file and provides the identify of the host which
301should be considered the home for any arrays.
302
303When creating an array, the
304.B homehost
305will be recorded in the superblock. For version-1 superblocks, it will
306be prefixed to the array name. For version-0.90 superblocks part of
307the SHA1 hash of the hostname will be stored in the later half of the
308UUID.
309
310When reporting information about an array, any array which is tagged
311for the given homehost will be reported as such.
312
313When using Auto-Assemble, only arrays tagged for the given homehost
314will be assembled.
315
2ae555c3
NB
316.SH For create, build, or grow:
317
318.TP
319.BR -n ", " --raid-devices=
320Specify the number of active devices in the array. This, plus the
321number of spare devices (see below) must equal the number of
322.I component-devices
323(including "\fBmissing\fP" devices)
324that are listed on the command line for
325.BR --create .
326Setting a value of 1 is probably
327a mistake and so requires that
328.B --force
329be specified first. A value of 1 will then be allowed for linear,
330multipath, raid0 and raid1. It is never allowed for raid4 or raid5.
331.br
332This number can only be changed using
333.B --grow
334for RAID1 arrays, and only on kernels which provide necessary support.
335
336.TP
337.BR -x ", " --spare-devices=
338Specify the number of spare (eXtra) devices in the initial array.
339Spares can also be added
340and removed later. The number of component devices listed
341on the command line must equal the number of raid devices plus the
342number of spare devices.
343
344
345.TP
346.BR -z ", " --size=
347Amount (in Kibibytes) of space to use from each drive in RAID1/4/5/6.
348This must be a multiple of the chunk size, and must leave about 128Kb
349of space at the end of the drive for the RAID superblock.
350If this is not specified
351(as it normally is not) the smallest drive (or partition) sets the
352size, though if there is a variance among the drives of greater than 1%, a warning is
353issued.
354
355This value can be set with
356.B --grow
357for RAID level 1/4/5/6. If the array was created with a size smaller
358than the currently active drives, the extra space can be accessed
359using
360.BR --grow .
361The size can be given as
362.B max
363which means to choose the largest size that fits on all current drives.
52826846 364
cd29a5c8
NB
365.TP
366.BR -c ", " --chunk=
367Specify chunk size of kibibytes. The default is 64.
52826846 368
cd29a5c8
NB
369.TP
370.BR --rounding=
371Specify rounding factor for linear array (==chunk size)
52826846 372
cd29a5c8
NB
373.TP
374.BR -l ", " --level=
aa88f531
NB
375Set raid level. When used with
376.IR --create ,
98c6faba 377options are: linear, raid0, 0, stripe, raid1, 1, mirror, raid4, 4,
2ae555c3 378raid5, 5, raid6, 6, raid10, 10, multipath, mp, faulty. Obviously some of these are synonymous.
aa88f531
NB
379
380When used with
381.IR --build ,
a9d69660 382only linear, stripe, raid0, 0, raid1, multipath, mp, and faulty are valid.
52826846 383
2ae555c3
NB
384Not yet supported with
385.IR --grow .
386
cd29a5c8 387.TP
1a7dfc35
NB
388.BR -p ", " --layout=
389This option configures the fine details of data layout for raid5,
390and raid10 arrays, and controls the failure modes for
391.IR faulty .
392
393The layout of the raid5 parity block can be one of
2d465520
NB
394left-asymmetric,
395left-symmetric,
396right-asymmetric,
397right-symmetric,
398la, ra, ls, rs. The default is left-symmetric.
52826846 399
1a7dfc35
NB
400When setting the failure mode for
401.I faulty
402the options are:
b5e64645
NB
403write-transient,
404wt,
405read-transient,
406rt,
2ae555c3 407write-persistent,
b5e64645
NB
408wp,
409read-persistent,
410rp,
411write-all,
412read-fixable,
413rf,
414clear,
415flush,
416none.
417
418Each mode can be followed by a number which is used as a period
419between fault generation. Without a number, the fault is generated
420once on the first relevant request. With a number, the fault will be
421generated after that many request, and will continue to be generated
422every time the period elapses.
423
424Multiple failure modes can be current simultaneously by using the
425"--grow" option to set subsequent failure modes.
426
427"clear" or "none" will remove any pending or periodic failure modes,
2ae555c3 428and "flush" will clear any persistent faults.
b5e64645
NB
429
430To set the parity with "--grow", the level of the array ("faulty")
431must be specified before the fault mode is specified.
432
b578481c 433Finally, the layout options for RAID10 are one of 'n', 'o' or 'p' followed
1a7dfc35
NB
434by a small number. The default is 'n2'.
435
436.I n
b578481c
NB
437signals 'near' copies. Multiple copies of one data block are at
438similar offsets in different devices.
439
440.I o
441signals 'offset' copies. Rather than the chunks being duplicated
442within a stripe, whole stripes are duplicated but are rotated by one
443device so duplicate blocks are on different devices. Thus subsequent
444copies of a block are in the next drive, and are one chunk further
445down.
446
1a7dfc35
NB
447.I f
448signals 'far' copies
449(multiple copies have very different offsets). See md(4) for more
450detail about 'near' and 'far'.
451
452The number is the number of copies of each datablock. 2 is normal, 3
453can be useful. This number can be at most equal to the number of
454devices in the array. It does not need to divide evenly into that
455number (e.g. it is perfectly legal to have an 'n2' layout for an array
456with an odd number of devices).
457
cd29a5c8 458.TP
1a7dfc35
NB
459.BR --parity=
460same as --layout (thus explaining the p of
461.IR -p ).
52826846 462
e793c2e5
NB
463.TP
464.BR -b ", " --bitmap=
465Specify a file to store a write-intent bitmap in. The file should not
466exist unless --force is also given. The same file should be provided
2ae555c3
NB
467when assembling the array. If the word
468.B internal
469is given, then the bitmap is stored with the metadata on the array,
470and so is replicated on all devices. If the word
471.B none
472is given with
473.B --grow
474mode, then any bitmap that is present is removed.
e793c2e5 475
2ae555c3
NB
476To help catch typing errors, the filename must contain at least one
477slash ('/') if it is a real file (not 'internal' or 'none').
478
479Note: external bitmaps are only known to work on ext2 and ext3.
480Storing bitmap files on other filesystems may result in serious problems.
e793c2e5 481
cd29a5c8 482.TP
2ae555c3
NB
483.BR --bitmap-chunk=
484Set the chunksize of the bitmap. Each bit corresponds to that many
1bfdbe01
NB
485Kilobytes of storage.
486When using a file based bitmap, the default is to use the smallest
487size that is atleast 4 and requires no more than 2^21 chunks.
2ae555c3
NB
488When using an
489.B internal
490bitmap, the chunksize is automatically determined to make best use of
491available space.
5787fa49 492
cd29a5c8
NB
493
494.TP
2ae555c3
NB
495.BR -W ", " --write-mostly
496subsequent devices lists in a
497.BR --build ,
498.BR --create ,
499or
500.B --add
501command will be flagged as 'write-mostly'. This is valid for RAID1
502only and means that the 'md' driver will avoid reading from these
503devices if at all possible. This can be useful if mirroring over a
504slow link.
52826846 505
2ae555c3
NB
506.TP
507.BR --write-behind=
508Specify that write-behind mode should be enabled (valid for RAID1
509only). If an argument is specified, it will set the maximum number
510of outstanding writes allowed. The default value is 256.
511A write-intent bitmap is required in order to use write-behind
512mode, and write-behind is only attempted on drives marked as
513.IR write-mostly .
dd0781e5
NB
514
515.TP
516.BR --assume-clean
517Tell
518.I mdadm
47d79ef8
NB
519that the array pre-existed and is known to be clean. It can be useful
520when trying to recover from a major failure as you can be sure that no
521data will be affected unless you actually write to the array. It can
522also be used when creating a RAID1 or RAID10 if you want to avoid the
523initial resync, however this practice - while normally safe - is not
524recommended. Use this ony if you really know what you are doing.
dd0781e5 525
2ae555c3
NB
526.TP
527.BR --backup-file=
528This is needed when --grow is used to increase the number of
529raid-devices in a RAID5 if there are no spare devices available.
530See the section below on RAID_DEVICE CHANGES. The file should be
531stored on a separate device, not on the raid array being reshaped.
532
947fd4dd
NB
533.TP
534.BR -N ", " --name=
535Set a
536.B name
537for the array. This is currently only effective when creating an
538array with a version-1 superblock. The name is a simple textual
539string that can be used to identify array components when assembling.
540
dd0781e5
NB
541.TP
542.BR -R ", " --run
543Insist that
544.I mdadm
545run the array, even if some of the components
546appear to be active in another array or filesystem. Normally
547.I mdadm
548will ask for confirmation before including such components in an
549array. This option causes that question to be suppressed.
550
551.TP
552.BR -f ", " --force
553Insist that
554.I mdadm
555accept the geometry and layout specified without question. Normally
556.I mdadm
557will not allow creation of an array with only one device, and will try
558to create a raid5 array with one missing drive (as this makes the
559initial resync work faster). With
560.BR --force ,
561.I mdadm
562will not try to be so clever.
563
564.TP
565.BR -a ", " "--auto{=no,yes,md,mdp,part,p}{NN}"
48f7b27a
NB
566Instruct mdadm to create the device file if needed, possibly allocating
567an unused minor number. "md" causes a non-partitionable array
dd0781e5 568to be used. "mdp", "part" or "p" causes a partitionable array (2.6 and
2ae555c3 569later) to be used. "yes" requires the named md device to have
f9c25f1d 570a 'standard' format, and the type and minor number will be determined
48f7b27a
NB
571from this. See DEVICE NAMES below.
572
a9d69660 573The argument can also come immediately after
dd0781e5
NB
574"-a". e.g. "-ap".
575
75723446
NB
576If --auto is not given on the command line or in the config file, then
577the default will be
578.BR --auto=yes .
579
1337546d
NB
580If
581.I --scan
582is also given, then any
583.I auto=
584entries in the config file will over-ride the
585.I --auto
586instruction given on the command line.
587
dd0781e5
NB
588For partitionable arrays,
589.I mdadm
590will create the device file for the whole array and for the first 4
591partitions. A different number of partitions can be specified at the
592end of this option (e.g.
593.BR --auto=p7 ).
2ae555c3 594If the device name ends with a digit, the partition names add a 'p',
48f7b27a 595and a number, e.g. "/dev/home1p3". If there is no
dd0781e5
NB
596trailing digit, then the partition names just have a number added,
597e.g. "/dev/scratch3".
598
48f7b27a
NB
599If the md device name is in a 'standard' format as described in DEVICE
600NAMES, then it will be created, if necessary, with the appropriate
601number based on that name. If the device name is not in one of these
a9d69660 602formats, then a unused minor number will be allocated. The minor
48f7b27a
NB
603number will be considered unused if there is no active array for that
604number, and there is no entry in /dev for that number and with a
605non-standard name.
606
38098016
NB
607.TP
608.BR --symlink = no
609Normally when
610.B --auto
611causes
612.I mdadm
613to create devices in
614.B /dev/md/
615it will also create symlinks from
616.B /dev/
617with names starting with
618.B md
619or
620.BR md_ .
621Use
622.B --symlink=no
623to suppress this, or
624.B --symlink=yes
625to enforce this even if it is suppressing
626.IR mdadm.conf .
627
628
52826846
NB
629.SH For assemble:
630
cd29a5c8
NB
631.TP
632.BR -u ", " --uuid=
633uuid of array to assemble. Devices which don't have this uuid are
634excluded
635
636.TP
637.BR -m ", " --super-minor=
638Minor number of device that array was created for. Devices which
639don't have this minor number are excluded. If you create an array as
2d465520 640/dev/md1, then all superblocks will contain the minor number 1, even if
cd29a5c8
NB
641the array is later assembled as /dev/md2.
642
d013a55e
NB
643Giving the literal word "dev" for
644.B --super-minor
645will cause
646.I mdadm
647to use the minor number of the md device that is being assembled.
648e.g. when assembling
649.BR /dev/md0 ,
650.M --super-minor=dev
651will look for super blocks with a minor number of 0.
652
947fd4dd
NB
653.TP
654.BR -N ", " --name=
655Specify the name of the array to assemble. This must be the name
624920bb
NB
656that was specified when creating the array. It must either match
657then name stored in the superblock exactly, or it must match
41a3b72a 658with the current
624920bb
NB
659.I homehost
660is added to the start of the given name.
947fd4dd 661
cd29a5c8
NB
662.TP
663.BR -f ", " --force
52826846
NB
664Assemble the array even if some superblocks appear out-of-date
665
cd29a5c8
NB
666.TP
667.BR -R ", " --run
b8a8ccf9
NB
668Attempt to start the array even if fewer drives were given than were
669present last time the array was active. Normally if not all the
670expected drives are found and
cd29a5c8
NB
671.B --scan
672is not used, then the array will be assembled but not started.
673With
674.B --run
675an attempt will be made to start it anyway.
52826846 676
b8a8ccf9
NB
677.TP
678.B --no-degraded
679This is the reverse of
680.B --run
681in that it inhibits the started if array unless all expected drives
682are present. This is only needed with
683.B --scan
684and can be used if you physical connections to devices are
685not as reliable as you would like.
686
dd0781e5
NB
687.TP
688.BR -a ", " "--auto{=no,yes,md,mdp,part}"
689See this option under Create and Build options.
690
e793c2e5
NB
691.TP
692.BR -b ", " --bitmap=
2ae555c3
NB
693Specify the bitmap file that was given when the array was created. If
694an array has an
695.B internal
696bitmap, there is no need to specify this when assembling the array.
697
698.TP
699.BR --backup-file=
700If
701.B --backup-file
702was used to grow the number of raid-devices in a RAID5, and the system
703crashed during the critical section, then the same
704.B --backup-file
705must be presented to --assemble to allow possibly corrupted data to be
706restored.
e793c2e5 707
5787fa49
NB
708.TP
709.BR -U ", " --update=
710Update the superblock on each device while assembling the array. The
feb716e9
NB
711argument given to this flag can be one of
712.BR sparc2.2 ,
713.BR summaries ,
7d99579f 714.BR uuid ,
c4f12c13 715.BR name ,
0237e0ca 716.BR homehost ,
e5329c37 717.BR resync ,
586ed405 718.BR byteorder ,
bee8ec56 719.BR devicesize ,
5787fa49
NB
720or
721.BR super-minor .
722
723The
724.B sparc2.2
7d99579f 725option will adjust the superblock of an array what was created on a Sparc
5787fa49
NB
726machine running a patched 2.2 Linux kernel. This kernel got the
727alignment of part of the superblock wrong. You can use the
728.B "--examine --sparc2.2"
729option to
730.I mdadm
731to see what effect this would have.
732
733The
734.B super-minor
735option will update the
2ae555c3 736.B "preferred minor"
5787fa49 737field on each superblock to match the minor number of the array being
45c073c9
NB
738assembled.
739This can be useful if
740.B --examine
741reports a different "Preferred Minor" to
742.BR --detail .
743In some cases this update will be performed automatically
744by the kernel driver. In particular the update happens automatically
745at the first write to an array with redundancy (RAID level 1 or
746greater) on a 2.6 (or later) kernel.
5787fa49 747
7d99579f
NB
748The
749.B uuid
750option will change the uuid of the array. If a UUID is given with the
38dbfd8a 751"--uuid" option that UUID will be used as a new UUID and will
7d99579f
NB
752.B NOT
753be used to help identify the devices in the array.
754If no "--uuid" is given, a random uuid is chosen.
755
c4f12c13
NB
756The
757.B name
758option will change the
759.I name
760of the array as stored in the superblock. This is only supported for
761version-1 superblocks.
762
0237e0ca
NB
763The
764.B homehost
765option will change the
766.I homehost
767as recorded in the superblock. For version-0 superblocks, this is the
768same as updating the UUID.
769For version-1 superblocks, this involves updating the name.
770
e5329c37
NB
771The
772.B resync
773option will cause the array to be marked
774.I dirty
775meaning that any redundancy in the array (e.g. parity for raid5,
776copies for raid1) may be incorrect. This will cause the raid system
777to perform a "resync" pass to make sure that all redundant information
778is correct.
779
586ed405
NB
780The
781.B byteorder
782option allows arrays to be moved between machines with different
783byte-order.
2ae555c3 784When assembling such an array for the first time after a move, giving
586ed405
NB
785.B "--update=byteorder"
786will cause
787.I mdadm
788to expect superblocks to have their byteorder reversed, and will
789correct that order before assembling the array. This is only valid
2ae555c3 790with original (Version 0.90) superblocks.
586ed405 791
feb716e9
NB
792The
793.B summaries
794option will correct the summaries in the superblock. That is the
795counts of total, working, active, failed, and spare devices.
5787fa49 796
bee8ec56
NB
797The
798.B devicesize
799will rarely be of use. It applies to version 1.1 and 1.2 metadata
800only (where the metadata is at the start of the device) and is only
801useful when the component device has changed size (typically become
802larger). The version 1 metadata records the amount of the device that
803can be used to store data, so if a device in a version 1.1 or 1.2
804array becomes larger, the metadata will still be visible, but the
805extra space will not. In this case it might be useful to assemble the
806array with
807.BR --update=devicesize .
808This will cause
809.I mdadm
810to determine the maximum usable amount of space on each device and
811update the relevant field in the metadata.
812
41a3b72a
NB
813.TP
814.B --auto-update-homehost
815This flag is only meaning with auto-assembly (see discussion below).
816In that situation, if no suitable arrays are found for this homehost,
817.I mdadm
818will recan for any arrays at all and will assemble them and update the
819homehost to match the current host.
820
e0d19036 821.SH For Manage mode:
52826846 822
cd29a5c8
NB
823.TP
824.BR -a ", " --add
2ae555c3 825hot-add listed devices.
52826846 826
fe80f49b
NB
827.TP
828.BR --re-add
2ae555c3 829re-add a device that was recently removed from an array.
fe80f49b 830
cd29a5c8
NB
831.TP
832.BR -r ", " --remove
2d465520 833remove listed devices. They must not be active. i.e. they should
cd29a5c8 834be failed or spare devices.
52826846 835
cd29a5c8
NB
836.TP
837.BR -f ", " --fail
838mark listed devices as faulty.
52826846 839
cd29a5c8
NB
840.TP
841.BR --set-faulty
842same as --fail.
52826846 843
2ae555c3
NB
844.P
845Each of these options require that the first device list is the array
846to be acted upon and the remainder are component devices to be added,
847removed, or marked as fault. Several different operations can be
848specified for different devices, e.g.
849.in +5
850mdadm /dev/md0 --add /dev/sda1 --fail /dev/sdb1 --remove /dev/sdb1
851.in -5
852Each operation applies to all devices listed until the next
853operations.
854
855If an array is using a write-intent bitmap, then devices which have
856been removed can be re-added in a way that avoids a full
857reconstruction but instead just updated the blocks that have changed
858since the device was removed. For arrays with persistent metadata
859(superblocks) this is done automatically. For arrays created with
860.B --build
861mdadm needs to be told that this device we removed recently with
862.B --re-add.
863
864Devices can only be removed from an array if they are not in active
865use. i.e. that must be spares or failed devices. To remove an active
866device, it must be marked as
867.B faulty
868first.
869
870.SH For Misc mode:
871
872.TP
873.BR -Q ", " --query
874Examine a device to see
875(1) if it is an md device and (2) if it is a component of an md
876array.
877Information about what is discovered is presented.
878
879.TP
880.BR -D ", " --detail
881Print detail of one or more md devices.
5787fa49 882
2ae555c3
NB
883.TP
884.BR -E ", " --examine
885Print content of md superblock on device(s).
5787fa49
NB
886.TP
887.B --sparc2.2
a9d69660 888If an array was created on a 2.2 Linux kernel patched with RAID
5787fa49
NB
889support, the superblock will have been created incorrectly, or at
890least incompatibly with 2.4 and later kernels. Using the
891.B --sparc2.2
892flag with
893.B --examine
894will fix the superblock before displaying it. If this appears to do
895the right thing, then the array can be successfully assembled using
896.BR "--assemble --update=sparc2.2" .
897
2ae555c3
NB
898.TP
899.BR -X ", " --examine-bitmap
900Report information about a bitmap file.
e0d19036 901
cd29a5c8
NB
902.TP
903.BR -R ", " --run
904start a partially built array.
52826846 905
cd29a5c8
NB
906.TP
907.BR -S ", " --stop
908deactivate array, releasing all resources.
52826846 909
cd29a5c8
NB
910.TP
911.BR -o ", " --readonly
912mark array as readonly.
52826846 913
cd29a5c8
NB
914.TP
915.BR -w ", " --readwrite
916mark array as readwrite.
52826846 917
e0d19036
NB
918.TP
919.B --zero-superblock
920If the device contains a valid md superblock, the block is
921over-written with zeros. With
922--force
923the block where the superblock would be is over-written even if it
924doesn't appear to be valid.
52826846 925
feb716e9
NB
926.TP
927.BR -t ", " --test
928When used with
929.BR --detail ,
930the exit status of
931.I mdadm
932is set to reflect the status of the device.
933
e0d19036
NB
934.SH For Monitor mode:
935.TP
936.BR -m ", " --mail
937Give a mail address to send alerts to.
938
939.TP
940.BR -p ", " --program ", " --alert
941Give a program to be run whenever an event is detected.
942
773135f5
NB
943.TP
944.BR -y ", " --syslog
945Cause all events to be reported through 'syslog'. The messages have
946facility of 'daemon' and varying priorities.
947
e0d19036
NB
948.TP
949.BR -d ", " --delay
950Give a delay in seconds.
951.B mdadm
952polls the md arrays and then waits this many seconds before polling
953again. The default is 60 seconds.
954
d013a55e
NB
955.TP
956.BR -f ", " --daemonise
957Tell
958.B mdadm
959to run as a background daemon if it decides to monitor anything. This
960causes it to fork and run in the child, and to disconnect form the
961terminal. The process id of the child is written to stdout.
962This is useful with
963.B --scan
964which will only continue monitoring if a mail address or alert program
965is found in the config file.
966
b5e64645
NB
967.TP
968.BR -i ", " --pid-file
969When
970.B mdadm
971is running in daemon mode, write the pid of the daemon process to
972the specified file, instead of printing it on standard output.
973
aa88f531
NB
974.TP
975.BR -1 ", " --oneshot
976Check arrays only once. This will generate
977.B NewArray
978events and more significantly
979.B DegradedArray
a9d69660
NB
980and
981.B SparesMissing
aa88f531
NB
982events. Running
983.in +5
984.B " mdadm --monitor --scan -1"
985.in -5
986from a cron script will ensure regular notification of any degraded arrays.
987
98c6faba
NB
988.TP
989.BR -t ", " --test
990Generate a
991.B TestMessage
992alert for every array found at startup. This alert gets mailed and
993passed to the alert program. This can be used for testing that alert
a9d69660 994message do get through successfully.
98c6faba 995
e0d19036 996.SH ASSEMBLE MODE
52826846 997
cd29a5c8
NB
998.HP 12
999Usage:
9a9dab36 1000.B mdadm --assemble
5787fa49
NB
1001.I md-device options-and-component-devices...
1002.HP 12
1003Usage:
1004.B mdadm --assemble --scan
1005.I md-devices-and-options...
cd29a5c8
NB
1006.HP 12
1007Usage:
9a9dab36 1008.B mdadm --assemble --scan
cd29a5c8 1009.I options...
52826846 1010
cd29a5c8 1011.PP
52826846 1012This usage assembles one or more raid arrays from pre-existing components.
9a9dab36 1013For each array, mdadm needs to know the md device, the identity of the
e0d19036 1014array, and a number of component-devices. These can be found in a number of ways.
52826846 1015
5787fa49
NB
1016In the first usage example (without the
1017.BR --scan )
1018the first device given is the md device.
1019In the second usage example, all devices listed are treated as md
1020devices and assembly is attempted.
1021In the third (where no devices are listed) all md devices that are
1022listed in the configuration file are assembled.
52826846 1023
d013a55e
NB
1024If precisely one device is listed, but
1025.B --scan
dd0781e5 1026is not given, then
d013a55e
NB
1027.I mdadm
1028acts as though
1029.B --scan
1030was given and identify information is extracted from the configuration file.
1031
2ae555c3 1032The identity can be given with the
52826846 1033.B --uuid
cd29a5c8
NB
1034option, with the
1035.B --super-minor
5787fa49 1036option, can be found in the config file, or will be taken from the
e0d19036 1037super block on the first component-device listed on the command line.
52826846 1038
2ae555c3 1039Devices can be given on the
52826846 1040.B --assemble
5787fa49
NB
1041command line or in the config file. Only devices which have an md
1042superblock which contains the right identity will be considered for
1043any array.
52826846 1044
2ae555c3 1045The config file is only used if explicitly named with
52826846 1046.B --config
d013a55e 1047or requested with (a possibly implicit)
2ae555c3 1048.B --scan.
52826846 1049In the later case,
9a9dab36 1050.B /etc/mdadm.conf
52826846
NB
1051is used.
1052
2ae555c3 1053If
52826846 1054.B --scan
cd29a5c8
NB
1055is not given, then the config file will only be used to find the
1056identity of md arrays.
52826846 1057
2d465520 1058Normally the array will be started after it is assembled. However if
cd29a5c8 1059.B --scan
2d465520 1060is not given and insufficient drives were listed to start a complete
cd29a5c8
NB
1061(non-degraded) array, then the array is not started (to guard against
1062usage errors). To insist that the array be started in this case (as
1a7dfc35 1063may work for RAID1, 4, 5, 6, or 10), give the
cd29a5c8
NB
1064.B --run
1065flag.
52826846 1066
75723446
NB
1067If the md device does not exist, then it will be created providing the
1068intent is clear. i.e. the name must be in a standard form, or the
1069.I --auto
1070option must be given to clarify how and whether the device should be
1071created.
dd0781e5
NB
1072
1073This can be useful for handling partitioned devices (which don't have
1074a stable device number - it can change after a reboot) and when using
1075"udev" to manage your
1076.B /dev
1077tree (udev cannot handle md devices because of the unusual device
1078initialisation conventions).
1079
1080If the option to "auto" is "mdp" or "part" or (on the command line
1081only) "p", then mdadm will create a partitionable array, using the
2ae555c3 1082first free one that is not in use, and does not already have an entry
dd0781e5
NB
1083in /dev (apart from numeric /dev/md* entries).
1084
1085If the option to "auto" is "yes" or "md" or (on the command line)
1086nothing, then mdadm will create a traditional, non-partitionable md
1087array.
1088
1089It is expected that the "auto" functionality will be used to create
1090device entries with meaningful names such as "/dev/md/home" or
1091"/dev/md/root", rather than names based on the numerical array number.
1092
1093When using this option to create a partitionable array, the device
1094files for the first 4 partitions are also created. If a different
1095number is required it can be simply appended to the auto option.
1096e.g. "auto=part8". Partition names are created by appending a digit
a9d69660 1097string to the device name, with an intervening "p" if the device name
dd0781e5
NB
1098ends with a digit.
1099
1100The
1101.B --auto
1102option is also available in Build and Create modes. As those modes do
1103not use a config file, the "auto=" config option does not apply to
1104these modes.
52826846 1105
41a3b72a
NB
1106.SS Auto Assembly
1107When
1108.B --assemble
1109is used with
1110.B --scan
1111and no devices are listed,
1112.I mdadm
1113will first attempt to assemble all the arrays listed in the config
1114file.
1115
1116If a
1117.B homehost
1118has been specified (either in the config file or on the command line),
1119.I mdadm
1120will look further for possible arrays and will try to assemble
1121anything that it finds which is tagged as belonging to the given
1122homehost. This is the only situation where
1123.I mdadm
1124will assemble arrays without being given specific device name or
1125identify information for the array.
1126
1127If
1128.I mdadm
1129finds a consistent set of devices that look like they should comprise
1130an array, and if the superblock is tagged as belonging to the given
1131home host, it will automatically choose a device name and try to
1132assemble the array. If the array uses version-0.90 metadata, then the
1133.B minor
1134number as recorded in the superblock is used to create a name in
1135.B /dev/md/
1136so for example
1137.BR /dev/md/3 .
1138If the array uses version-1 metadata, then the
1139.B name
1140from the superblock is used to similarly create a name in
1141.BR /dev/md .
1142The name will have any 'host' prefix stripped first.
1143
1144If
1145.I mdadm
1146cannot find any array for the given host at all, and if
1147.B --auto-update-homehost
1148is given, then
1149.I mdadm
1150will search again for any array (not just an array created for this
1151host) and will assemble each assuming
1152.IR --update=homehost .
1153This will change the host tag in the superblock so that on the next run,
1154these arrays will be found without the second pass. The intention of
1155this feature is to support transitioning a set of md arrays to using
1156homehost tagging.
1157
1158The reason for requiring arrays to be tagged with the homehost for
1159auto assembly is to guard against problems that can arise when moving
1160devices from one host to another.
1161
cd29a5c8 1162.SH BUILD MODE
52826846 1163
cd29a5c8
NB
1164.HP 12
1165Usage:
9a9dab36 1166.B mdadm --build
cd29a5c8
NB
1167.I device
1168.BI --chunk= X
1169.BI --level= Y
b83d95f3 1170.BI --raid-devices= Z
cd29a5c8
NB
1171.I devices
1172
1173.PP
2ae555c3 1174This usage is similar to
cd29a5c8 1175.BR --create .
a9d69660 1176The difference is that it creates an array without a superblock. With
cd29a5c8 1177these arrays there is no difference between initially creating the array and
52826846
NB
1178subsequently assembling the array, except that hopefully there is useful
1179data there in the second case.
1180
a9d69660
NB
1181The level may raid0, linear, multipath, or faulty, or one of their
1182synonyms. All devices must be listed and the array will be started
1183once complete.
cd29a5c8
NB
1184
1185.SH CREATE MODE
1186
1187.HP 12
1188Usage:
9a9dab36 1189.B mdadm --create
cd29a5c8
NB
1190.I device
1191.BI --chunk= X
1192.BI --level= Y
1193.br
b83d95f3 1194.BI --raid-devices= Z
cd29a5c8
NB
1195.I devices
1196
1197.PP
1198This usage will initialise a new md array, associate some devices with
1199it, and activate the array.
1200
a9d69660 1201If the
dd0781e5
NB
1202.B --auto
1203option is given (as described in more detail in the section on
1204Assemble mode), then the md device will be created with a suitable
1205device number if necessary.
1206
cd29a5c8 1207As devices are added, they are checked to see if they contain raid
2d465520 1208superblocks or filesystems. They are also checked to see if the variance in
cd29a5c8
NB
1209device size exceeds 1%.
1210
1211If any discrepancy is found, the array will not automatically be run, though
2ae555c3 1212the presence of a
cd29a5c8
NB
1213.B --run
1214can override this caution.
1215
2d465520 1216To create a "degraded" array in which some devices are missing, simply
d013a55e 1217give the word "\fBmissing\fP"
2d465520
NB
1218in place of a device name. This will cause
1219.B mdadm
1220to leave the corresponding slot in the array empty.
1221For a RAID4 or RAID5 array at most one slot can be
98c6faba 1222"\fBmissing\fP"; for a RAID6 array at most two slots.
2d465520
NB
1223For a RAID1 array, only one real device needs to be given. All of the
1224others can be
d013a55e 1225"\fBmissing\fP".
2d465520 1226
feb716e9
NB
1227When creating a RAID5 array,
1228.B mdadm
1229will automatically create a degraded array with an extra spare drive.
1230This is because building the spare into a degraded array is in general faster than resyncing
1231the parity on a non-degraded, but not clean, array. This feature can
1232be over-ridden with the
b5e64645 1233.I --force
feb716e9
NB
1234option.
1235
41a3b72a
NB
1236When creating an array with version-1 metadata a name for the host is
1237required.
1238If this is not given with the
1239.B --name
1240option,
1241.I mdadm
1242will chose a name based on the last component of the name of the
1243device being created. So if
1244.B /dev/md3
1245is being created, then the name
1246.B 3
1247will be chosen.
1248If
1249.B /dev/md/home
1250is being created, then the name
1251.B home
1252will be used.
1253
2ae555c3 1254'''If the
cd29a5c8 1255'''.B --size
e0d19036 1256'''option is given, it is not necessary to list any component-devices in this command.
cd29a5c8 1257'''They can be added later, before a
2ae555c3
NB
1258'''.B --run.
1259'''If no
cd29a5c8
NB
1260'''.B --size
1261'''is given, the apparent size of the smallest drive given is used.
1262
1263The General Management options that are valid with --create are:
1264.TP
1265.B --run
dd0781e5 1266insist on running the array even if some devices look like they might
cd29a5c8
NB
1267be in use.
1268
1269.TP
1270.B --readonly
1271start the array readonly - not supported yet.
52826846 1272
2ae555c3 1273
e0d19036 1274.SH MANAGE MODE
cd29a5c8
NB
1275.HP 12
1276Usage:
e0d19036
NB
1277.B mdadm
1278.I device
1279.I options... devices...
cd29a5c8
NB
1280.PP
1281
e0d19036
NB
1282This usage will allow individual devices in an array to be failed,
1283removed or added. It is possible to perform multiple operations with
1284on command. For example:
1285.br
5787fa49 1286.B " mdadm /dev/md0 -f /dev/hda1 -r /dev/hda1 -a /dev/hda1"
e0d19036
NB
1287.br
1288will firstly mark
1289.B /dev/hda1
1290as faulty in
1291.B /dev/md0
1292and will then remove it from the array and finally add it back
2d465520 1293in as a spare. However only one md array can be affected by a single
2ae555c3 1294command.
e0d19036
NB
1295
1296.SH MISC MODE
1297.HP 12
1298Usage:
9a9dab36 1299.B mdadm
e0d19036
NB
1300.I options ...
1301.I devices ...
1302.PP
cd29a5c8 1303
b5e64645 1304MISC mode includes a number of distinct operations that
e0d19036
NB
1305operate on distinct devices. The operations are:
1306.TP
1307--query
1308The device is examined to see if it is
1309(1) an active md array, or
1310(2) a component of an md array.
1311The information discovered is reported.
1312
1313.TP
1314--detail
2d465520
NB
1315The device should be an active md device.
1316.B mdadm
1317will display a detailed description of the array.
cd29a5c8 1318.B --brief
2d465520
NB
1319or
1320.B --scan
1321will cause the output to be less detailed and the format to be
e0d19036 1322suitable for inclusion in
9a9dab36 1323.BR /etc/mdadm.conf .
feb716e9
NB
1324The exit status of
1325.I mdadm
1326will normally be 0 unless
1327.I mdadm
1328failed to get useful information about the device(s). However if the
1329.B --test
1330option is given, then the exit status will be:
1331.RS
1332.TP
13330
1334The array is functioning normally.
1335.TP
13361
1337The array has at least one failed device.
1338.TP
13392
1340The array has multiple failed devices and hence is unusable (raid4 or
1341raid5).
1342.TP
13434
1344There was an error while trying to get information about the device.
1345.RE
cd29a5c8 1346
e0d19036
NB
1347.TP
1348--examine
2d465520
NB
1349The device should be a component of an md array.
1350.B mdadm
1351will read the md superblock of the device and display the contents.
e0d19036
NB
1352If
1353.B --brief
1354is given, or
1355.B --scan
1356then multiple devices that are components of the one array
1357are grouped together and reported in a single entry suitable
1358for inclusion in
1359.BR /etc/mdadm.conf .
1360
2d465520 1361Having
e0d19036
NB
1362.B --scan
1363without listing any devices will cause all devices listed in the
1364config file to be examined.
1365
1366.TP
1367--stop
98c6faba
NB
1368The devices should be active md arrays which will be deactivated, as
1369long as they are not currently in use.
e0d19036
NB
1370
1371.TP
1372--run
1373This will fully activate a partially assembled md array.
1374
1375.TP
1376--readonly
1377This will mark an active array as read-only, providing that it is
1378not currently being used.
1379
1380.TP
1381--readwrite
1382This will change a
1383.B readonly
1384array back to being read/write.
1385
2d465520
NB
1386.TP
1387--scan
1388For all operations except
1389.BR --examine ,
1390.B --scan
1391will cause the operation to be applied to all arrays listed in
1392.BR /proc/mdstat .
1393For
1394.BR --examine,
1395.B --scan
1396causes all devices listed in the config file to be examined.
1397
1398
e0d19036
NB
1399.SH MONITOR MODE
1400
cd29a5c8
NB
1401.HP 12
1402Usage:
e0d19036
NB
1403.B mdadm --monitor
1404.I options... devices...
1405
cd29a5c8 1406.PP
e0d19036
NB
1407This usage causes
1408.B mdadm
1409to periodically poll a number of md arrays and to report on any events
1410noticed.
1411.B mdadm
1412will never exit once it decides that there are arrays to be checked,
1413so it should normally be run in the background.
1414
2d465520
NB
1415As well as reporting events,
1416.B mdadm
1417may move a spare drive from one array to another if they are in the
1418same
1419.B spare-group
a9d69660 1420and if the destination array has a failed drive but no spares.
2d465520 1421
e0d19036
NB
1422If any devices are listed on the command line,
1423.B mdadm
1424will only monitor those devices. Otherwise all arrays listed in the
1425configuration file will be monitored. Further, if
1426.B --scan
1427is given, then any other md devices that appear in
1428.B /proc/mdstat
1429will also be monitored.
1430
1431The result of monitoring the arrays is the generation of events.
bd526cee 1432These events are passed to a separate program (if specified) and may
2d465520 1433be mailed to a given E-mail address.
e0d19036 1434
bd526cee 1435When passing event to program, the program is run once for each event
2ae555c3 1436and is given 2 or 3 command-line arguments. The first is the
bd526cee
NB
1437name of the event (see below). The second is the name of the
1438md device which is affected, and the third is the name of a related
1439device if relevant, such as a component device that has failed.
cd29a5c8
NB
1440
1441If
1442.B --scan
e0d19036
NB
1443is given, then a program or an E-mail address must be specified on the
1444command line or in the config file. If neither are available, then
1445.B mdadm
1446will not monitor anything.
1447Without
cd29a5c8 1448.B --scan
e0d19036 1449.B mdadm
2d465520 1450will continue monitoring as long as something was found to monitor. If
e0d19036
NB
1451no program or email is given, then each event is reported to
1452.BR stdout .
cd29a5c8 1453
e0d19036
NB
1454The different events are:
1455
1456.RS 4
1457.TP
1458.B DeviceDisappeared
2d465520 1459An md array which previously was configured appears to no longer be
773135f5 1460configured. (syslog priority: Critical)
e0d19036 1461
b8f72a62
NB
1462If
1463.I mdadm
1464was told to monitor an array which is RAID0 or Linear, then it will
1465report
1466.B DeviceDisappeared
1467with the extra information
1468.BR Wrong-Level .
1469This is because RAID0 and Linear do not support the device-failed,
1470hot-spare and resync operations which are monitored.
1471
e0d19036
NB
1472.TP
1473.B RebuildStarted
773135f5 1474An md array started reconstruction. (syslog priority: Warning)
e0d19036
NB
1475
1476.TP
1477.BI Rebuild NN
1478Where
1479.I NN
1480is 20, 40, 60, or 80, this indicates that rebuild has passed that many
773135f5 1481percentage of the total. (syslog priority: Warning)
e0d19036 1482
98c6faba
NB
1483.TP
1484.B RebuildFinished
1485An md array that was rebuilding, isn't any more, either because it
773135f5 1486finished normally or was aborted. (syslog priority: Warning)
98c6faba 1487
e0d19036
NB
1488.TP
1489.B Fail
773135f5
NB
1490An active component device of an array has been marked as
1491faulty. (syslog priority: Critical)
e0d19036
NB
1492
1493.TP
1494.B FailSpare
1495A spare component device which was being rebuilt to replace a faulty
773135f5 1496device has failed. (syslog priority: Critial)
e0d19036
NB
1497
1498.TP
1499.B SpareActive
1500A spare component device which was being rebuilt to replace a faulty
98b24a2a 1501device has been successfully rebuilt and has been made active.
773135f5 1502(syslog priority: Info)
e0d19036
NB
1503
1504.TP
1505.B NewArray
1506A new md array has been detected in the
1507.B /proc/mdstat
773135f5 1508file. (syslog priority: Info)
e0d19036 1509
aa88f531
NB
1510.TP
1511.B DegradedArray
1512A newly noticed array appears to be degraded. This message is not
1513generated when
1514.I mdadm
1515notices a drive failure which causes degradation, but only when
1516.I mdadm
1517notices that an array is degraded when it first sees the array.
773135f5 1518(syslog priority: Critial)
aa88f531 1519
e0d19036
NB
1520.TP
1521.B MoveSpare
1522A spare drive has been moved from one array in a
1523.B spare-group
1524to another to allow a failed drive to be replaced.
773135f5 1525(syslog priority: Info)
e0d19036 1526
b8f72a62
NB
1527.TP
1528.B SparesMissing
1529If
1530.I mdadm
1531has been told, via the config file, that an array should have a certain
1532number of spare devices, and
1533.I mdadm
1534detects that it has fewer that this number when it first sees the
1535array, it will report a
1536.B SparesMissing
1537message.
d1732eeb 1538(syslog priority: Warning)
b8f72a62 1539
98c6faba
NB
1540.TP
1541.B TestMessage
1542An array was found at startup, and the
1543.B --test
1544flag was given.
773135f5 1545(syslog priority: Info)
e0d19036
NB
1546.RE
1547
1548Only
98c6faba
NB
1549.B Fail ,
1550.B FailSpare ,
1551.B DegradedArray ,
d1732eeb 1552.B SparesMissing ,
e0d19036 1553and
98c6faba 1554.B TestMessage
e0d19036
NB
1555cause Email to be sent. All events cause the program to be run.
1556The program is run with two or three arguments, they being the event
1557name, the array device and possibly a second device.
1558
1559Each event has an associated array device (e.g.
1560.BR /dev/md1 )
1561and possibly a second device. For
1562.BR Fail ,
1563.BR FailSpare ,
1564and
1565.B SpareActive
1566the second device is the relevant component device.
1567For
1568.B MoveSpare
1569the second device is the array that the spare was moved from.
1570
1571For
1572.B mdadm
1573to move spares from one array to another, the different arrays need to
1574be labelled with the same
1575.B spare-group
1576in the configuration file. The
1577.B spare-group
1578name can be any string. It is only necessary that different spare
2d465520 1579groups use different names.
e0d19036
NB
1580
1581When
9a9dab36 1582.B mdadm
e0d19036
NB
1583detects that an array which is in a spare group has fewer active
1584devices than necessary for the complete array, and has no spare
1585devices, it will look for another array in the same spare group that
1586has a full complement of working drive and a spare. It will then
1587attempt to remove the spare from the second drive and add it to the
1588first.
1589If the removal succeeds but the adding fails, then it is added back to
1590the original array.
1591
dd0781e5
NB
1592.SH GROW MODE
1593The GROW mode is used for changing the size or shape of an active
1594array.
1595For this to work, the kernel must support the necessary change.
2ae555c3 1596Various types of growth are being added during 2.6 development,
dd0781e5
NB
1597including restructuring a raid5 array to have more active devices.
1598
dfd4d8ee
NB
1599Currently the only support available is to
1600.IP \(bu 4
1601change the "size" attribute
1602for RAID1, RAID5 and RAID6.
1603.IP \(bu 4
2ae555c3 1604increase the "raid-disks" attribute of RAID1 and RAID5.
dfd4d8ee 1605.IP \(bu 4
2ae555c3
NB
1606add a write-intent bitmap to any array which support these bitmaps, or
1607remove a write-intent bitmap from such an array.
dfd4d8ee 1608.PP
dd0781e5 1609
2ae555c3 1610.SS SIZE CHANGES
fe80f49b 1611Normally when an array is built the "size" it taken from the smallest
dd0781e5
NB
1612of the drives. If all the small drives in an arrays are, one at a
1613time, removed and replaced with larger drives, then you could have an
1614array of large drives with only a small amount used. In this
1615situation, changing the "size" with "GROW" mode will allow the extra
1616space to start being used. If the size is increased in this way, a
1617"resync" process will start to make sure the new parts of the array
1618are synchronised.
1619
1620Note that when an array changes size, any filesystem that may be
1621stored in the array will not automatically grow to use the space. The
1622filesystem will need to be explicitly told to use the extra space.
1623
2ae555c3
NB
1624.SS RAID-DEVICES CHANGES
1625
dd0781e5
NB
1626A RAID1 array can work with any number of devices from 1 upwards
1627(though 1 is not very useful). There may be times which you want to
1628increase or decrease the number of active devices. Note that this is
1629different to hot-add or hot-remove which changes the number of
1630inactive devices.
1631
1632When reducing the number of devices in a RAID1 array, the slots which
1633are to be removed from the array must already be vacant. That is, the
1634devices that which were in those slots must be failed and removed.
1635
1636When the number of devices is increased, any hot spares that are
a9d69660 1637present will be activated immediately.
dd0781e5 1638
2ae555c3
NB
1639Increasing the number of active devices in a RAID5 is much more
1640effort. Every block in the array will need to be read and written
1641back to a new location. From 2.6.17, the Linux Kernel is able to do
1642this safely, including restart and interrupted "reshape".
1643
1644When relocating the first few stripes on a raid5, it is not possible
1645to keep the data on disk completely consistent and crash-proof. To
1646provide the required safety, mdadm disables writes to the array while
1647this "critical section" is reshaped, and takes a backup of the data
1648that is in that section. This backup is normally stored in any spare
1649devices that the array has, however it can also be stored in a
1650separate file specified with the
1651.B --backup-file
1652option. If this option is used, and the system does crash during the
1653critical period, the same file must be passed to
1654.B --assemble
1655to restore the backup and reassemble the array.
1656
1657.SS BITMAP CHANGES
1658
1659A write-intent bitmap can be added to, or removed from, an active
1660array. Either internal bitmaps, or bitmaps stored in a separate file
fe80f49b
NB
1661can be added. Note that if you add a bitmap stored in a file which is
1662in a filesystem that is on the raid array being affected, the system
1663will deadlock. The bitmap must be on a separate filesystem.
1664
2d465520
NB
1665.SH EXAMPLES
1666
5787fa49 1667.B " mdadm --query /dev/name-of-device"
2d465520 1668.br
5787fa49
NB
1669This will find out if a given device is a raid array, or is part of
1670one, and will provide brief information about the device.
2d465520 1671
5787fa49 1672.B " mdadm --assemble --scan"
2d465520 1673.br
2ae555c3 1674This will assemble and start all arrays listed in the standard config file
5787fa49 1675file. This command will typically go in a system startup file.
2d465520 1676
2d465520 1677.B " mdadm --stop --scan"
5787fa49
NB
1678.br
1679This will shut down all array that can be shut down (i.e. are not
19f8b8fc 1680currently in use). This will typically go in a system shutdown script.
2d465520 1681
5787fa49 1682.B " mdadm --follow --scan --delay=120"
2d465520 1683.br
5787fa49
NB
1684If (and only if) there is an Email address or program given in the
1685standard config file, then
1686monitor the status of all arrays listed in that file by
1687polling them ever 2 minutes.
2d465520 1688
5787fa49 1689.B " mdadm --create /dev/md0 --level=1 --raid-devices=2 /dev/hd[ac]1"
2d465520 1690.br
5787fa49 1691Create /dev/md0 as a RAID1 array consisting of /dev/hda1 and /dev/hdc1.
2d465520 1692
2d465520
NB
1693.br
1694.B " echo 'DEVICE /dev/hd*[0-9] /dev/sd*[0-9]' > mdadm.conf"
1695.br
1696.B " mdadm --detail --scan >> mdadm.conf"
1697.br
5787fa49
NB
1698This will create a prototype config file that describes currently
1699active arrays that are known to be made from partitions of IDE or SCSI drives.
2d465520
NB
1700This file should be reviewed before being used as it may
1701contain unwanted detail.
1702
2d465520
NB
1703.B " echo 'DEVICE /dev/hd[a-z] /dev/sd*[a-z]' > mdadm.conf"
1704.br
5787fa49
NB
1705.B " mdadm --examine --scan --config=mdadm.conf >> mdadm.conf"
1706.ber
2ae555c3 1707This will find what arrays could be assembled from existing IDE and
5787fa49
NB
1708SCSI whole drives (not partitions) and store the information is the
1709format of a config file.
2d465520
NB
1710This file is very likely to contain unwanted detail, particularly
1711the
1712.B devices=
5787fa49
NB
1713entries. It should be reviewed and edited before being used as an
1714actual config file.
2d465520 1715
5787fa49 1716.B " mdadm --examine --brief --scan --config=partitions"
2d465520 1717.br
5787fa49
NB
1718.B " mdadm -Ebsc partitions"
1719.br
1720Create a list of devices by reading
1721.BR /proc/partitions ,
1722scan these for RAID superblocks, and printout a brief listing of all
1723that was found.
2d465520 1724
5787fa49 1725.B " mdadm -Ac partitions -m 0 /dev/md0"
2d465520 1726.br
5787fa49
NB
1727Scan all partitions and devices listed in
1728.BR /proc/partitions
1729and assemble
1730.B /dev/md0
1731out of all such devices with a RAID superblock with a minor number of 0.
2d465520 1732
d013a55e
NB
1733.B " mdadm --monitor --scan --daemonise > /var/run/mdadm"
1734.br
1735If config file contains a mail address or alert program, run mdadm in
1736the background in monitor mode monitoring all md devices. Also write
1737pid of mdadm daemon to
1738.BR /var/run/mdadm .
1739
5787fa49 1740.B " mdadm --create --help"
2d465520 1741.br
2ae555c3 1742Provide help about the Create mode.
2d465520 1743
5787fa49
NB
1744.B " mdadm --config --help"
1745.br
1746Provide help about the format of the config file.
2d465520 1747
5787fa49
NB
1748.B " mdadm --help"
1749.br
1750Provide general help.
cd29a5c8 1751
cd29a5c8
NB
1752
1753.SH FILES
1754
1755.SS /proc/mdstat
1756
2ae555c3
NB
1757If you're using the
1758.B /proc
cd29a5c8
NB
1759filesystem,
1760.B /proc/mdstat
2d465520
NB
1761lists all active md devices with information about them.
1762.B mdadm
1763uses this to find arrays when
1764.B --scan
1765is given in Misc mode, and to monitor array reconstruction
1766on Monitor mode.
1767
cd29a5c8 1768
9a9dab36 1769.SS /etc/mdadm.conf
cd29a5c8 1770
11a3e71d
NB
1771The config file lists which devices may be scanned to see if
1772they contain MD super block, and gives identifying information
1773(e.g. UUID) about known MD arrays. See
1774.BR mdadm.conf (5)
1775for more details.
cd29a5c8 1776
48f7b27a
NB
1777.SH DEVICE NAMES
1778
1779While entries in the /dev directory can have any format you like,
1780.I mdadm
1781has an understanding of 'standard' formats which it uses to guide its
1782behaviour when creating device files via the
1783.I --auto
1784option.
1785
1786The standard names for non-partitioned arrays (the only sort of md
1787array available in 2.4 and earlier) either of
1788.IP
1789/dev/mdNN
1790.br
1791/dev/md/NN
1792.PP
1793where NN is a number.
1794The standard names for partitionable arrays (as available from 2.6
1795onwards) is one of
1796.IP
1797/dev/md/dNN
1798.br
1799/dev/md_dNN
1800.PP
1801Partition numbers should be indicated by added "pMM" to these, thus "/dev/md/d1p2".
52826846 1802
2d465520
NB
1803.SH NOTE
1804.B mdadm
1805was previously known as
1806.BR mdctl .
a9d69660
NB
1807.P
1808.B mdadm
1809is completely separate from the
1810.B raidtools
1811package, and does not use the
1812.I /etc/raidtab
1813configuration file at all.
1814
52826846 1815.SH SEE ALSO
cd29a5c8
NB
1816For information on the various levels of
1817RAID, check out:
1818
1819.IP
1820.UR http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
1821http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
1822.UE
a9d69660
NB
1823'''.PP
1824'''for new releases of the RAID driver check out:
1825'''
1826'''.IP
1827'''.UR ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
1828'''ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
1829'''.UE
1830'''.PP
1831'''or
1832'''.IP
1833'''.UR http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
1834'''http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
1835'''.UE
cd29a5c8 1836.PP
2ae555c3 1837The latest version of
a9d69660
NB
1838.I mdadm
1839should always be available from
cd29a5c8 1840.IP
a9d69660
NB
1841.UR http://www.kernel.org/pub/linux/utils/raid/mdadm/
1842http://www.kernel.org/pub/linux/utils/raid/mdadm/
cd29a5c8
NB
1843.UE
1844.PP
a9d69660
NB
1845.IR mdadm.conf (5),
1846.IR md (4).
56eb10c0 1847.PP
52826846
NB
1848.IR raidtab (5),
1849.IR raid0run (8),
1850.IR raidstop (8),
a9d69660 1851.IR mkraid (8).