mdadm-1.0.1
[thirdparty/mdadm.git] / mdadm.8
1 .\" -*- nroff -*-
2 .TH MDADM 8
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 .B RAID4
31 and
32 .B RAID5.
33
34 Recent kernels (2002) also support a mode known as
35 .BR MULTIPATH .
36 .B mdadm
37 only provides limited support for MULTIPATH as yet.
38
39 .B mdadm
40 is a program that can be used to create, manage, and monitor
41 MD devices.  As
42 such it provides a similar set of functionality to the
43 .B raidtools
44 packages.
45 The key differences between
46 .B mdadm
47 and
48 .B raidtools
49 are:
50 .IP \(bu 4
51 .B mdadm
52 is a single program and not a collection of programs.
53 .IP \(bu 4
54 .B mdadm
55 can perform (almost) all of its functions without having a
56 configuration file.  Also
57 .B mdadm
58 helps with management of the configuration
59 file.
60 .IP \(bu 4
61 .B mdadm
62 can provide information about your arrays (through Query, Detail, and Examine)
63 that
64 .B  raidtools
65 cannot.
66
67 .SH MODES
68 mdadm has 6 major modes of operation:
69 .TP
70 .B Assemble
71 Assemble the parts of a previously created
72 array into an active array. Components can be explicitly given
73 or can be searched for. 
74 .B mdadm
75 checks that the components
76 do form a bona fide array, and can, on request, fiddle superblock
77 information so as to assemble a faulty array.
78
79 .TP
80 .B Build
81 Build a legacy array without per-device superblocks.
82
83 .TP
84 .B Create
85 Create a new array with per-device superblocks.
86 '''It can progress
87 '''in several step create-add-add-run or it can all happen with one command.
88
89 .TP
90 .B Manage
91 This is for doing things to specific components of an array such as
92 adding new spares and removing faulty devices.
93
94 .TP
95 .B Misc
96 This mode allows operations on independent devices such as examine MD
97 superblocks, erasing old superblocks and stopping active arrays.
98
99 .TP
100 .B "Follow or Monitor"
101 Monitor one or more md devices and act on any state changes.
102
103 .SH OPTIONS
104
105 Available options are:
106
107 .TP
108 .BR -A ", " --assemble
109 Assemble a pre-existing array.
110
111 .TP
112 .BR -B ", " --build
113 Build a legacy array without superblocks.
114
115 .TP
116 .BR -C ", " --create
117 Create a new array.
118
119 .TP
120 .BR -Q ", " --query
121 Examine a device to see
122 (1) if it is an md device and (2) if it is a component of an md
123 array.
124 Information about what is discovered is presented.
125
126 .TP
127 .BR -D ", " --detail
128 Print detail of one or more md devices.
129
130 .TP
131 .BR -E ", " --examine
132 Print content of md superblock on device(s).
133
134 .TP
135 .BR -F ", " --follow ", " --monitor
136 Select
137 .B Monitor
138 mode.
139
140 .TP
141 .BR -h ", " --help
142 Display help message or, after above option, mode specific help message.
143
144 .TP
145 .BR -V ", " --version
146 Print version information for mdadm.
147
148 .TP
149 .BR -v ", " --verbose
150 Be more verbose about what is happening.
151
152 .TP
153 .BR -b ", " --brief
154 Be less verbose.  This is used with
155 .B --detail
156 and
157 .BR --examine .
158
159 .TP
160 .BR -f ", " --force
161 Be more forceful about certain operations.  See the various modes of
162 the exact meaning of this option in different contexts.
163
164 .TP
165 .BR -c ", " --config=
166 Specify the config file.  Default is
167 .BR /etc/mdadm.conf .
168
169 .TP
170 .BR -s ", " --scan
171 scan config file or
172 .B /proc/mdstat
173 for missing information.
174 In general, this option gives
175 .B mdadm
176 permission to get any missing information, like component devices,
177 array devices, array identities, and alert destination from the
178 configuration file:
179 .BR /etc/mdadm.conf .
180 One exception is MISC mode when using
181 .B --detail
182 or
183 .B --stop
184 in which case
185 .B --scan
186 says to get a list of array devices from
187 .BR /proc/mdstat .
188
189 .SH For create or build:
190
191 .TP
192 .BR -c ", " --chunk=
193 Specify chunk size of kibibytes.  The default is 64.
194
195 .TP
196 .BR --rounding=
197 Specify rounding factor for linear array (==chunk size)
198
199 .TP
200 .BR -l ", " --level=
201 Set raid level.  Options are: linear, raid0, 0, stripe, raid1, 1, mirror, raid5, 4,
202 raid5, 5, multipath, mp.  Obviously some of these are synonymous.
203 Only the first 4 are valid when Building.
204
205 .TP
206 .BR -p ", " --parity=
207 Set raid5 parity algorithm. Options are:
208 left-asymmetric,
209 left-symmetric,
210 right-asymmetric,
211 right-symmetric,
212 la, ra, ls, rs.  The default is left-symmetric.
213
214 .TP
215 .BR --layout=
216 same as --parity
217
218 .TP
219 .BR -n ", " --raid-devices=
220 number of active devices in array.
221
222 .TP
223 .BR -x ", " --spare-devices=
224 number of spare (eXtra) devices in initial array.  Spares can be added
225 and removed later.
226
227 .TP
228 .BR -z ", " --size=
229 Amount (in Kibibytes) of space to use from each drive in RAID1/4/5.
230 This must be a multiple of the chunk size, and must leave about 128Kb
231 of space at the end of the drive for the RAID superblock.
232 If this is not specified
233 (as it normally is not) the smallest drive (or partition) sets the
234 size, though if there is a variance among the drives of greater than 1%, a warning is
235 issued.
236
237 .SH For assemble:
238
239 .TP
240 .BR -u ", " --uuid=
241 uuid of array to assemble. Devices which don't have this uuid are
242 excluded
243
244 .TP
245 .BR -m ", " --super-minor=
246 Minor number of device that array was created for.  Devices which
247 don't have this minor number are excluded.  If you create an array as
248 /dev/md1, then all superblocks will contain the minor number 1, even if
249 the array is later assembled as /dev/md2.
250
251 .TP
252 .BR -f ", " --force
253 Assemble the array even if some superblocks appear out-of-date
254
255 .TP
256 .BR -R ", " --run
257 Attempt to start the array even if fewer drives were given than are
258 needed for a full array. Normally if not all drives are found and
259 .B --scan
260 is not used, then the array will be assembled but not started.
261 With
262 .B --run
263 an attempt will be made to start it anyway.
264
265 .SH For Manage mode:
266
267 .TP
268 .BR -a ", " --add
269 '''add, or
270 hotadd listed devices.
271
272 .TP
273 .BR -r ", " --remove
274 remove listed devices.  They must not be active.  i.e. they should
275 be failed or spare devices.
276
277 .TP
278 .BR -f ", " --fail
279 mark listed devices as faulty.
280
281 .TP
282 .BR --set-faulty
283 same as --fail.
284
285 .SH For Misc mode:
286
287 .TP
288 .BR -R ", " --run
289 start a partially built array.
290
291 .TP
292 .BR -S ", " --stop
293 deactivate array, releasing all resources.
294
295 .TP
296 .BR -o ", " --readonly
297 mark array as readonly.
298
299 .TP
300 .BR -w ", " --readwrite
301 mark array as readwrite.
302
303 .TP
304 .B --zero-superblock
305 If the device contains a valid md superblock, the block is
306 over-written with zeros.  With
307 --force
308 the block where the superblock would be is over-written even if it
309 doesn't appear to be valid.
310
311 .SH For Monitor mode:
312 .TP
313 .BR -m ", " --mail
314 Give a mail address to send alerts to.
315
316 .TP
317 .BR -p ", " --program ", " --alert
318 Give a program to be run whenever an event is detected.
319
320 .TP
321 .BR -d ", " --delay
322 Give a delay in seconds.
323 .B mdadm
324 polls the md arrays and then waits this many seconds before polling
325 again.  The default is 60 seconds.
326
327 .SH ASSEMBLE MODE
328
329 .HP 12
330 Usage:
331 .B mdadm --assemble
332 .I device options...
333 .HP 12
334 Usage:
335 .B mdadm --assemble --scan
336 .I  options...
337
338 .PP
339 This usage assembles one or more raid arrays from pre-existing components.
340 For each array, mdadm needs to know the md device, the identity of the
341 array, and a number of component-devices. These can be found in a number of ways.
342
343 The md device is either given before 
344 .B --scan
345 or is found from the config file. In the latter case, multiple md devices
346 can be started with a single mdadm command.
347
348 The identity can be given with the 
349 .B --uuid
350 option, with the
351 .B --super-minor
352 option, can be found in in the config file, or will be taken from the
353 super block on the first component-device listed on the command line.
354
355 Devices can be given on the 
356 .B --assemble
357 command line or from the config file. Only devices which have an md
358 superblock which contains the right identity will be considered for any device.
359
360 The config file is only used if explicitly named with 
361 .B --config
362 or requested with 
363 .B --scan. 
364 In the later case,
365 .B /etc/mdadm.conf
366 is used.
367
368 If 
369 .B --scan
370 is not given, then the config file will only be used to find the
371 identity of md arrays.
372
373 Normally the array will be started after it is assembled.  However if
374 .B --scan
375 is not given and insufficient drives were listed to start a complete
376 (non-degraded) array, then the array is not started (to guard against
377 usage errors).  To insist that the array be started in this case (as
378 may work for RAID1 or RAID5), give the
379 .B --run
380 flag.
381
382
383 .SH BUILD MODE
384
385 .HP 12
386 Usage:
387 .B mdadm --build
388 .I device
389 .BI --chunk= X
390 .BI --level= Y
391 .BI --raid-devices= Z
392 .I devices
393
394 .PP
395 This usage is similar to 
396 .BR --create .
397 The difference is that it creates a legacy array without a superblock. With
398 these arrays there is no difference between initially creating the array and
399 subsequently assembling the array, except that hopefully there is useful
400 data there in the second case.
401
402 The level may only be 0, raid0, or linear. All devices must be listed
403 and the array will be started once complete.
404
405 .SH CREATE MODE
406
407 .HP 12
408 Usage:
409 .B mdadm --create
410 .I device
411 .BI --chunk= X
412 .BI --level= Y
413 .br
414 .BI --raid-devices= Z
415 .I  devices
416
417 .PP
418 This usage will initialise a new md array, associate some devices with
419 it, and activate the array.
420
421 As devices are added, they are checked to see if they contain raid
422 superblocks or filesystems. They are also checked to see if the variance in
423 device size exceeds 1%.
424
425 If any discrepancy is found, the array will not automatically be run, though
426 the presence of a 
427 .B --run
428 can override this caution.
429
430 To create a "degraded" array in which some devices are missing, simply
431 give the word
432 .B missing
433 in place of a device name.  This will cause
434 .B mdadm
435 to leave the corresponding slot in the array empty.
436 For a RAID4 or RAID5 array at most one slot can be
437 .BR missing .
438 For a RAID1 array, only one real device needs to be given.  All of the
439 others can be
440 .BR missing .
441
442 '''If the 
443 '''.B --size
444 '''option is given, it is not necessary to list any component-devices in this command.
445 '''They can be added later, before a
446 '''.B --run. 
447 '''If no 
448 '''.B --size
449 '''is given, the apparent size of the smallest drive given is used.
450
451 The General Management options that are valid with --create are:
452 .TP
453 .B --run
454 insist of running the array even if some devices look like they might
455 be in use.
456
457 .TP
458 .B --readonly
459 start the array readonly - not supported yet.
460
461 .SH MANAGE MODE
462 .HP 12
463 Usage:
464 .B mdadm
465 .I device
466 .I options... devices...
467 .PP
468
469 This usage will allow individual devices in an array to be failed,
470 removed or added.  It is possible to perform multiple operations with
471 on command. For example:
472 .br
473 .B "  mdadm /dev/md0 -f /dev/hda1 -r /dev/hda1 /a /dev/hda1"
474 .br
475 will firstly mark
476 .B /dev/hda1
477 as faulty in
478 .B /dev/md0
479 and will then remove it from the array and finally add it back
480 in as a spare.  However only one md array can be affected by a single
481 command. 
482
483 .SH MISC MODE
484 .HP 12
485 Usage:
486 .B mdadm
487 .I options ...
488 .I devices  ...
489 .PP
490
491 MISC mode includes a number if distinct operations that
492 operate on distinct devices.  The operations are:
493 .TP
494 --query
495 The device is examined to see if it is
496 (1) an active md array, or
497 (2) a component of an md array.
498 The information discovered is reported.
499
500 .TP
501 --detail
502 The device should be an active md device.
503 .B   mdadm
504 will display a detailed description of the array.
505 .B --brief
506 or
507 .B --scan
508 will cause the output to be less detailed and the format to be
509 suitable for inclusion in
510 .BR /etc/mdadm.conf .
511
512 .TP
513 --examine
514 The device should be a component of an md array.
515 .B mdadm
516 will read the md superblock of the device and display the contents.
517 If
518 .B --brief
519 is given, or
520 .B --scan
521 then multiple devices that are components of the one array
522 are grouped together and reported in a single entry suitable
523 for inclusion in
524 .BR /etc/mdadm.conf .
525
526 Having
527 .B --scan
528 without listing any devices will cause all devices listed in the
529 config file to be examined.
530
531 .TP
532 --stop
533 This devices should active md arrays which will be deactivated, if
534 they are not currently in use.
535
536 .TP
537 --run
538 This will fully activate a partially assembled md array.
539
540 .TP
541 --readonly
542 This will mark an active array as read-only, providing that it is
543 not currently being used.
544
545 .TP
546 --readwrite
547 This will change a
548 .B readonly
549 array back to being read/write.
550
551 .TP
552 --scan
553 For all operations except
554 .BR --examine ,
555 .B --scan
556 will cause the operation to be applied to all arrays listed in
557 .BR /proc/mdstat .
558 For
559 .BR --examine,
560 .B --scan
561 causes all devices listed in the config file to be examined.
562
563
564 .SH MONITOR MODE
565
566 .HP 12
567 Usage:
568 .B mdadm --monitor
569 .I options... devices...
570
571 .PP
572 This usage causes
573 .B mdadm
574 to periodically poll a number of md arrays and to report on any events
575 noticed.
576 .B mdadm
577 will never exit once it decides that there are arrays to be checked,
578 so it should normally be run in the background.
579
580 As well as reporting events,
581 .B mdadm
582 may move a spare drive from one array to another if they are in the
583 same
584 .B spare-group
585 and if the destination array has a failed drive but not spares.
586
587 If any devices are listed on the command line,
588 .B mdadm
589 will only monitor those devices. Otherwise all arrays listed in the
590 configuration file will be monitored.  Further, if
591 .B --scan
592 is given, then any other md devices that appear in
593 .B /proc/mdstat
594 will also be monitored.
595
596 The result of monitoring the arrays is the generation of events.
597 These events are passed to a separate program (if specified) and may
598 be mailed to a given E-mail address.
599
600 When passing event to program, the program is run once for each event
601 and is given 2 or 3 command-line arguements.  The first is the
602 name of the event (see below).  The second is the name of the
603 md device which is affected, and the third is the name of a related
604 device if relevant, such as a component device that has failed.
605
606 If
607 .B --scan
608 is given, then a program or an E-mail address must be specified on the
609 command line or in the config file.  If neither are available, then
610 .B mdadm
611 will not monitor anything.
612 Without
613 .B --scan
614 .B mdadm
615 will continue monitoring as long as something was found to monitor.  If
616 no program or email is given, then each event is reported to
617 .BR stdout .
618
619 The different events are:
620
621 .RS 4
622 .TP
623 .B DeviceDisappeared
624 An md array which previously was configured appears to no longer be
625 configured.
626
627 .TP
628 .B RebuildStarted
629 An md array started reconstruction.
630
631 .TP
632 .BI Rebuild NN
633 Where
634 .I NN
635 is 20, 40, 60, or 80, this indicates that rebuild has passed that many
636 percentage of the total.
637
638 .TP
639 .B Fail
640 An active component device of an array has been marked as faulty.
641
642 .TP
643 .B FailSpare
644 A spare component device which was being rebuilt to replace a faulty
645 device has failed.
646
647 .TP
648 .B SpareActive
649 A spare component device which was being rebuilt to replace a faulty
650 device as been successfully rebuild and has been made active.
651
652 .TP
653 .B NewArray
654 A new md array has been detected in the
655 .B /proc/mdstat
656 file.
657
658 .TP
659 .B MoveSpare
660 A spare drive has been moved from one array in a
661 .B spare-group
662 to another to allow a failed drive to be replaced.
663
664 .RE
665
666 Only
667 .B Fail
668 and
669 .B FailSpare
670 cause Email to be sent.  All events cause the program to be run.
671 The program is run with two or three arguments, they being the event
672 name, the array device and possibly a second device.
673
674 Each event has an associated array device (e.g.
675 .BR /dev/md1 )
676 and possibly a second device.  For
677 .BR Fail ,
678 .BR FailSpare ,
679 and
680 .B SpareActive
681 the second device is the relevant component device.
682 For
683 .B MoveSpare
684 the second device is the array that the spare was moved from.
685
686 For
687 .B mdadm
688 to move spares from one array to another, the different arrays need to
689 be labelled with the same
690 .B spare-group
691 in the configuration file.  The
692 .B spare-group
693 name can be any string. It is only necessary that different spare
694 groups use different names.
695
696 When
697 .B mdadm
698 detects that an array which is in a spare group has fewer active
699 devices than necessary for the complete array, and has no spare
700 devices, it will look for another array in the same spare group that
701 has a full complement of working drive and a spare.  It will then
702 attempt to remove the spare from the second drive and add it to the
703 first.
704 If the removal succeeds but the adding fails, then it is added back to
705 the original array.
706
707 .SH EXAMPLES
708
709 To find out if a devices is a raid array or part of one:
710 .br
711 .B "  mdadm -Q /dev/name-of-device"
712
713 To assemble and start all array listed in the standard config file:
714 .br
715 .B "  mdadm -As"
716
717 To shut down all arrays (that are not still in used):
718 .br
719 .B "  mdadm --stop --scan"
720
721 To monitor all arrays if (and only if) an email address or program
722 was given in the config file, but poll every 2 minutes:
723 .br
724 .B "  mdadm -Fs --delay=120"
725
726 To create /dev/md0 as a RAID1 array with /dev/hda1 and /dev/hdc1:
727 .br
728 .B "  mdadm -C /dev/md0 -l1 -n2 /dev/hd[ac]1"
729
730 To create prototype a config file that describes currently
731 active arrays that are known to be made from partitions of
732 IDE or SCSI drives:
733 .br
734 .B "  echo 'DEVICE /dev/hd*[0-9] /dev/sd*[0-9]' > mdadm.conf"
735 .br
736 .B "  mdadm --detail --scan >> mdadm.conf"
737 .br
738 This file should be reviewed before being used as it may
739 contain unwanted detail.
740
741 To find out what raid arrays could be assembled from existing
742 IDE and SCSI whole drives (not partitions):
743 .br
744 .B "  echo 'DEVICE /dev/hd[a-z] /dev/sd*[a-z]' > mdadm.conf"
745 .br
746 .B "  mdadm -Es -c mdadm.conf >> mdadm.conf"
747 This file is very likely to contain unwanted detail, particularly
748 the
749 .B devices=
750 entries.
751
752 To get help about Create mode:
753 .br
754 .B "  mdadm --create --help"
755
756 To get help about the format of the config file:
757 .br
758 .B "  mdadm --config --help"
759
760 To get general help:
761 .br
762 .B "  mdadm --help"
763
764
765
766
767 .SH FILES
768
769 .SS /proc/mdstat
770
771 If you're using the 
772 .B /proc 
773 filesystem,
774 .B /proc/mdstat
775 lists all active md devices with information about them.
776 .B mdadm
777 uses this to find arrays when
778 .B --scan
779 is given in Misc mode, and to monitor array reconstruction
780 on Monitor mode.
781
782
783 .SS /etc/mdadm.conf
784
785 The config file lists which devices may be scanned to see if
786 they contain MD super block, and gives identifying information
787 (e.g. UUID) about known MD arrays.  See
788 .BR mdadm.conf (5)
789 for more details.
790
791
792 .SH NOTE
793 .B mdadm
794 was previously known as
795 .BR mdctl .
796  
797 .SH SEE ALSO
798 For information on the various levels of
799 RAID, check out:
800
801 .IP
802 .UR   http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
803 http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
804 .UE
805 .PP
806 for new releases of the RAID driver check out:
807
808 .IP
809 .UR  ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
810 ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
811 .UE
812 .PP
813 or
814 .IP
815 .UR http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
816 http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
817 .URk
818 .PP
819 .BR mdadm.conf (5),
820 .BR md (4).
821 .PP
822 .IR raidtab (5),
823 .IR raid0run (8),
824 .IR raidstop (8),
825 .IR mkraid (8)