diff options
Diffstat (limited to 'mdadm.8')
| -rw-r--r-- | mdadm.8 | 575 |
1 files changed, 575 insertions, 0 deletions
@@ -0,0 +1,575 @@ +.\" -*- nroff -*- +.TH mdadm 8 +.SH NAME +mdadm \- manage MD devices +.I aka +Linux Software Raid. + +.SH SYNOPSIS + +.BI mdadm " [mode] <raiddevice> [options] <subdevices>" + +.SH DESCRIPTION +RAID devices are virtual devices created from two or more +real block devices. This allows multiple devices (typically disk +drives or partitions there-of) to be combined into a single device to +hold (for example) a single filesystem. +Some RAID levels included redundancy and so can survive some degree of +device failure. + +Linux Software RAID devices are implemented through the md (Multiple Devices) device driver. + +Currently, Linux supports +.B LINEAR +md devices, +.B RAID0 +(striping), +.B RAID1 +(mirroring), +.B RAID4 +and +.B RAID5. + +Recent kernels (2002) also support a mode known as +.BR MULTIPATH . +.B mdadm +does not support MULTIPATH as yet. + +.B mdadm +is a program that can be used to create and manage MD devices. As +such it provides a similar set of functionality to the +.B raidtools +packages. +The key differences between +.B mdadm +and +.B raidtools +are: +.IP \(bu 4 +.B mdadm +is a single program and not a collection of programs. +.IP \(bu 4 +.B mdadm +can perform (almost) all of its functions without having a +configuration file. Also mdadm helps with management of the configuration +file. +.IP \(bu 4 +.B mdadm +can provide information about your arrays (through Detail and Examine) +that +.B raidtools +cannot. +.IP \(bu 4 +.B raidtools +can manage MULTIPATH devices which +.B mdadm +cannot yet manage. + +.SH MODES +mdadm has 7 major modes of operation: +.TP +.B Assemble +Assemble the parts of a previously created +array into an active array. Components can be explicitly given +or can be searched for. +.B mdadm +checks that the components +do form a bona fide array, and can, on request, fiddle superblock +information so as to assemble a faulty array. + +.TP +.B Build +Build a legacy array without per-device superblocks. + +.TP +.B Create +Create a new array with per-device superblocks. +'''It can progress +'''in several step create-add-add-run or it can all happen with one command. + +.TP +.B Detail +Display the details of a given md device. Details include the RAID +level, the number of devices, which ones are faulty (if any), and the +array UUID. + +.TP +.B Examine +Examine a device to see if it is part of an md array, and print out +the details of that array. +This mode can also be used to examine a large number of devices and to +print out a summary of the arrays found in a format suitable for the +.B mdadm.conf +configuration file. + +.TP +.B "Follow or Monitor" +Monitor one or more md devices and act on any state changes. + +.TP +.B Manage +This is for odd bits an pieces like hotadd, hotremove, setfaulty, stop, +readonly, readwrite. +'''If an array is only partially setup by the +'''Create or Assemble commands, subsequent Manage commands can finish the +'''job. + +.SH OPTIONS + +Available options are: + +.TP +.BR -A ", " --assemble +Assemble an existing array. + +.TP +.BR -B ", " --build +Build a legacy array without superblocks. + +.TP +.BR -C ", " --create +Create a new array. + +.TP +.BR -D ", " --detail +Print detail of one or more md devices. + +.TP +.BR -E ", " --examine +Print content of md superblock on device(s). + +.TP +.BR -F ", " --follow ", " --monitor +Select +.B Monitor +mode. + +.TP +.BR -h ", " --help +Display help message or, after above option, mode specific help message. + +.TP +.BR -V ", " --version +Print version information for mdadm. + +.TP +.BR -v ", " --verbose +Be more verbose about what is happening. + +.TP +.BR -b ", " --brief +Be less verbose. This is used with +.B --detail +and +.BR --examine . + +.SH For create or build: + +.TP +.BR -c ", " --chunk= +Specify chunk size of kibibytes. The default is 64. + +.TP +.BR --rounding= +Specify rounding factor for linear array (==chunk size) + +.TP +.BR -l ", " --level= +Set raid level. Options are: linear, raid0, 0, stripe, raid1, 1, mirror, raid5, 4, +raid5, 5. Obviously some of these are synonymous. +Only the first 4 are valid when Building. + +.TP +.BR -p ", " --parity= +Set raid5 parity algorithm. Options are: +{left,right}-{,a}symmetric, la, ra, ls, rs. The default is left-symmetric. + +.TP +.BR --layout= +same as --parity + +.TP +.BR -n ", " --raid-disks= +number of active devices in array. + +.TP +.BR -x ", " --spare-disks= +number of spare (eXtra) disks in initial array. Spares can be added +and removed later. + +.TP +.BR -z ", " --size= +Amount (in Kibibytes) of space to use from each drive in RAID1/4/5. +This must be a multiple of the chunk size, and must leave about 128Kb +of space at the end of the drive for the RAID superblock. +If this is not specified +(as it normally is not) the smallest drive (or partition) sets the +size, though if there is a variance among the drives of greater than 1%, a warning is +issued. + +.SH For assemble: + +.TP +.BR -u ", " --uuid= +uuid of array to assemble. Devices which don't have this uuid are +excluded + +.TP +.BR -m ", " --super-minor= +Minor number of device that array was created for. Devices which +don't have this minor number are excluded. If you create an array as +/dev/md1, then all superblock will contain the minor number 1, even if +the array is later assembled as /dev/md2. + +.TP +.BR -c ", " --config= +config file. Default is +.BR /etc/mdadm.conf . + +.TP +.BR -s ", " --scan +scan config file for missing information + +.TP +.BR -f ", " --force +Assemble the array even if some superblocks appear out-of-date + +.TP +.BR -R ", " --run +Attempt to start the array even if fewer drives were given than are +needed for a full array. Normally if not all drives are found and +.B --scan +is not used, then the array will be assembled but not started. +With +.B --run +an attempt will be made to start it anyway. + +.SH General management + +.TP +.BR -a ", " --add +'''add, or +hotadd listed devices. + +.TP +.BR -r ", " --remove +remove listed devices. The must not be active. i.e. they should +be failed or spare devices. + +.TP +.BR -f ", " --fail +mark listed devices as faulty. + +.TP +.BR --set-faulty +same as --fail. + +.TP +.BR -R ", " --run +start a partially built array. + +.TP +.BR -S ", " --stop +deactivate array, releasing all resources. + +.TP +.BR -o ", " --readonly +mark array as readonly. + +.TP +.BR -w ", " --readwrite +mark array as readwrite. + + +.SH ASSEMBLY MODE + +.HP 12 +Usage: +.B mdadm --assemble +.I device options... +.HP 12 +Usage: +.B mdadm --assemble --scan +.I options... + +.PP +This usage assembles one or more raid arrays from pre-existing components. +For each array, mdadm needs to know the md device, the identity of the +array, and a number of sub devices. These can be found in a number of ways. + +The md device is either given before +.B --scan +or is found from the config file. In the latter case, multiple md devices +can be started with a single mdadm command. + +The identity can be given with the +.B --uuid +option, with the +.B --super-minor +option, can be found in in the config file, or will be taken from the +super block on the first subdevice listed on the command line. + +Devices can be given on the +.B --assemble +command line or from the config file. Only devices which have an md +superblock which contains the right identity will be considered for any device. + +The config file is only used if explicitly named with +.B --config +or requested with +.B --scan. +In the later case, +.B /etc/mdadm.conf +is used. + +If +.B --scan +is not given, then the config file will only be used to find the +identity of md arrays. + +Normally the array will be started after it is assembled. However is +.B --scan +is not given and insufficient drives were lists to start a complete +(non-degraded) array, then the array is not started (to guard against +usage errors). To insist that the array be started in this case (as +may work for RAID1 or RAID5), give the +.B --run +flag. + + +.SH BUILD MODE + +.HP 12 +Usage: +.B mdadm --build +.I device +.BI --chunk= X +.BI --level= Y +.BI --raid-disks= Z +.I devices + +.PP +This usage is similar to +.BR --create . +The difference is that it creates a legacy array without a superblock. With +these arrays there is no difference between initially creating the array and +subsequently assembling the array, except that hopefully there is useful +data there in the second case. + +The level may only be 0, raid0, or linear. All devices must be listed +and the array will be started once complete. + +.SH CREATE MODE + +.HP 12 +Usage: +.B mdadm --create +.I device +.BI --chunk= X +.BI --level= Y +.br +.BI --raid-disks= Z +.I devices + +.PP +This usage will initialise a new md array, associate some devices with +it, and activate the array. + +As devices are added, they are checked to see if they contain raid +superblocks or filesystems. They are also check to see if the variance in +device size exceeds 1%. + +If any discrepancy is found, the array will not automatically be run, though +the presence of a +.B --run +can override this caution. + +'''If the +'''.B --size +'''option is given, it is not necessary to list any subdevices in this command. +'''They can be added later, before a +'''.B --run. +'''If no +'''.B --size +'''is given, the apparent size of the smallest drive given is used. + +The General Management options that are valid with --create are: +.TP +.B --run +insist of running the array even if some devices look like they might +be in use. + +.TP +.B --readonly +start the array readonly - not supported yet. + +.SH DETAIL MODE +.HP 12 +Usage: +.B mdadm --detail +.RB [ --brief ] +.I device ... +.PP + +This usage sill print out the details of the given array including a +list of component devices. To determine names for the devices, +.B mdadm +searches +.B /dev +for device files with the right major and minor numbers. + +With +.B --brief +.B mdadm +prints a single line that identifies the level, number of disks, and +UUID of the array. This line is suitable for inclusion in +.BR /etc/mdadm.conf . + +.SH EXAMINE MODE +.HP 12 +Usage: +.B mdadm --examine +.RB [ --scan ] +.RB [ --brief ] +.I device ... +.PP +This usage will examine some block devices to see if that have a valid +RAID superblock on them. The information in each valid raid +superblock will be printed. + +If +.B --scan +is used, the no devices should be listed, and the complete set of +devices identified in the configuration file are checked. +.B --scan +implies +.B --brief +but this implication can be countered by specifying +.BR --verbose . + +With +.B --brief +.B mdadm +will output an config file entry of each distinct array that was +found. This entry will list the UUID, the raid level, and a list of +the individual devices on which a superblock for that array was found. +This output will by syntactically suitable for inclusion in the +configuration file, but should +.B NOT +be used blindly. Often the array description that you want in the +configuration file is much less specific than that given by +.BR "mdadm -Bs" . +For example, you normally do not want to list the devices, +particularly if they are SCSI devices. + +'''.SH BUGS +'''no known bugs. + +.SH FILES + +.SS /proc/mdstat + +If you're using the +.B /proc +filesystem, +.B /proc/mdstat +gives you informations about md devices status. +This file is not currently used by +.BR mdadm . + +.SS /etc/mdadm.conf + +The config file is line oriented with, as usual, blank lines and lines +beginning with a hash (or pound sign or sharp or number sign, +whichever you like to call it) ignored. +Lines that start with a blank are treated as continuations of the +previous line (I don't like trailing slashes). + +Each line contains a sequence of space-separated words, the first of +which identified the type of line. Keywords are case-insensitive, and +the first work on a line can be abbreviated to 3 letters. + +There are two types of lines. ARRAY and DEVICE. + +The DEVICE lines usually come first. All remaining words on the line +are treated as names of devices, possibly containing wild cards (see +.IR glob (7)). +These list all the devices that +.B mdadm +is allowed to scan +when looking for devices with RAID superblocks. +Each line can contain multiple device names, and there can be multiple +DEVICE lines. For example: +.IP +DEVICE /dev/hda* /dev/hdc* +.br +DEV /dev/sd* +.br +DEVICE /dev/discs/disc*/disc +.PP +The ARRAY lines identify actual arrays. The second word on the line +should be the name of the device where the array is normally +assembled, such as /dev/md1. +Subsequent words identify the array. If multiple identities are given, +then the array much match ALL identities to be considered a match. +Each identity word has a tag, and equals sign, and some value. +The options are: + +.TP +.B uuid= +The value should be a 128 bit uuid in hexadecimal, with punctuation +interspersed if desired. This must match the uuid stored in the +superblock. +.TP +.B super-minor= +The value is an integer which indicates the minor number that was +stored in the superblock when the array was created. When an array is +created as /dev/mdX, then the minor number X is stored. +.TP +.B devices= +The value is a comma separated list of device names. Precisely these +devices will be used to assemble the array. Note that the devices +listed there must also be listed on a DEVICE line. +.TP +.B level= +The value is a raid level. This is normally used to identify an +array, but is supported so that the output of +.B "mdadm --examine --scan" +can be use directly in the configuration file. +.TP +.B disks= +The value is the number of disks in a complete active array. As with +.B level= +this is mainly for compatibility with the output of +.BR "mdadm --examine --scan" . + +.SH TODO + +Finish and document Follow mode. + +.SH SEE ALSO +For information on the various levels of +RAID, check out: + +.IP +.UR http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/ +http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/ +.UE +.PP +for new releases of the RAID driver check out: + +.IP +.UR ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches +ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches +.UE +.PP +or +.IP +.UR http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/ +http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/ +.URk +.PP +.IR raidtab (5), +.IR raid0run (8), +.IR raidstop (8), +.IR mkraid (8) |