]> git.ipfire.org Git - thirdparty/mdadm.git/blob - mdadm.8
Use O_EXCL when opening component devices to be assembled into an array
[thirdparty/mdadm.git] / mdadm.8
1 .\" -*- nroff -*-
2 .TH MDADM 8 "" v1.9.0
3 .SH NAME
4 mdadm \- manage MD devices
5 .I aka
6 Linux Software Raid.
7
8 .SH SYNOPSIS
9
10 .BI mdadm " [mode] <raiddevice> [options] <component-devices>"
11
12 .SH DESCRIPTION
13 RAID devices are virtual devices created from two or more
14 real block devices. This allows multiple devices (typically disk
15 drives or partitions there-of) to be combined into a single device to
16 hold (for example) a single filesystem.
17 Some RAID levels include redundancy and so can survive some degree of
18 device failure.
19
20 Linux Software RAID devices are implemented through the md (Multiple
21 Devices) device driver.
22
23 Currently, Linux supports
24 .B LINEAR
25 md devices,
26 .B RAID0
27 (striping),
28 .B RAID1
29 (mirroring),
30 .BR RAID4 ,
31 .BR RAID5 ,
32 .BR RAID6 ,
33 .BR MULTIPATH ,
34 and
35 .BR FAULTY .
36
37 .B MULTIPATH is not a Software RAID mechanism, but does involve
38 multiple devices. For
39 .B MULTIPATH
40 each device is a path to one common physical storage device.
41
42 .B FAULTY is also no true RAID, and it only involves one device. It
43 provides a layer over a true device that can be used to inject faults.
44
45 .B mdadm
46 is a program that can be used to create, manage, and monitor
47 MD devices. As
48 such it provides a similar set of functionality to the
49 .B raidtools
50 packages.
51 The key differences between
52 .B mdadm
53 and
54 .B raidtools
55 are:
56 .IP \(bu 4
57 .B mdadm
58 is a single program and not a collection of programs.
59 .IP \(bu 4
60 .B mdadm
61 can perform (almost) all of its functions without having a
62 configuration file and does not use one by default. Also
63 .B mdadm
64 helps with management of the configuration
65 file.
66 .IP \(bu 4
67 .B mdadm
68 can provide information about your arrays (through Query, Detail, and Examine)
69 that
70 .B raidtools
71 cannot.
72 .P
73 .I mdadm
74 does not use
75 .IR /etc/raidtab ,
76 the
77 .B raidtools
78 configuration file, at all. It has a different configuration file
79 with a different format and an different purpose.
80
81 .SH MODES
82 mdadm has 7 major modes of operation:
83 .TP
84 .B Assemble
85 Assemble the parts of a previously created
86 array into an active array. Components can be explicitly given
87 or can be searched for.
88 .B mdadm
89 checks that the components
90 do form a bona fide array, and can, on request, fiddle superblock
91 information so as to assemble a faulty array.
92
93 .TP
94 .B Build
95 Build a legacy array without per-device superblocks.
96
97 .TP
98 .B Create
99 Create a new array with per-device superblocks.
100 '''It can progress
101 '''in several step create-add-add-run or it can all happen with one command.
102
103 .TP
104 .B Manage
105 This is for doing things to specific components of an array such as
106 adding new spares and removing faulty devices.
107
108 .TP
109 .B Misc
110 This mode allows operations on independent devices such as examine MD
111 superblocks, erasing old superblocks and stopping active arrays.
112
113 .TP
114 .B "Follow or Monitor"
115 Monitor one or more md devices and act on any state changes. This is
116 only meaningful for raid1, 4, 5, 6 or multipath arrays as
117 only these have interesting state. raid0 or linear never have
118 missing, spare, or failed drives, so there is nothing to monitor.
119
120 .TP
121 .B "Grow"
122 Grow (or shrink) an array, or otherwise reshape it in some way.
123 Currently supported growth options including changing the active size
124 of componenet devices in RAID level 1/4/5/6 and changing the number of
125 active devices in RAID1.
126
127 .SH OPTIONS
128
129 Available options are:
130
131 .TP
132 .BR -A ", " --assemble
133 Assemble a pre-existing array.
134
135 .TP
136 .BR -B ", " --build
137 Build a legacy array without superblocks.
138
139 .TP
140 .BR -C ", " --create
141 Create a new array.
142
143 .TP
144 .BR -Q ", " --query
145 Examine a device to see
146 (1) if it is an md device and (2) if it is a component of an md
147 array.
148 Information about what is discovered is presented.
149
150 .TP
151 .BR -D ", " --detail
152 Print detail of one or more md devices.
153
154 .TP
155 .BR -E ", " --examine
156 Print content of md superblock on device(s).
157
158 .TP
159 .BR -F ", " --follow ", " --monitor
160 Select
161 .B Monitor
162 mode.
163
164 .TP
165 .BR -G ", " --grow
166 Change the size or shape of an active array.
167
168 .TP
169 .BR -h ", " --help
170 Display help message or, after above option, mode specific help
171 message.
172
173 .TP
174 .B --help-options
175 Display more detailed help about command line parsing and some commonly
176 used options.
177
178 .TP
179 .BR -V ", " --version
180 Print version information for mdadm.
181
182 .TP
183 .BR -v ", " --verbose
184 Be more verbose about what is happening.
185
186 .TP
187 .BR -b ", " --brief
188 Be less verbose. This is used with
189 .B --detail
190 and
191 .BR --examine .
192
193 .TP
194 .BR -f ", " --force
195 Be more forceful about certain operations. See the various modes of
196 the exact meaning of this option in different contexts.
197
198 .TP
199 .BR -c ", " --config=
200 Specify the config file. Default is
201 .BR /etc/mdadm.conf .
202 If the config file given is
203 .B partitions
204 then nothing will be read, but
205 .I mdadm
206 will act as though the config file contained exactly
207 .B "DEVICE partitions"
208 and will read
209 .B /proc/partitions
210 to find a list of devices to scan.
211 If the word
212 .B none
213 is given for the config file, then
214 .I mdadm
215 will act as though the config file were empty.
216
217 .TP
218 .BR -s ", " --scan
219 scan config file or
220 .B /proc/mdstat
221 for missing information.
222 In general, this option gives
223 .B mdadm
224 permission to get any missing information, like component devices,
225 array devices, array identities, and alert destination from the
226 configuration file:
227 .BR /etc/mdadm.conf .
228 One exception is MISC mode when using
229 .B --detail
230 or
231 .B --stop
232 in which case
233 .B --scan
234 says to get a list of array devices from
235 .BR /proc/mdstat .
236
237 .SH For create or build:
238
239 .TP
240 .BR -c ", " --chunk=
241 Specify chunk size of kibibytes. The default is 64.
242
243 .TP
244 .BR --rounding=
245 Specify rounding factor for linear array (==chunk size)
246
247 .TP
248 .BR -l ", " --level=
249 Set raid level. When used with
250 .IR --create ,
251 options are: linear, raid0, 0, stripe, raid1, 1, mirror, raid4, 4,
252 raid5, 5, raid6, 6, multipath, mp, fautly. Obviously some of these are synonymous.
253
254 When used with
255 .IR --build ,
256 only linear, raid0, 0, stripe are valid.
257
258 .TP
259 .BR -p ", " --parity=
260 Set raid5 parity algorithm. Options are:
261 left-asymmetric,
262 left-symmetric,
263 right-asymmetric,
264 right-symmetric,
265 la, ra, ls, rs. The default is left-symmetric.
266
267 This option is also used to set the failure mode for
268 .IR faulty .
269 The options are:
270 write-transient,
271 wt,
272 read-transient,
273 rt,
274 write-presistent,
275 wp,
276 read-persistent,
277 rp,
278 write-all,
279 read-fixable,
280 rf,
281 clear,
282 flush,
283 none.
284
285 Each mode can be followed by a number which is used as a period
286 between fault generation. Without a number, the fault is generated
287 once on the first relevant request. With a number, the fault will be
288 generated after that many request, and will continue to be generated
289 every time the period elapses.
290
291 Multiple failure modes can be current simultaneously by using the
292 "--grow" option to set subsequent failure modes.
293
294 "clear" or "none" will remove any pending or periodic failure modes,
295 and "flush" will clear any persistant faults.
296
297 To set the parity with "--grow", the level of the array ("faulty")
298 must be specified before the fault mode is specified.
299
300 .TP
301 .BR --layout=
302 same as --parity
303
304 .TP
305 .BR -n ", " --raid-devices=
306 Specify the number of active devices in the array. This, plus the
307 number of spare devices (see below) must equal the number of
308 .I component-devices
309 (including "\fBmissing\fP" devices)
310 that are listed on the command line for
311 .BR --create .
312 Setting a value of 1 is probably
313 a mistake and so requires that
314 .B --force
315 be specified first. A value of 1 will then be allowed for linear,
316 multipath, raid0 and raid1. It is never allowed for raid4 or raid5.
317 .br
318 This number can only be changed using
319 .B --grow
320 for RAID1 arrays, and only on kernels which provide necessary support.
321
322 .TP
323 .BR -x ", " --spare-devices=
324 Specify the number of spare (eXtra) devices in the initial array.
325 Spares can also be added
326 and removed later. The number of component devices listed
327 on the command line must equal the number of raid devices plus the
328 number of spare devices.
329
330
331 .TP
332 .BR -z ", " --size=
333 Amount (in Kibibytes) of space to use from each drive in RAID1/4/5/6.
334 This must be a multiple of the chunk size, and must leave about 128Kb
335 of space at the end of the drive for the RAID superblock.
336 If this is not specified
337 (as it normally is not) the smallest drive (or partition) sets the
338 size, though if there is a variance among the drives of greater than 1%, a warning is
339 issued.
340
341 This value can be set with
342 .B --grow
343 for RAID level 1/4/5/6. If the array was created with a size smaller
344 than the currently active drives, the extra space can be accessed
345 using
346 .BR --grow .
347
348 .TP
349 .BR --assume-clean
350 Tell
351 .I mdadm
352 that the array pre-existed and is known to be clean. This is only
353 really useful for Building RAID1 array. Only use this if you really
354 know what you are doing. This is currently only supported for --build.
355
356 .TP
357 .BR -R ", " --run
358 Insist that
359 .I mdadm
360 run the array, even if some of the components
361 appear to be active in another array or filesystem. Normally
362 .I mdadm
363 will ask for confirmation before including such components in an
364 array. This option causes that question to be suppressed.
365
366 .TP
367 .BR -f ", " --force
368 Insist that
369 .I mdadm
370 accept the geometry and layout specified without question. Normally
371 .I mdadm
372 will not allow creation of an array with only one device, and will try
373 to create a raid5 array with one missing drive (as this makes the
374 initial resync work faster). With
375 .BR --force ,
376 .I mdadm
377 will not try to be so clever.
378
379 .TP
380 .BR -a ", " "--auto{=no,yes,md,mdp,part,p}{NN}"
381 Instruct mdadm to create the device file if needed, possibly allocating
382 an unused minor number. "md" causes a non-partitionable array
383 to be used. "mdp", "part" or "p" causes a partitionable array (2.6 and
384 later) to be used. "yes" requires the named md device to have a
385 'standard' format, and the type and minor number will be determined
386 from this. See DEVICE NAMES below.
387
388 The argumentment can also come immediately after
389 "-a". e.g. "-ap".
390
391 For partitionable arrays,
392 .I mdadm
393 will create the device file for the whole array and for the first 4
394 partitions. A different number of partitions can be specified at the
395 end of this option (e.g.
396 .BR --auto=p7 ).
397 If the device name ends with a digit, the partition names add a'p',
398 and a number, e.g. "/dev/home1p3". If there is no
399 trailing digit, then the partition names just have a number added,
400 e.g. "/dev/scratch3".
401
402 If the md device name is in a 'standard' format as described in DEVICE
403 NAMES, then it will be created, if necessary, with the appropriate
404 number based on that name. If the device name is not in one of these
405 formats, then a unused minor number will be allocted. The minor
406 number will be considered unused if there is no active array for that
407 number, and there is no entry in /dev for that number and with a
408 non-standard name.
409
410 .SH For assemble:
411
412 .TP
413 .BR -u ", " --uuid=
414 uuid of array to assemble. Devices which don't have this uuid are
415 excluded
416
417 .TP
418 .BR -m ", " --super-minor=
419 Minor number of device that array was created for. Devices which
420 don't have this minor number are excluded. If you create an array as
421 /dev/md1, then all superblocks will contain the minor number 1, even if
422 the array is later assembled as /dev/md2.
423
424 Giving the literal word "dev" for
425 .B --super-minor
426 will cause
427 .I mdadm
428 to use the minor number of the md device that is being assembled.
429 e.g. when assembling
430 .BR /dev/md0 ,
431 .M --super-minor=dev
432 will look for super blocks with a minor number of 0.
433
434 .TP
435 .BR -f ", " --force
436 Assemble the array even if some superblocks appear out-of-date
437
438 .TP
439 .BR -R ", " --run
440 Attempt to start the array even if fewer drives were given than are
441 needed for a full array. Normally if not all drives are found and
442 .B --scan
443 is not used, then the array will be assembled but not started.
444 With
445 .B --run
446 an attempt will be made to start it anyway.
447
448 .TP
449 .BR -a ", " "--auto{=no,yes,md,mdp,part}"
450 See this option under Create and Build options.
451
452 .TP
453 .BR -U ", " --update=
454 Update the superblock on each device while assembling the array. The
455 argument given to this flag can be one of
456 .BR sparc2.2 ,
457 .BR summaries ,
458 .BR resync ,
459 or
460 .BR super-minor .
461
462 The
463 .B sparc2.2
464 option will adjust the superblock of an array what was created on a Sparc
465 machine running a patched 2.2 Linux kernel. This kernel got the
466 alignment of part of the superblock wrong. You can use the
467 .B "--examine --sparc2.2"
468 option to
469 .I mdadm
470 to see what effect this would have.
471
472 The
473 .B super-minor
474 option will update the
475 .B "prefered minor"
476 field on each superblock to match the minor number of the array being
477 assembled. This is not needed on 2.6 and later kernels as they make
478 this adjustment automatically.
479
480 The
481 .B resync
482 option will cause the array to be marked
483 .I dirty
484 meaning that any redundancy in the array (e.g. parity for raid5,
485 copies for raid1) may be incorrect. This will cause the raid system
486 to perform a "resync" pass to make sure that all redundant information
487 is correct.
488
489 The
490 .B summaries
491 option will correct the summaries in the superblock. That is the
492 counts of total, working, active, failed, and spare devices.
493
494 .SH For Manage mode:
495
496 .TP
497 .BR -a ", " --add
498 '''add, or
499 hotadd listed devices.
500
501 .TP
502 .BR -r ", " --remove
503 remove listed devices. They must not be active. i.e. they should
504 be failed or spare devices.
505
506 .TP
507 .BR -f ", " --fail
508 mark listed devices as faulty.
509
510 .TP
511 .BR --set-faulty
512 same as --fail.
513
514 .SH For Examine mode:
515
516 .TP
517 .B --sparc2.2
518 In an array was created on a 2.2 Linux kernel patched with RAID
519 support, the superblock will have been created incorrectly, or at
520 least incompatibly with 2.4 and later kernels. Using the
521 .B --sparc2.2
522 flag with
523 .B --examine
524 will fix the superblock before displaying it. If this appears to do
525 the right thing, then the array can be successfully assembled using
526 .BR "--assemble --update=sparc2.2" .
527
528 .SH For Misc mode:
529
530 .TP
531 .BR -R ", " --run
532 start a partially built array.
533
534 .TP
535 .BR -S ", " --stop
536 deactivate array, releasing all resources.
537
538 .TP
539 .BR -o ", " --readonly
540 mark array as readonly.
541
542 .TP
543 .BR -w ", " --readwrite
544 mark array as readwrite.
545
546 .TP
547 .B --zero-superblock
548 If the device contains a valid md superblock, the block is
549 over-written with zeros. With
550 --force
551 the block where the superblock would be is over-written even if it
552 doesn't appear to be valid.
553
554 .TP
555 .BR -t ", " --test
556 When used with
557 .BR --detail ,
558 the exit status of
559 .I mdadm
560 is set to reflect the status of the device.
561
562 .SH For Monitor mode:
563 .TP
564 .BR -m ", " --mail
565 Give a mail address to send alerts to.
566
567 .TP
568 .BR -p ", " --program ", " --alert
569 Give a program to be run whenever an event is detected.
570
571 .TP
572 .BR -d ", " --delay
573 Give a delay in seconds.
574 .B mdadm
575 polls the md arrays and then waits this many seconds before polling
576 again. The default is 60 seconds.
577
578 .TP
579 .BR -f ", " --daemonise
580 Tell
581 .B mdadm
582 to run as a background daemon if it decides to monitor anything. This
583 causes it to fork and run in the child, and to disconnect form the
584 terminal. The process id of the child is written to stdout.
585 This is useful with
586 .B --scan
587 which will only continue monitoring if a mail address or alert program
588 is found in the config file.
589
590 .TP
591 .BR -i ", " --pid-file
592 When
593 .B mdadm
594 is running in daemon mode, write the pid of the daemon process to
595 the specified file, instead of printing it on standard output.
596
597 .TP
598 .BR -1 ", " --oneshot
599 Check arrays only once. This will generate
600 .B NewArray
601 events and more significantly
602 .B DegradedArray
603 events. Running
604 .in +5
605 .B " mdadm --monitor --scan -1"
606 .in -5
607 from a cron script will ensure regular notification of any degraded arrays.
608
609 .TP
610 .BR -t ", " --test
611 Generate a
612 .B TestMessage
613 alert for every array found at startup. This alert gets mailed and
614 passed to the alert program. This can be used for testing that alert
615 message to get through successfully.
616
617 .SH ASSEMBLE MODE
618
619 .HP 12
620 Usage:
621 .B mdadm --assemble
622 .I md-device options-and-component-devices...
623 .HP 12
624 Usage:
625 .B mdadm --assemble --scan
626 .I md-devices-and-options...
627 .HP 12
628 Usage:
629 .B mdadm --assemble --scan
630 .I options...
631
632 .PP
633 This usage assembles one or more raid arrays from pre-existing components.
634 For each array, mdadm needs to know the md device, the identity of the
635 array, and a number of component-devices. These can be found in a number of ways.
636
637 In the first usage example (without the
638 .BR --scan )
639 the first device given is the md device.
640 In the second usage example, all devices listed are treated as md
641 devices and assembly is attempted.
642 In the third (where no devices are listed) all md devices that are
643 listed in the configuration file are assembled.
644
645 If precisely one device is listed, but
646 .B --scan
647 is not given, then
648 .I mdadm
649 acts as though
650 .B --scan
651 was given and identify information is extracted from the configuration file.
652
653 The identity can be given with the
654 .B --uuid
655 option, with the
656 .B --super-minor
657 option, can be found in the config file, or will be taken from the
658 super block on the first component-device listed on the command line.
659
660 Devices can be given on the
661 .B --assemble
662 command line or in the config file. Only devices which have an md
663 superblock which contains the right identity will be considered for
664 any array.
665
666 The config file is only used if explicitly named with
667 .B --config
668 or requested with (a possibly implicit)
669 .B --scan.
670 In the later case,
671 .B /etc/mdadm.conf
672 is used.
673
674 If
675 .B --scan
676 is not given, then the config file will only be used to find the
677 identity of md arrays.
678
679 Normally the array will be started after it is assembled. However if
680 .B --scan
681 is not given and insufficient drives were listed to start a complete
682 (non-degraded) array, then the array is not started (to guard against
683 usage errors). To insist that the array be started in this case (as
684 may work for RAID1, 4, 5 or 6), give the
685 .B --run
686 flag.
687
688 If an
689 .B auto
690 option is given, either on the command line (--auto) or in the
691 configuration file (e.g. auto=part), then
692 .I mdadm
693 will create the md device if necessary or will re-create it if it
694 doesn't look usable as it is.
695
696 This can be useful for handling partitioned devices (which don't have
697 a stable device number - it can change after a reboot) and when using
698 "udev" to manage your
699 .B /dev
700 tree (udev cannot handle md devices because of the unusual device
701 initialisation conventions).
702
703 If the option to "auto" is "mdp" or "part" or (on the command line
704 only) "p", then mdadm will create a partitionable array, using the
705 first free one that is not inuse, and does not already have an entry
706 in /dev (apart from numeric /dev/md* entries).
707
708 If the option to "auto" is "yes" or "md" or (on the command line)
709 nothing, then mdadm will create a traditional, non-partitionable md
710 array.
711
712 It is expected that the "auto" functionality will be used to create
713 device entries with meaningful names such as "/dev/md/home" or
714 "/dev/md/root", rather than names based on the numerical array number.
715
716 When using this option to create a partitionable array, the device
717 files for the first 4 partitions are also created. If a different
718 number is required it can be simply appended to the auto option.
719 e.g. "auto=part8". Partition names are created by appending a digit
720 string to the device name, with an intervening "_p" if the device name
721 ends with a digit.
722
723 The
724 .B --auto
725 option is also available in Build and Create modes. As those modes do
726 not use a config file, the "auto=" config option does not apply to
727 these modes.
728
729 .SH BUILD MODE
730
731 .HP 12
732 Usage:
733 .B mdadm --build
734 .I device
735 .BI --chunk= X
736 .BI --level= Y
737 .BI --raid-devices= Z
738 .I devices
739
740 .PP
741 This usage is similar to
742 .BR --create .
743 The difference is that it creates a legacy array without a superblock. With
744 these arrays there is no difference between initially creating the array and
745 subsequently assembling the array, except that hopefully there is useful
746 data there in the second case.
747
748 The level may only be 0, raid0, or linear. All devices must be listed
749 and the array will be started once complete.
750
751 .SH CREATE MODE
752
753 .HP 12
754 Usage:
755 .B mdadm --create
756 .I device
757 .BI --chunk= X
758 .BI --level= Y
759 .br
760 .BI --raid-devices= Z
761 .I devices
762
763 .PP
764 This usage will initialise a new md array, associate some devices with
765 it, and activate the array.
766
767 This the
768 .B --auto
769 option is given (as described in more detail in the section on
770 Assemble mode), then the md device will be created with a suitable
771 device number if necessary.
772
773 As devices are added, they are checked to see if they contain raid
774 superblocks or filesystems. They are also checked to see if the variance in
775 device size exceeds 1%.
776
777 If any discrepancy is found, the array will not automatically be run, though
778 the presence of a
779 .B --run
780 can override this caution.
781
782 To create a "degraded" array in which some devices are missing, simply
783 give the word "\fBmissing\fP"
784 in place of a device name. This will cause
785 .B mdadm
786 to leave the corresponding slot in the array empty.
787 For a RAID4 or RAID5 array at most one slot can be
788 "\fBmissing\fP"; for a RAID6 array at most two slots.
789 For a RAID1 array, only one real device needs to be given. All of the
790 others can be
791 "\fBmissing\fP".
792
793 When creating a RAID5 array,
794 .B mdadm
795 will automatically create a degraded array with an extra spare drive.
796 This is because building the spare into a degraded array is in general faster than resyncing
797 the parity on a non-degraded, but not clean, array. This feature can
798 be over-ridden with the
799 .I --force
800 option.
801
802 '''If the
803 '''.B --size
804 '''option is given, it is not necessary to list any component-devices in this command.
805 '''They can be added later, before a
806 '''.B --run.
807 '''If no
808 '''.B --size
809 '''is given, the apparent size of the smallest drive given is used.
810
811 The General Management options that are valid with --create are:
812 .TP
813 .B --run
814 insist on running the array even if some devices look like they might
815 be in use.
816
817 .TP
818 .B --readonly
819 start the array readonly - not supported yet.
820
821 .SH MANAGE MODE
822 .HP 12
823 Usage:
824 .B mdadm
825 .I device
826 .I options... devices...
827 .PP
828
829 This usage will allow individual devices in an array to be failed,
830 removed or added. It is possible to perform multiple operations with
831 on command. For example:
832 .br
833 .B " mdadm /dev/md0 -f /dev/hda1 -r /dev/hda1 -a /dev/hda1"
834 .br
835 will firstly mark
836 .B /dev/hda1
837 as faulty in
838 .B /dev/md0
839 and will then remove it from the array and finally add it back
840 in as a spare. However only one md array can be affected by a single
841 command.
842
843 .SH MISC MODE
844 .HP 12
845 Usage:
846 .B mdadm
847 .I options ...
848 .I devices ...
849 .PP
850
851 MISC mode includes a number of distinct operations that
852 operate on distinct devices. The operations are:
853 .TP
854 --query
855 The device is examined to see if it is
856 (1) an active md array, or
857 (2) a component of an md array.
858 The information discovered is reported.
859
860 .TP
861 --detail
862 The device should be an active md device.
863 .B mdadm
864 will display a detailed description of the array.
865 .B --brief
866 or
867 .B --scan
868 will cause the output to be less detailed and the format to be
869 suitable for inclusion in
870 .BR /etc/mdadm.conf .
871 The exit status of
872 .I mdadm
873 will normally be 0 unless
874 .I mdadm
875 failed to get useful information about the device(s). However if the
876 .B --test
877 option is given, then the exit status will be:
878 .RS
879 .TP
880 0
881 The array is functioning normally.
882 .TP
883 1
884 The array has at least one failed device.
885 .TP
886 2
887 The array has multiple failed devices and hence is unusable (raid4 or
888 raid5).
889 .TP
890 4
891 There was an error while trying to get information about the device.
892 .RE
893
894 .TP
895 --examine
896 The device should be a component of an md array.
897 .B mdadm
898 will read the md superblock of the device and display the contents.
899 If
900 .B --brief
901 is given, or
902 .B --scan
903 then multiple devices that are components of the one array
904 are grouped together and reported in a single entry suitable
905 for inclusion in
906 .BR /etc/mdadm.conf .
907
908 Having
909 .B --scan
910 without listing any devices will cause all devices listed in the
911 config file to be examined.
912
913 .TP
914 --stop
915 The devices should be active md arrays which will be deactivated, as
916 long as they are not currently in use.
917
918 .TP
919 --run
920 This will fully activate a partially assembled md array.
921
922 .TP
923 --readonly
924 This will mark an active array as read-only, providing that it is
925 not currently being used.
926
927 .TP
928 --readwrite
929 This will change a
930 .B readonly
931 array back to being read/write.
932
933 .TP
934 --scan
935 For all operations except
936 .BR --examine ,
937 .B --scan
938 will cause the operation to be applied to all arrays listed in
939 .BR /proc/mdstat .
940 For
941 .BR --examine,
942 .B --scan
943 causes all devices listed in the config file to be examined.
944
945
946 .SH MONITOR MODE
947
948 .HP 12
949 Usage:
950 .B mdadm --monitor
951 .I options... devices...
952
953 .PP
954 This usage causes
955 .B mdadm
956 to periodically poll a number of md arrays and to report on any events
957 noticed.
958 .B mdadm
959 will never exit once it decides that there are arrays to be checked,
960 so it should normally be run in the background.
961
962 As well as reporting events,
963 .B mdadm
964 may move a spare drive from one array to another if they are in the
965 same
966 .B spare-group
967 and if the destination array has a failed drive but not spares.
968
969 If any devices are listed on the command line,
970 .B mdadm
971 will only monitor those devices. Otherwise all arrays listed in the
972 configuration file will be monitored. Further, if
973 .B --scan
974 is given, then any other md devices that appear in
975 .B /proc/mdstat
976 will also be monitored.
977
978 The result of monitoring the arrays is the generation of events.
979 These events are passed to a separate program (if specified) and may
980 be mailed to a given E-mail address.
981
982 When passing event to program, the program is run once for each event
983 and is given 2 or 3 command-line arguements. The first is the
984 name of the event (see below). The second is the name of the
985 md device which is affected, and the third is the name of a related
986 device if relevant, such as a component device that has failed.
987
988 If
989 .B --scan
990 is given, then a program or an E-mail address must be specified on the
991 command line or in the config file. If neither are available, then
992 .B mdadm
993 will not monitor anything.
994 Without
995 .B --scan
996 .B mdadm
997 will continue monitoring as long as something was found to monitor. If
998 no program or email is given, then each event is reported to
999 .BR stdout .
1000
1001 The different events are:
1002
1003 .RS 4
1004 .TP
1005 .B DeviceDisappeared
1006 An md array which previously was configured appears to no longer be
1007 configured.
1008
1009 .TP
1010 .B RebuildStarted
1011 An md array started reconstruction.
1012
1013 .TP
1014 .BI Rebuild NN
1015 Where
1016 .I NN
1017 is 20, 40, 60, or 80, this indicates that rebuild has passed that many
1018 percentage of the total.
1019
1020 .TP
1021 .B RebuildFinished
1022 An md array that was rebuilding, isn't any more, either because it
1023 finished normally or was aborted.
1024
1025 .TP
1026 .B Fail
1027 An active component device of an array has been marked as faulty.
1028
1029 .TP
1030 .B FailSpare
1031 A spare component device which was being rebuilt to replace a faulty
1032 device has failed.
1033
1034 .TP
1035 .B SpareActive
1036 A spare component device which was being rebuilt to replace a faulty
1037 device as been successfully rebuild and has been made active.
1038
1039 .TP
1040 .B NewArray
1041 A new md array has been detected in the
1042 .B /proc/mdstat
1043 file.
1044
1045 .TP
1046 .B DegradedArray
1047 A newly noticed array appears to be degraded. This message is not
1048 generated when
1049 .I mdadm
1050 notices a drive failure which causes degradation, but only when
1051 .I mdadm
1052 notices that an array is degraded when it first sees the array.
1053
1054 .TP
1055 .B MoveSpare
1056 A spare drive has been moved from one array in a
1057 .B spare-group
1058 to another to allow a failed drive to be replaced.
1059
1060 .TP
1061 .B TestMessage
1062 An array was found at startup, and the
1063 .B --test
1064 flag was given.
1065 .RE
1066
1067 Only
1068 .B Fail ,
1069 .B FailSpare ,
1070 .B DegradedArray ,
1071 and
1072 .B TestMessage
1073 cause Email to be sent. All events cause the program to be run.
1074 The program is run with two or three arguments, they being the event
1075 name, the array device and possibly a second device.
1076
1077 Each event has an associated array device (e.g.
1078 .BR /dev/md1 )
1079 and possibly a second device. For
1080 .BR Fail ,
1081 .BR FailSpare ,
1082 and
1083 .B SpareActive
1084 the second device is the relevant component device.
1085 For
1086 .B MoveSpare
1087 the second device is the array that the spare was moved from.
1088
1089 For
1090 .B mdadm
1091 to move spares from one array to another, the different arrays need to
1092 be labelled with the same
1093 .B spare-group
1094 in the configuration file. The
1095 .B spare-group
1096 name can be any string. It is only necessary that different spare
1097 groups use different names.
1098
1099 When
1100 .B mdadm
1101 detects that an array which is in a spare group has fewer active
1102 devices than necessary for the complete array, and has no spare
1103 devices, it will look for another array in the same spare group that
1104 has a full complement of working drive and a spare. It will then
1105 attempt to remove the spare from the second drive and add it to the
1106 first.
1107 If the removal succeeds but the adding fails, then it is added back to
1108 the original array.
1109
1110 .SH GROW MODE
1111 The GROW mode is used for changing the size or shape of an active
1112 array.
1113 For this to work, the kernel must support the necessary change.
1114 Various types of growth may be added during 2.6 development, possibly
1115 including restructuring a raid5 array to have more active devices.
1116
1117 Currently the only support available is to change the "size" attribute
1118 for arrays with redundancy, and the raid-disks attribute of RAID1
1119 arrays.
1120
1121 Normally when an array is build the "size" it taken from the smallest
1122 of the drives. If all the small drives in an arrays are, one at a
1123 time, removed and replaced with larger drives, then you could have an
1124 array of large drives with only a small amount used. In this
1125 situation, changing the "size" with "GROW" mode will allow the extra
1126 space to start being used. If the size is increased in this way, a
1127 "resync" process will start to make sure the new parts of the array
1128 are synchronised.
1129
1130 Note that when an array changes size, any filesystem that may be
1131 stored in the array will not automatically grow to use the space. The
1132 filesystem will need to be explicitly told to use the extra space.
1133
1134 A RAID1 array can work with any number of devices from 1 upwards
1135 (though 1 is not very useful). There may be times which you want to
1136 increase or decrease the number of active devices. Note that this is
1137 different to hot-add or hot-remove which changes the number of
1138 inactive devices.
1139
1140 When reducing the number of devices in a RAID1 array, the slots which
1141 are to be removed from the array must already be vacant. That is, the
1142 devices that which were in those slots must be failed and removed.
1143
1144 When the number of devices is increased, any hot spares that are
1145 present may be activated immediately.
1146
1147 .SH EXAMPLES
1148
1149 .B " mdadm --query /dev/name-of-device"
1150 .br
1151 This will find out if a given device is a raid array, or is part of
1152 one, and will provide brief information about the device.
1153
1154 .B " mdadm --assemble --scan"
1155 .br
1156 This will assemble and start all arrays listed in the standard confile
1157 file. This command will typically go in a system startup file.
1158
1159 .B " mdadm --stop --scan"
1160 .br
1161 This will shut down all array that can be shut down (i.e. are not
1162 currently in use). This will typically go in a system shutdown script.
1163
1164 .B " mdadm --follow --scan --delay=120"
1165 .br
1166 If (and only if) there is an Email address or program given in the
1167 standard config file, then
1168 monitor the status of all arrays listed in that file by
1169 polling them ever 2 minutes.
1170
1171 .B " mdadm --create /dev/md0 --level=1 --raid-devices=2 /dev/hd[ac]1"
1172 .br
1173 Create /dev/md0 as a RAID1 array consisting of /dev/hda1 and /dev/hdc1.
1174
1175 .br
1176 .B " echo 'DEVICE /dev/hd*[0-9] /dev/sd*[0-9]' > mdadm.conf"
1177 .br
1178 .B " mdadm --detail --scan >> mdadm.conf"
1179 .br
1180 This will create a prototype config file that describes currently
1181 active arrays that are known to be made from partitions of IDE or SCSI drives.
1182 This file should be reviewed before being used as it may
1183 contain unwanted detail.
1184
1185 .B " echo 'DEVICE /dev/hd[a-z] /dev/sd*[a-z]' > mdadm.conf"
1186 .br
1187 .B " mdadm --examine --scan --config=mdadm.conf >> mdadm.conf"
1188 .ber
1189 This will find what arrays could be assembled from existign IDE and
1190 SCSI whole drives (not partitions) and store the information is the
1191 format of a config file.
1192 This file is very likely to contain unwanted detail, particularly
1193 the
1194 .B devices=
1195 entries. It should be reviewed and edited before being used as an
1196 actual config file.
1197
1198 .B " mdadm --examine --brief --scan --config=partitions"
1199 .br
1200 .B " mdadm -Ebsc partitions"
1201 .br
1202 Create a list of devices by reading
1203 .BR /proc/partitions ,
1204 scan these for RAID superblocks, and printout a brief listing of all
1205 that was found.
1206
1207 .B " mdadm -Ac partitions -m 0 /dev/md0"
1208 .br
1209 Scan all partitions and devices listed in
1210 .BR /proc/partitions
1211 and assemble
1212 .B /dev/md0
1213 out of all such devices with a RAID superblock with a minor number of 0.
1214
1215 .B " mdadm --monitor --scan --daemonise > /var/run/mdadm"
1216 .br
1217 If config file contains a mail address or alert program, run mdadm in
1218 the background in monitor mode monitoring all md devices. Also write
1219 pid of mdadm daemon to
1220 .BR /var/run/mdadm .
1221
1222 .B " mdadm --create --help"
1223 .br
1224 Providew help about the Create mode.
1225
1226 .B " mdadm --config --help"
1227 .br
1228 Provide help about the format of the config file.
1229
1230 .B " mdadm --help"
1231 .br
1232 Provide general help.
1233
1234
1235 .SH FILES
1236
1237 .SS /proc/mdstat
1238
1239 If you're using the
1240 .B /proc
1241 filesystem,
1242 .B /proc/mdstat
1243 lists all active md devices with information about them.
1244 .B mdadm
1245 uses this to find arrays when
1246 .B --scan
1247 is given in Misc mode, and to monitor array reconstruction
1248 on Monitor mode.
1249
1250
1251 .SS /etc/mdadm.conf
1252
1253 The config file lists which devices may be scanned to see if
1254 they contain MD super block, and gives identifying information
1255 (e.g. UUID) about known MD arrays. See
1256 .BR mdadm.conf (5)
1257 for more details.
1258
1259 .SH DEVICE NAMES
1260
1261 While entries in the /dev directory can have any format you like,
1262 .I mdadm
1263 has an understanding of 'standard' formats which it uses to guide its
1264 behaviour when creating device files via the
1265 .I --auto
1266 option.
1267
1268 The standard names for non-partitioned arrays (the only sort of md
1269 array available in 2.4 and earlier) either of
1270 .IP
1271 /dev/mdNN
1272 .br
1273 /dev/md/NN
1274 .PP
1275 where NN is a number.
1276 The standard names for partitionable arrays (as available from 2.6
1277 onwards) is one of
1278 .IP
1279 /dev/md/dNN
1280 .br
1281 /dev/md_dNN
1282 .PP
1283 Partition numbers should be indicated by added "pMM" to these, thus "/dev/md/d1p2".
1284
1285 .SH NOTE
1286 .B mdadm
1287 was previously known as
1288 .BR mdctl .
1289
1290 .SH SEE ALSO
1291 For information on the various levels of
1292 RAID, check out:
1293
1294 .IP
1295 .UR http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
1296 http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
1297 .UE
1298 .PP
1299 for new releases of the RAID driver check out:
1300
1301 .IP
1302 .UR ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
1303 ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
1304 .UE
1305 .PP
1306 or
1307 .IP
1308 .UR http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
1309 http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
1310 .URk
1311 .PP
1312 .BR mdadm.conf (5),
1313 .BR md (4).
1314 .PP
1315 .IR raidtab (5),
1316 .IR raid0run (8),
1317 .IR raidstop (8),
1318 .IR mkraid (8)