4 mdadm \- manage MD devices
10 .BI mdadm " [mode] <raiddevice> [options] <component-devices>"
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
20 Linux Software RAID devices are implemented through the md (Multiple
21 Devices) device driver.
23 Currently, Linux supports
34 Recent kernels (2002) also support a mode known as
37 only provides limited support for MULTIPATH as yet.
40 is a program that can be used to create, manage, and monitor
42 such it provides a similar set of functionality to the
45 The key differences between
52 is a single program and not a collection of programs.
55 can perform (almost) all of its functions without having a
56 configuration file and does not use one by default. Also
58 helps with management of the configuration
62 can provide information about your arrays (through Query, Detail, and Examine)
72 configuration file, at all. It has a different configuration file
73 with a different format and an different purpose.
76 mdadm has 6 major modes of operation:
79 Assemble the parts of a previously created
80 array into an active array. Components can be explicitly given
81 or can be searched for.
83 checks that the components
84 do form a bona fide array, and can, on request, fiddle superblock
85 information so as to assemble a faulty array.
89 Build a legacy array without per-device superblocks.
93 Create a new array with per-device superblocks.
95 '''in several step create-add-add-run or it can all happen with one command.
99 This is for doing things to specific components of an array such as
100 adding new spares and removing faulty devices.
104 This mode allows operations on independent devices such as examine MD
105 superblocks, erasing old superblocks and stopping active arrays.
108 .B "Follow or Monitor"
109 Monitor one or more md devices and act on any state changes. This is
110 only meaningful for raid1, raid5 or multipath arrays as only these have
111 interesting state. raid0 or linear never have missing, spare, or
112 failed drives, so there is nothing to monitor.
117 Available options are:
120 .BR -A ", " --assemble
121 Assemble a pre-existing array.
125 Build a legacy array without superblocks.
133 Examine a device to see
134 (1) if it is an md device and (2) if it is a component of an md
136 Information about what is discovered is presented.
140 Print detail of one or more md devices.
143 .BR -E ", " --examine
144 Print content of md superblock on device(s).
147 .BR -F ", " --follow ", " --monitor
154 Display help message or, after above option, mode specific help message.
157 .BR -V ", " --version
158 Print version information for mdadm.
161 .BR -v ", " --verbose
162 Be more verbose about what is happening.
166 Be less verbose. This is used with
173 Be more forceful about certain operations. See the various modes of
174 the exact meaning of this option in different contexts.
177 .BR -c ", " --config=
178 Specify the config file. Default is
179 .BR /etc/mdadm.conf .
180 If the config file given is
182 then nothing will be read, but
184 will act as though the config file contained exactly
185 .B "DEVICE partitions"
188 to find a list of devices to scan.
194 for missing information.
195 In general, this option gives
197 permission to get any missing information, like component devices,
198 array devices, array identities, and alert destination from the
200 .BR /etc/mdadm.conf .
201 One exception is MISC mode when using
207 says to get a list of array devices from
210 .SH For create or build:
214 Specify chunk size of kibibytes. The default is 64.
218 Specify rounding factor for linear array (==chunk size)
222 Set raid level. Options are: linear, raid0, 0, stripe, raid1, 1, mirror, raid5, 4,
223 raid5, 5, multipath, mp. Obviously some of these are synonymous.
224 Only the first 4 are valid when Building.
227 .BR -p ", " --parity=
228 Set raid5 parity algorithm. Options are:
233 la, ra, ls, rs. The default is left-symmetric.
240 .BR -n ", " --raid-devices=
241 Specify the number of active devices in the array. This, plus the
242 number of spare devices (see below) must equal the number of
246 devices) that are listed on the command line.
249 .BR -x ", " --spare-devices=
250 Specify the number of spare (eXtra) devices in the initial array.
251 Spares can also be added
252 and removed later. The number of component devices listed
253 on the command line must equal the number of raid devices plus the
254 number of spare devices.
259 Amount (in Kibibytes) of space to use from each drive in RAID1/4/5.
260 This must be a multiple of the chunk size, and must leave about 128Kb
261 of space at the end of the drive for the RAID superblock.
262 If this is not specified
263 (as it normally is not) the smallest drive (or partition) sets the
264 size, though if there is a variance among the drives of greater than 1%, a warning is
271 uuid of array to assemble. Devices which don't have this uuid are
275 .BR -m ", " --super-minor=
276 Minor number of device that array was created for. Devices which
277 don't have this minor number are excluded. If you create an array as
278 /dev/md1, then all superblocks will contain the minor number 1, even if
279 the array is later assembled as /dev/md2.
283 Assemble the array even if some superblocks appear out-of-date
287 Attempt to start the array even if fewer drives were given than are
288 needed for a full array. Normally if not all drives are found and
290 is not used, then the array will be assembled but not started.
293 an attempt will be made to start it anyway.
296 .BR -U ", " --update=
297 Update the superblock on each device while assembling the array. The
298 argument given to this flag can be either
305 option will adjust the superblock of an array what was created on a Sparc
306 machine running a patched 2.2 Linux kernel. This kernel got the
307 alignment of part of the superblock wrong. You can use the
308 .B "--examine --sparc2.2"
311 to see what effect this would have.
315 option will update the
317 field on each superblock to match the minor number of the array being
318 assembled. This is not need on 2.6 and later kernels as they make
319 this adjustment automatically.
327 hotadd listed devices.
331 remove listed devices. They must not be active. i.e. they should
332 be failed or spare devices.
336 mark listed devices as faulty.
342 .SH For Examine mode:
346 In an array was created on a 2.2 Linux kernel patched with RAID
347 support, the superblock will have been created incorrectly, or at
348 least incompatibly with 2.4 and later kernels. Using the
352 will fix the superblock before displaying it. If this appears to do
353 the right thing, then the array can be successfully assembled using
354 .BR "--assemble --update=sparc2.2" .
360 start a partially built array.
364 deactivate array, releasing all resources.
367 .BR -o ", " --readonly
368 mark array as readonly.
371 .BR -w ", " --readwrite
372 mark array as readwrite.
376 If the device contains a valid md superblock, the block is
377 over-written with zeros. With
379 the block where the superblock would be is over-written even if it
380 doesn't appear to be valid.
382 .SH For Monitor mode:
385 Give a mail address to send alerts to.
388 .BR -p ", " --program ", " --alert
389 Give a program to be run whenever an event is detected.
393 Give a delay in seconds.
395 polls the md arrays and then waits this many seconds before polling
396 again. The default is 60 seconds.
403 .I md-device options-and-component-devices...
406 .B mdadm --assemble --scan
407 .I md-devices-and-options...
410 .B mdadm --assemble --scan
414 This usage assembles one or more raid arrays from pre-existing components.
415 For each array, mdadm needs to know the md device, the identity of the
416 array, and a number of component-devices. These can be found in a number of ways.
418 In the first usage example (without the
420 the first device given is the md device.
421 In the second usage example, all devices listed are treated as md
422 devices and assembly is attempted.
423 In the third (where no devices are listed) all md devices that are
424 listed in the configuration file are assembled.
426 The identity can be given with the
430 option, can be found in the config file, or will be taken from the
431 super block on the first component-device listed on the command line.
433 Devices can be given on the
435 command line or in the config file. Only devices which have an md
436 superblock which contains the right identity will be considered for
439 The config file is only used if explicitly named with
449 is not given, then the config file will only be used to find the
450 identity of md arrays.
452 Normally the array will be started after it is assembled. However if
454 is not given and insufficient drives were listed to start a complete
455 (non-degraded) array, then the array is not started (to guard against
456 usage errors). To insist that the array be started in this case (as
457 may work for RAID1 or RAID5), give the
470 .BI --raid-devices= Z
474 This usage is similar to
476 The difference is that it creates a legacy array without a superblock. With
477 these arrays there is no difference between initially creating the array and
478 subsequently assembling the array, except that hopefully there is useful
479 data there in the second case.
481 The level may only be 0, raid0, or linear. All devices must be listed
482 and the array will be started once complete.
493 .BI --raid-devices= Z
497 This usage will initialise a new md array, associate some devices with
498 it, and activate the array.
500 As devices are added, they are checked to see if they contain raid
501 superblocks or filesystems. They are also checked to see if the variance in
502 device size exceeds 1%.
504 If any discrepancy is found, the array will not automatically be run, though
507 can override this caution.
509 To create a "degraded" array in which some devices are missing, simply
512 in place of a device name. This will cause
514 to leave the corresponding slot in the array empty.
515 For a RAID4 or RAID5 array at most one slot can be
517 For a RAID1 array, only one real device needs to be given. All of the
523 '''option is given, it is not necessary to list any component-devices in this command.
524 '''They can be added later, before a
528 '''is given, the apparent size of the smallest drive given is used.
530 The General Management options that are valid with --create are:
533 insist of running the array even if some devices look like they might
538 start the array readonly - not supported yet.
545 .I options... devices...
548 This usage will allow individual devices in an array to be failed,
549 removed or added. It is possible to perform multiple operations with
550 on command. For example:
552 .B " mdadm /dev/md0 -f /dev/hda1 -r /dev/hda1 -a /dev/hda1"
558 and will then remove it from the array and finally add it back
559 in as a spare. However only one md array can be affected by a single
570 MISC mode includes a number if distinct operations that
571 operate on distinct devices. The operations are:
574 The device is examined to see if it is
575 (1) an active md array, or
576 (2) a component of an md array.
577 The information discovered is reported.
581 The device should be an active md device.
583 will display a detailed description of the array.
587 will cause the output to be less detailed and the format to be
588 suitable for inclusion in
589 .BR /etc/mdadm.conf .
593 The device should be a component of an md array.
595 will read the md superblock of the device and display the contents.
600 then multiple devices that are components of the one array
601 are grouped together and reported in a single entry suitable
603 .BR /etc/mdadm.conf .
607 without listing any devices will cause all devices listed in the
608 config file to be examined.
612 This devices should active md arrays which will be deactivated, if
613 they are not currently in use.
617 This will fully activate a partially assembled md array.
621 This will mark an active array as read-only, providing that it is
622 not currently being used.
628 array back to being read/write.
632 For all operations except
635 will cause the operation to be applied to all arrays listed in
640 causes all devices listed in the config file to be examined.
648 .I options... devices...
653 to periodically poll a number of md arrays and to report on any events
656 will never exit once it decides that there are arrays to be checked,
657 so it should normally be run in the background.
659 As well as reporting events,
661 may move a spare drive from one array to another if they are in the
664 and if the destination array has a failed drive but not spares.
666 If any devices are listed on the command line,
668 will only monitor those devices. Otherwise all arrays listed in the
669 configuration file will be monitored. Further, if
671 is given, then any other md devices that appear in
673 will also be monitored.
675 The result of monitoring the arrays is the generation of events.
676 These events are passed to a separate program (if specified) and may
677 be mailed to a given E-mail address.
679 When passing event to program, the program is run once for each event
680 and is given 2 or 3 command-line arguements. The first is the
681 name of the event (see below). The second is the name of the
682 md device which is affected, and the third is the name of a related
683 device if relevant, such as a component device that has failed.
687 is given, then a program or an E-mail address must be specified on the
688 command line or in the config file. If neither are available, then
690 will not monitor anything.
694 will continue monitoring as long as something was found to monitor. If
695 no program or email is given, then each event is reported to
698 The different events are:
703 An md array which previously was configured appears to no longer be
708 An md array started reconstruction.
714 is 20, 40, 60, or 80, this indicates that rebuild has passed that many
715 percentage of the total.
719 An active component device of an array has been marked as faulty.
723 A spare component device which was being rebuilt to replace a faulty
728 A spare component device which was being rebuilt to replace a faulty
729 device as been successfully rebuild and has been made active.
733 A new md array has been detected in the
739 A spare drive has been moved from one array in a
741 to another to allow a failed drive to be replaced.
749 cause Email to be sent. All events cause the program to be run.
750 The program is run with two or three arguments, they being the event
751 name, the array device and possibly a second device.
753 Each event has an associated array device (e.g.
755 and possibly a second device. For
760 the second device is the relevant component device.
763 the second device is the array that the spare was moved from.
767 to move spares from one array to another, the different arrays need to
768 be labelled with the same
770 in the configuration file. The
772 name can be any string. It is only necessary that different spare
773 groups use different names.
777 detects that an array which is in a spare group has fewer active
778 devices than necessary for the complete array, and has no spare
779 devices, it will look for another array in the same spare group that
780 has a full complement of working drive and a spare. It will then
781 attempt to remove the spare from the second drive and add it to the
783 If the removal succeeds but the adding fails, then it is added back to
788 .B " mdadm --query /dev/name-of-device"
790 This will find out if a given device is a raid array, or is part of
791 one, and will provide brief information about the device.
793 .B " mdadm --assemble --scan"
795 This will assemble and start all arrays listed in the standard confile
796 file. This command will typically go in a system startup file.
798 .B " mdadm --stop --scan"
800 This will shut down all array that can be shut down (i.e. are not
801 currently in used). This will typically going in a system shutdown script.
803 .B " mdadm --follow --scan --delay=120"
805 If (and only if) there is an Email address or program given in the
806 standard config file, then
807 monitor the status of all arrays listed in that file by
808 polling them ever 2 minutes.
810 .B " mdadm --create /dev/md0 --level=1 --raid-devices=2 /dev/hd[ac]1"
812 Create /dev/md0 as a RAID1 array consisting of /dev/hda1 and /dev/hdc1.
815 .B " echo 'DEVICE /dev/hd*[0-9] /dev/sd*[0-9]' > mdadm.conf"
817 .B " mdadm --detail --scan >> mdadm.conf"
819 This will create a prototype config file that describes currently
820 active arrays that are known to be made from partitions of IDE or SCSI drives.
821 This file should be reviewed before being used as it may
822 contain unwanted detail.
824 .B " echo 'DEVICE /dev/hd[a-z] /dev/sd*[a-z]' > mdadm.conf"
826 .B " mdadm --examine --scan --config=mdadm.conf >> mdadm.conf"
828 This will find what arrays could be assembled from existign IDE and
829 SCSI whole drives (not partitions) and store the information is the
830 format of a config file.
831 This file is very likely to contain unwanted detail, particularly
834 entries. It should be reviewed and edited before being used as an
837 .B " mdadm --examine --brief --scan --config=partitions"
839 .B " mdadm -Ebsc partitions"
841 Create a list of devices by reading
842 .BR /proc/partitions ,
843 scan these for RAID superblocks, and printout a brief listing of all
846 .B " mdadm -Ac partitions -m 0 /dev/md0"
848 Scan all partitions and devices listed in
852 out of all such devices with a RAID superblock with a minor number of 0.
854 .B " mdadm --create --help"
856 Providew help about the Create mode.
858 .B " mdadm --config --help"
860 Provide help about the format of the config file.
864 Provide general help.
875 lists all active md devices with information about them.
877 uses this to find arrays when
879 is given in Misc mode, and to monitor array reconstruction
885 The config file lists which devices may be scanned to see if
886 they contain MD super block, and gives identifying information
887 (e.g. UUID) about known MD arrays. See
894 was previously known as
898 For information on the various levels of
902 .UR http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
903 http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
906 for new releases of the RAID driver check out:
909 .UR ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
910 ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
915 .UR http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
916 http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
projects / thirdparty / mdadm.git / blob