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
35 .B MULTIPATH is not a Software RAID mechanism, but does involve
38 each device is a path to one common physical storage device.
42 is a program that can be used to create, manage, and monitor
44 such it provides a similar set of functionality to the
47 The key differences between
54 is a single program and not a collection of programs.
57 can perform (almost) all of its functions without having a
58 configuration file and does not use one by default. Also
60 helps with management of the configuration
64 can provide information about your arrays (through Query, Detail, and Examine)
74 configuration file, at all. It has a different configuration file
75 with a different format and an different purpose.
78 mdadm has 6 major modes of operation:
81 Assemble the parts of a previously created
82 array into an active array. Components can be explicitly given
83 or can be searched for.
85 checks that the components
86 do form a bona fide array, and can, on request, fiddle superblock
87 information so as to assemble a faulty array.
91 Build a legacy array without per-device superblocks.
95 Create a new array with per-device superblocks.
97 '''in several step create-add-add-run or it can all happen with one command.
101 This is for doing things to specific components of an array such as
102 adding new spares and removing faulty devices.
106 This mode allows operations on independent devices such as examine MD
107 superblocks, erasing old superblocks and stopping active arrays.
110 .B "Follow or Monitor"
111 Monitor one or more md devices and act on any state changes. This is
112 only meaningful for raid1, raid5 or multipath arrays as only these have
113 interesting state. raid0 or linear never have missing, spare, or
114 failed drives, so there is nothing to monitor.
119 Available options are:
122 .BR -A ", " --assemble
123 Assemble a pre-existing array.
127 Build a legacy array without superblocks.
135 Examine a device to see
136 (1) if it is an md device and (2) if it is a component of an md
138 Information about what is discovered is presented.
142 Print detail of one or more md devices.
145 .BR -E ", " --examine
146 Print content of md superblock on device(s).
149 .BR -F ", " --follow ", " --monitor
156 Display help message or, after above option, mode specific help message.
159 .BR -V ", " --version
160 Print version information for mdadm.
163 .BR -v ", " --verbose
164 Be more verbose about what is happening.
168 Be less verbose. This is used with
175 Be more forceful about certain operations. See the various modes of
176 the exact meaning of this option in different contexts.
179 .BR -c ", " --config=
180 Specify the config file. Default is
181 .BR /etc/mdadm.conf .
182 If the config file given is
184 then nothing will be read, but
186 will act as though the config file contained exactly
187 .B "DEVICE partitions"
190 to find a list of devices to scan.
193 is given for the config file, then
195 will act as though the config file were empty.
201 for missing information.
202 In general, this option gives
204 permission to get any missing information, like component devices,
205 array devices, array identities, and alert destination from the
207 .BR /etc/mdadm.conf .
208 One exception is MISC mode when using
214 says to get a list of array devices from
217 .SH For create or build:
221 Specify chunk size of kibibytes. The default is 64.
225 Specify rounding factor for linear array (==chunk size)
229 Set raid level. Options are: linear, raid0, 0, stripe, raid1, 1, mirror, raid5, 4,
230 raid5, 5, multipath, mp. Obviously some of these are synonymous.
231 Only the first 4 are valid when Building.
234 .BR -p ", " --parity=
235 Set raid5 parity algorithm. Options are:
240 la, ra, ls, rs. The default is left-symmetric.
247 .BR -n ", " --raid-devices=
248 Specify the number of active devices in the array. This, plus the
249 number of spare devices (see below) must equal the number of
251 (including "\fBmissing\fP" devices)
252 that are listed on the command line.
255 .BR -x ", " --spare-devices=
256 Specify the number of spare (eXtra) devices in the initial array.
257 Spares can also be added
258 and removed later. The number of component devices listed
259 on the command line must equal the number of raid devices plus the
260 number of spare devices.
265 Amount (in Kibibytes) of space to use from each drive in RAID1/4/5.
266 This must be a multiple of the chunk size, and must leave about 128Kb
267 of space at the end of the drive for the RAID superblock.
268 If this is not specified
269 (as it normally is not) the smallest drive (or partition) sets the
270 size, though if there is a variance among the drives of greater than 1%, a warning is
277 uuid of array to assemble. Devices which don't have this uuid are
281 .BR -m ", " --super-minor=
282 Minor number of device that array was created for. Devices which
283 don't have this minor number are excluded. If you create an array as
284 /dev/md1, then all superblocks will contain the minor number 1, even if
285 the array is later assembled as /dev/md2.
287 Giving the literal word "dev" for
291 to use the minor number of the md device that is being assembled.
295 will look for super blocks with a minor number of 0.
299 Assemble the array even if some superblocks appear out-of-date
303 Attempt to start the array even if fewer drives were given than are
304 needed for a full array. Normally if not all drives are found and
306 is not used, then the array will be assembled but not started.
309 an attempt will be made to start it anyway.
312 .BR -U ", " --update=
313 Update the superblock on each device while assembling the array. The
314 argument given to this flag can be either
321 option will adjust the superblock of an array what was created on a Sparc
322 machine running a patched 2.2 Linux kernel. This kernel got the
323 alignment of part of the superblock wrong. You can use the
324 .B "--examine --sparc2.2"
327 to see what effect this would have.
331 option will update the
333 field on each superblock to match the minor number of the array being
334 assembled. This is not need on 2.6 and later kernels as they make
335 this adjustment automatically.
343 hotadd listed devices.
347 remove listed devices. They must not be active. i.e. they should
348 be failed or spare devices.
352 mark listed devices as faulty.
358 .SH For Examine mode:
362 In an array was created on a 2.2 Linux kernel patched with RAID
363 support, the superblock will have been created incorrectly, or at
364 least incompatibly with 2.4 and later kernels. Using the
368 will fix the superblock before displaying it. If this appears to do
369 the right thing, then the array can be successfully assembled using
370 .BR "--assemble --update=sparc2.2" .
376 start a partially built array.
380 deactivate array, releasing all resources.
383 .BR -o ", " --readonly
384 mark array as readonly.
387 .BR -w ", " --readwrite
388 mark array as readwrite.
392 If the device contains a valid md superblock, the block is
393 over-written with zeros. With
395 the block where the superblock would be is over-written even if it
396 doesn't appear to be valid.
398 .SH For Monitor mode:
401 Give a mail address to send alerts to.
404 .BR -p ", " --program ", " --alert
405 Give a program to be run whenever an event is detected.
409 Give a delay in seconds.
411 polls the md arrays and then waits this many seconds before polling
412 again. The default is 60 seconds.
415 .BR -f ", " --daemonise
418 to run as a background daemon if it decides to monitor anything. This
419 causes it to fork and run in the child, and to disconnect form the
420 terminal. The process id of the child is written to stdout.
423 which will only continue monitoring if a mail address or alert program
424 is found in the config file.
431 .I md-device options-and-component-devices...
434 .B mdadm --assemble --scan
435 .I md-devices-and-options...
438 .B mdadm --assemble --scan
442 This usage assembles one or more raid arrays from pre-existing components.
443 For each array, mdadm needs to know the md device, the identity of the
444 array, and a number of component-devices. These can be found in a number of ways.
446 In the first usage example (without the
448 the first device given is the md device.
449 In the second usage example, all devices listed are treated as md
450 devices and assembly is attempted.
451 In the third (where no devices are listed) all md devices that are
452 listed in the configuration file are assembled.
454 If precisely one device is listed, but
460 was given and identify information is extracted from the configuration file.
462 The identity can be given with the
466 option, can be found in the config file, or will be taken from the
467 super block on the first component-device listed on the command line.
469 Devices can be given on the
471 command line or in the config file. Only devices which have an md
472 superblock which contains the right identity will be considered for
475 The config file is only used if explicitly named with
477 or requested with (a possibly implicit)
485 is not given, then the config file will only be used to find the
486 identity of md arrays.
488 Normally the array will be started after it is assembled. However if
490 is not given and insufficient drives were listed to start a complete
491 (non-degraded) array, then the array is not started (to guard against
492 usage errors). To insist that the array be started in this case (as
493 may work for RAID1 or RAID5), give the
506 .BI --raid-devices= Z
510 This usage is similar to
512 The difference is that it creates a legacy array without a superblock. With
513 these arrays there is no difference between initially creating the array and
514 subsequently assembling the array, except that hopefully there is useful
515 data there in the second case.
517 The level may only be 0, raid0, or linear. All devices must be listed
518 and the array will be started once complete.
529 .BI --raid-devices= Z
533 This usage will initialise a new md array, associate some devices with
534 it, and activate the array.
536 As devices are added, they are checked to see if they contain raid
537 superblocks or filesystems. They are also checked to see if the variance in
538 device size exceeds 1%.
540 If any discrepancy is found, the array will not automatically be run, though
543 can override this caution.
545 To create a "degraded" array in which some devices are missing, simply
546 give the word "\fBmissing\fP"
547 in place of a device name. This will cause
549 to leave the corresponding slot in the array empty.
550 For a RAID4 or RAID5 array at most one slot can be
552 For a RAID1 array, only one real device needs to be given. All of the
558 '''option is given, it is not necessary to list any component-devices in this command.
559 '''They can be added later, before a
563 '''is given, the apparent size of the smallest drive given is used.
565 The General Management options that are valid with --create are:
568 insist of running the array even if some devices look like they might
573 start the array readonly - not supported yet.
580 .I options... devices...
583 This usage will allow individual devices in an array to be failed,
584 removed or added. It is possible to perform multiple operations with
585 on command. For example:
587 .B " mdadm /dev/md0 -f /dev/hda1 -r /dev/hda1 -a /dev/hda1"
593 and will then remove it from the array and finally add it back
594 in as a spare. However only one md array can be affected by a single
605 MISC mode includes a number if distinct operations that
606 operate on distinct devices. The operations are:
609 The device is examined to see if it is
610 (1) an active md array, or
611 (2) a component of an md array.
612 The information discovered is reported.
616 The device should be an active md device.
618 will display a detailed description of the array.
622 will cause the output to be less detailed and the format to be
623 suitable for inclusion in
624 .BR /etc/mdadm.conf .
628 The device should be a component of an md array.
630 will read the md superblock of the device and display the contents.
635 then multiple devices that are components of the one array
636 are grouped together and reported in a single entry suitable
638 .BR /etc/mdadm.conf .
642 without listing any devices will cause all devices listed in the
643 config file to be examined.
647 This devices should active md arrays which will be deactivated, if
648 they are not currently in use.
652 This will fully activate a partially assembled md array.
656 This will mark an active array as read-only, providing that it is
657 not currently being used.
663 array back to being read/write.
667 For all operations except
670 will cause the operation to be applied to all arrays listed in
675 causes all devices listed in the config file to be examined.
683 .I options... devices...
688 to periodically poll a number of md arrays and to report on any events
691 will never exit once it decides that there are arrays to be checked,
692 so it should normally be run in the background.
694 As well as reporting events,
696 may move a spare drive from one array to another if they are in the
699 and if the destination array has a failed drive but not spares.
701 If any devices are listed on the command line,
703 will only monitor those devices. Otherwise all arrays listed in the
704 configuration file will be monitored. Further, if
706 is given, then any other md devices that appear in
708 will also be monitored.
710 The result of monitoring the arrays is the generation of events.
711 These events are passed to a separate program (if specified) and may
712 be mailed to a given E-mail address.
714 When passing event to program, the program is run once for each event
715 and is given 2 or 3 command-line arguements. The first is the
716 name of the event (see below). The second is the name of the
717 md device which is affected, and the third is the name of a related
718 device if relevant, such as a component device that has failed.
722 is given, then a program or an E-mail address must be specified on the
723 command line or in the config file. If neither are available, then
725 will not monitor anything.
729 will continue monitoring as long as something was found to monitor. If
730 no program or email is given, then each event is reported to
733 The different events are:
738 An md array which previously was configured appears to no longer be
743 An md array started reconstruction.
749 is 20, 40, 60, or 80, this indicates that rebuild has passed that many
750 percentage of the total.
754 An active component device of an array has been marked as faulty.
758 A spare component device which was being rebuilt to replace a faulty
763 A spare component device which was being rebuilt to replace a faulty
764 device as been successfully rebuild and has been made active.
768 A new md array has been detected in the
774 A spare drive has been moved from one array in a
776 to another to allow a failed drive to be replaced.
784 cause Email to be sent. All events cause the program to be run.
785 The program is run with two or three arguments, they being the event
786 name, the array device and possibly a second device.
788 Each event has an associated array device (e.g.
790 and possibly a second device. For
795 the second device is the relevant component device.
798 the second device is the array that the spare was moved from.
802 to move spares from one array to another, the different arrays need to
803 be labelled with the same
805 in the configuration file. The
807 name can be any string. It is only necessary that different spare
808 groups use different names.
812 detects that an array which is in a spare group has fewer active
813 devices than necessary for the complete array, and has no spare
814 devices, it will look for another array in the same spare group that
815 has a full complement of working drive and a spare. It will then
816 attempt to remove the spare from the second drive and add it to the
818 If the removal succeeds but the adding fails, then it is added back to
823 .B " mdadm --query /dev/name-of-device"
825 This will find out if a given device is a raid array, or is part of
826 one, and will provide brief information about the device.
828 .B " mdadm --assemble --scan"
830 This will assemble and start all arrays listed in the standard confile
831 file. This command will typically go in a system startup file.
833 .B " mdadm --stop --scan"
835 This will shut down all array that can be shut down (i.e. are not
836 currently in used). This will typically going in a system shutdown script.
838 .B " mdadm --follow --scan --delay=120"
840 If (and only if) there is an Email address or program given in the
841 standard config file, then
842 monitor the status of all arrays listed in that file by
843 polling them ever 2 minutes.
845 .B " mdadm --create /dev/md0 --level=1 --raid-devices=2 /dev/hd[ac]1"
847 Create /dev/md0 as a RAID1 array consisting of /dev/hda1 and /dev/hdc1.
850 .B " echo 'DEVICE /dev/hd*[0-9] /dev/sd*[0-9]' > mdadm.conf"
852 .B " mdadm --detail --scan >> mdadm.conf"
854 This will create a prototype config file that describes currently
855 active arrays that are known to be made from partitions of IDE or SCSI drives.
856 This file should be reviewed before being used as it may
857 contain unwanted detail.
859 .B " echo 'DEVICE /dev/hd[a-z] /dev/sd*[a-z]' > mdadm.conf"
861 .B " mdadm --examine --scan --config=mdadm.conf >> mdadm.conf"
863 This will find what arrays could be assembled from existign IDE and
864 SCSI whole drives (not partitions) and store the information is the
865 format of a config file.
866 This file is very likely to contain unwanted detail, particularly
869 entries. It should be reviewed and edited before being used as an
872 .B " mdadm --examine --brief --scan --config=partitions"
874 .B " mdadm -Ebsc partitions"
876 Create a list of devices by reading
877 .BR /proc/partitions ,
878 scan these for RAID superblocks, and printout a brief listing of all
881 .B " mdadm -Ac partitions -m 0 /dev/md0"
883 Scan all partitions and devices listed in
887 out of all such devices with a RAID superblock with a minor number of 0.
889 .B " mdadm --monitor --scan --daemonise > /var/run/mdadm"
891 If config file contains a mail address or alert program, run mdadm in
892 the background in monitor mode monitoring all md devices. Also write
893 pid of mdadm daemon to
896 .B " mdadm --create --help"
898 Providew help about the Create mode.
900 .B " mdadm --config --help"
902 Provide help about the format of the config file.
906 Provide general help.
917 lists all active md devices with information about them.
919 uses this to find arrays when
921 is given in Misc mode, and to monitor array reconstruction
927 The config file lists which devices may be scanned to see if
928 they contain MD super block, and gives identifying information
929 (e.g. UUID) about known MD arrays. See
936 was previously known as
940 For information on the various levels of
944 .UR http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
945 http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
948 for new releases of the RAID driver check out:
951 .UR ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
952 ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
957 .UR http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
958 http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
projects / thirdparty / mdadm.git / blob