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