4 mdctl \- manage MD devices
10 .BI mdctl " [mode] <raiddevice> [options] <subdevices>"
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 included redundancy and so can survive some degree of
20 Linux Software RAID devices are implemented through the md (Multiple Devices) device driver.
22 Currently, Linux supports
33 Recent kernels (2002) also support a mode known as
36 does not support MULTIPATH as yet.
39 is a program that can be used to create and manage MD devices. As
40 such it provides a similar set of functionality to the
43 The key differences between
50 is a single program and not a collection of programs.
53 can perform (almost) all of its functions without having a
54 configuration file. Also mdctl helps with management of the configuration
58 can provide information about your arrays (through Detail and Examine)
64 can manage MULTIPATH devices which
69 mdctl has 7 major modes of operation:
72 Assemble the parts of a previously created
73 array into an active array. Components can be explicitly given
74 or can be searched for.
76 checks that the components
77 do form a bona fide array, and can, on request, fiddle superblock
78 information so as to assemble a faulty array.
82 Build a legacy array without per-device superblocks.
86 Create a new array with per-device superblocks.
88 '''in several step create-add-add-run or it can all happen with one command.
92 Display the details of a given md device. Details include the RAID
93 level, the number of devices, which ones are faulty (if any), and the
98 Examine a device to see if it is part of an md array, and print out
99 the details of that array.
100 This mode can also be used to examine a large number of devices and to
101 print out a summary of the arrays found in a format suitable for the
106 .B "Follow or Monitor"
107 Monitor one or more md devices and act on any state changes.
111 This is for odd bits an pieces like hotadd, hotremove, setfaulty, stop,
113 '''If an array is only partially setup by the
114 '''Create or Assemble commands, subsequent Manage commands can finish the
119 Available options are:
122 .BR -A ", " --assemble
123 Assemble an existing array.
127 Build a legacy array without superblocks.
135 Print detail of one or more md devices.
138 .BR -E ", " --examine
139 Print content of md superblock on device(s).
142 .BR -F ", " --follow ", " --monitor
149 Display help message or, after above option, mode specific help message.
152 .BR -V ", " --version
153 Print version information for mdctl.
156 .BR -v ", " --verbose
157 Be more verbose about what is happening.
161 Be less verbose. This is used with
166 .SH For create or build:
170 Specify chunk size of kibibytes. The default is 64.
174 Specify rounding factor for linear array (==chunk size)
178 Set raid level. Options are: linear, raid0, 0, stripe, raid1, 1, mirror, raid5, 4,
179 raid5, 5. Obviously some of these are synonymous.
180 Only the first 4 are valid when Building.
183 .BR -p ", " --parity=
184 Set raid5 parity algorithm. Options are:
185 {left,right}-{,a}symmetric, la, ra, ls, rs. The default is left-symmetric.
192 .BR -n ", " --raid-disks=
193 number of active devices in array.
196 .BR -x ", " --spare-disks=
197 number of spare (eXtra) disks in initial array. Spares can be added
202 Amount (in Kibibytes) of space to use from each drive in RAID1/4/5.
203 This must be a multiple of the chunk size, and must leave about 128Kb
204 of space at the end of the drive for the RAID superblock.
205 If this is not specified
206 (as it normally is not) the smallest drive (or partition) sets the
207 size, though if there is a variance among the drives of greater than 1%, a warning is
214 uuid of array to assemble. Devices which don't have this uuid are
218 .BR -m ", " --super-minor=
219 Minor number of device that array was created for. Devices which
220 don't have this minor number are excluded. If you create an array as
221 /dev/md1, then all superblock will contain the minor number 1, even if
222 the array is later assembled as /dev/md2.
225 .BR -c ", " --config=
226 config file. Default is
227 .BR /etc/mdctl.conf .
231 scan config file for missing information
235 Assemble the array even if some superblocks appear out-of-date
239 Attempt to start the array even if fewer drives were given than are
240 needed for a full array. Normally if not all drives are found and
242 is not used, then the array will be assembled but not started.
245 an attempt will be made to start it anyway.
247 .SH General management
252 hotadd listed devices.
256 remove listed devices. The must not be active. i.e. they should
257 be failed or spare devices.
261 mark listed devices as faulty.
269 start a partially built array.
273 deactivate array, releasing all resources.
276 .BR -o ", " --readonly
277 mark array as readonly.
280 .BR -w ", " --readwrite
281 mark array as readwrite.
292 .B mdctl --assemble --scan
296 This usage assembles one or more raid arrays from pre-existing components.
297 For each array, mdctl needs to know the md device, the identity of the
298 array, and a number of sub devices. These can be found in a number of ways.
300 The md device is either given before
302 or is found from the config file. In the latter case, multiple md devices
303 can be started with a single mdctl command.
305 The identity can be given with the
309 option, can be found in in the config file, or will be taken from the
310 super block on the first subdevice listed on the command line.
312 Devices can be given on the
314 command line or from the config file. Only devices which have an md
315 superblock which contains the right identity will be considered for any device.
317 The config file is only used if explicitly named with
327 is not given, then the config file will only be used to find the
328 identity of md arrays.
330 Normally the array will be started after it is assembled. However is
332 is not given and insufficient drives were lists to start a complete
333 (non-degraded) array, then the array is not started (to guard against
334 usage errors). To insist that the array be started in this case (as
335 may work for RAID1 or RAID5), give the
352 This usage is similar to
354 The difference is that it creates a legacy array without a superblock. With
355 these arrays there is no difference between initially creating the array and
356 subsequently assembling the array, except that hopefully there is useful
357 data there in the second case.
359 The level may only be 0, raid0, or linear. All devices must be listed
360 and the array will be started once complete.
375 This usage will initialise a new md array, associate some devices with
376 it, and activate the array.
378 As devices are added, they are checked to see if they contain raid
379 superblocks or filesystems. They are also check to see if the variance in
380 device size exceeds 1%.
382 If any discrepancy is found, the array will not automatically be run, though
385 can override this caution.
389 '''option is given, it is not necessary to list any subdevices in this command.
390 '''They can be added later, before a
394 '''is given, the apparent size of the smallest drive given is used.
396 The General Management options that are valid with --create are:
399 insist of running the array even if some devices look like they might
404 start the array readonly - not supported yet.
414 This usage sill print out the details of the given array including a
415 list of component devices. To determine names for the devices,
419 for device files with the right major and minor numbers.
424 prints a single line that identifies the level, number of disks, and
425 UUID of the array. This line is suitable for inclusion in
426 .BR /etc/mdctl.conf .
436 This usage will examine some block devices to see if that have a valid
437 RAID superblock on them. The information in each valid raid
438 superblock will be printed.
442 is used, the no devices should be listed, and the complete set of
443 devices identified in the configuration file are checked.
447 but this implication can be countered by specifying
453 will output an config file entry of each distinct array that was
454 found. This entry will list the UUID, the raid level, and a list of
455 the individual devices on which a superblock for that array was found.
456 This output will by syntactically suitable for inclusion in the
457 configuration file, but should
459 be used blindly. Often the array description that you want in the
460 configuration file is much less specific than that given by
462 For example, you normally do not want to list the devices,
463 particularly if they are SCSI devices.
476 gives you informations about md devices status.
477 This file is not currently used by
482 The config file is line oriented with, as usual, blank lines and lines
483 beginning with a hash (or pound sign or sharp or number sign,
484 whichever you like to call it) ignored.
485 Lines that start with a blank are treated as continuations of the
486 previous line (I don't like trailing slashes).
488 Each line contains a sequence of space-separated words, the first of
489 which identified the type of line. Keywords are case-insensitive, and
490 the first work on a line can be abbreviated to 3 letters.
492 There are two types of lines. ARRAY and DEVICE.
494 The DEVICE lines usually come first. All remaining words on the line
495 are treated as names of devices, possibly containing wild cards (see
497 These list all the devices that
500 when looking for devices with RAID superblocks.
501 Each line can contain multiple device names, and there can be multiple
502 DEVICE lines. For example:
504 DEVICE /dev/hda* /dev/hdc*
508 DEVICE /dev/discs/disc*/disc
510 The ARRAY lines identify actual arrays. The second word on the line
511 should be the name of the device where the array is normally
512 assembled, such as /dev/md1.
513 Subsequent words identify the array. If multiple identities are given,
514 then the array much match ALL identities to be considered a match.
515 Each identity word has a tag, and equals sign, and some value.
520 The value should be a 128 bit uuid in hexadecimal, with punctuation
521 interspersed if desired. This must match the uuid stored in the
525 The value is an integer which indicates the minor number that was
526 stored in the superblock when the array was created. When an array is
527 created as /dev/mdX, then the minor number X is stored.
530 The value is a comma separated list of device names. Precisely these
531 devices will be used to assemble the array. Note that the devices
532 listed there must also be listed on a DEVICE line.
535 The value is a raid level. This is normally used to identify an
536 array, but is supported so that the output of
537 .B "mdctl --examine --scan"
538 can be use directly in the configuration file.
541 The value is the number of disks in a complete active array. As with
543 this is mainly for compatibility with the output of
544 .BR "mdctl --examine --scan" .
548 Finish and document Follow mode.
551 For information on the various levels of
555 .UR http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
556 http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
559 for new releases of the RAID driver check out:
562 .UR ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
563 ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
568 .UR http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
569 http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
projects / thirdparty / mdadm.git / blob