From cd29a5c835c11cbcedc10487677eac6a946ad61b Mon Sep 17 00:00:00 2001 From: Neil Brown Date: Wed, 6 Mar 2002 23:17:40 +0000 Subject: mdctl-0.6 --- mdctl.8 | 668 ++++++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 478 insertions(+), 190 deletions(-) (limited to 'mdctl.8') diff --git a/mdctl.8 b/mdctl.8 index fe9c656..153d7b5 100644 --- a/mdctl.8 +++ b/mdctl.8 @@ -1,286 +1,574 @@ .\" -*- nroff -*- .TH mdctl 8 .SH NAME -mdctl \- a single program that can be used to control Linux md devices +mdctl \- manage MD devices +.I aka +Linux Software Raid. + .SH SYNOPSIS -.BI mdctl -[mode] [options] +.BI mdctl " [mode] [options] " .SH DESCRIPTION RAID devices are virtual devices created from two or more -real block devices. This allows multiple disks to be combined into a single -filesystem, possibly with integrated redundancy to survive drive failure.. Linux RAID devices -are implemented through the md device driver. - -If you're using the -.B /proc -filesystem, -.B /proc/mdstat -gives you informations about md devices status. - -Currently, Linux supports linear md devices, RAID0 (striping), RAID1 -(mirrroring), RAID4 and RAID5. For information on the various levels of -RAID, check out: - - http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/ - -for new releases of the RAID driver check out: - - ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches - -.B mdctl -is a single program that can be used to control Linux md devices. It -is intended to provide all the functionality (and more) of the mdtools -and raidtools but with a very different interface. - -mdctl can perform all functions without a configuration file. There is the -option of using a configuration file, but not in the same way that raidtools -uses one. raidtools uses a configuration file to describe how to create a -RAID array, and also uses this file partially to start a previously created -RAID array. Further, raidtools requires the configuration file for such -things as stopping a raid array which needs to know nothing about the array. - -The configuration file that can be used by mdctl lists two different things: - -.IP "\fB\-\fP" -a list of md devices and information about how to identify each. The -identity can consist of a UUID, and minor-number as recorded on the -superblock, or a list of devices. +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 mdctl +does not support MULTIPATH as yet. -.IP "\fB\-\fP" -a list of devices that should be scanned for md sub-devices. +.B mdctl +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 mdctl +and +.B raidtools +are: +.IP \(bu 4 +.B mdctl +is a single program and not a collection of programs. +.IP \(bu 4 +.B mdctl +can perform (almost) all of its functions without having a +configuration file. Also mdctl helps with management of the configuration +file. +.IP \(bu 4 +.B mdctl +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 mdctl +cannot yet manage. .SH MODES -mdctl has 4 major modes of operation: -.IP "\fBCreate\fP" -This mode is used to create a new array with a superblock. It can progress -in several step create-add-add-run or it can all happen with one command. - -.IP "\fBAssemble\fP" -This mode is used to assemble the parts of a previously created +mdctl 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 mdctl -(optionally) checks that the components -do form a bonafide array, and can, on request, fiddle superblock -version numbers so as to assemble a faulty array. - -.IP "\fBBuild\fP" -This is for building legacy arrays without superblocks. - -.IP "\fBManage\fP" +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 mdctl.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/Assemble/Build command, subsequent Manage commands can finish the -job. +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: -.IP "\fB\-C\fP, \fB\-\-create\fP" -Create a new array +.TP +.BR -A ", " --assemble +Assemble an existing array. -.IP "\fB-A\fP, \fB\-\-assemble\fP" -Assemble an existing array +.TP +.BR -B ", " --build +Build a legacy array without superblocks. -.IP "\fB\-B\fP, \fB\-\-build\fP" -Build a legacy array without superblock +.TP +.BR -C ", " --create +Create a new array. -.IP "\fB\-D\fP, \fB\-\-detail\fP" -Print detail of a given md array +.TP +.BR -D ", " --detail +Print detail of one or more md devices. -.IP "\fB\-E\fP, \fB\-\-examine\fP" -Print content of md superblock on device +.TP +.BR -E ", " --examine +Print content of md superblock on device(s). -.IP "\fB\-h\fP, \fB\-\-help\fP" -This help message or, after above option, mode specific help message +.TP +.BR -F ", " --follow ", " --monitor +Select +.B Monitor +mode. -.IP "\fB\-V\fP, \fB\-\-version\fP" -Print version information for mdctl +.TP +.BR -h ", " --help +Display help message or, after above option, mode specific help message. -.IP "\fB\-v\fP, \fB\-\-verbose\fP" -Be more verbose about what is happening +.TP +.BR -V ", " --version +Print version information for mdctl. -.SH For create or build: +.TP +.BR -v ", " --verbose +Be more verbose about what is happening. -.IP "\fB\-c\fP, \fB\-\-chunk=\fP" -chunk size of kibibytes +.TP +.BR -b ", " --brief +Be less verbose. This is used with +.B --detail +and +.BR --examine . -.IP "\fB\-\-rounding=\fP" -rounding factor for linear array (==chunk size) +.SH For create or build: -.IP "\fB\-l\fP, \fB\-\-level=\fP" -raid level: 0,1,4,5,linear. 0 or linear for build +.TP +.BR -c ", " --chunk= +Specify chunk size of kibibytes. The default is 64. -.IP "\fB\-p\fP, \fB\-\-parity=\fP" -raid5 parity algorithm: {left,right}-{,a}symmetric +.TP +.BR --rounding= +Specify rounding factor for linear array (==chunk size) -.IP "\fB\-\-layout=\fP" -same as --parity +.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. -.IP "\fB\-n\fP, \fB\-\-raid-disks=\fP" -number of active devices in array +.TP +.BR -p ", " --parity= +Set raid5 parity algorithm. Options are: +{left,right}-{,a}symmetric, la, ra, ls, rs. The default is left-symmetric. -.IP "\fB\-x\fP, \fB\-\-spare-disks=\fP" -number of spares (eXtras) to allow space for +.TP +.BR --layout= +same as --parity -.IP "\fB\-z\fP, \fB\-\-size=\fP" -Size (in K) of each drive in RAID1/4/5 - optional +.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: -.IP "\fB\-u\fP, \fB\-\-uuid=\fP" -uuid of array to assemble. Devices which don't have this uuid are excluded - -.IP "\fB\-c\fP, \fB\-\-config=\fP" -config file - -.IP "\fB\-s\fP, \fB\-\-scan\fP" +.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/mdctl.conf . + +.TP +.BR -s ", " --scan scan config file for missing information -.IP "\fB\-f\fP, \fB\-\-force\fP" +.TP +.BR -f ", " --force Assemble the array even if some superblocks appear out-of-date -.SH General management - -.IP "\fB\-a\fP, \fB\-\-add\fP" -add, or hotadd subsequent devices - -.IP "\fB\-r\fP, \fB\-\-remove\fP" -remove subsequent devices - -.IP "\fB\-f\fP, \fB\-\-fail\fP" -mark subsequent devices a faulty - -.IP "\fB\-\-set-faulty\fP" -same as --fail - -.IP "\fB\-R\fP, \fB\-\-run\fP" -start a partially built array +.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. -.IP "\fB\-S\fP, \fB\-\-stop\fP" -deactivate array, releasing all resources +.SH General management -.IP "\fB\-o\fP, \fB\-\-readonly\fP" -mark array as readonly +.TP +.BR -a ", " --add +'''add, or +hotadd listed devices. -.IP "\fB\-w\fP, \fB\-\-readwrite\fP" -mark array as readwrite +.TP +.BR -r ", " --remove +remove listed devices. The must not be active. i.e. they should +be failed or spare devices. -.SH CREATE MODE +.TP +.BR -f ", " --fail +mark listed devices as faulty. -Usage: +.TP +.BR --set-faulty +same as --fail. -.B mdctl ---create device --chunk=X --level=Y --raid-disks=Z devices +.TP +.BR -R ", " --run +start a partially built array. -This usage will initialise a new md array and possibly associate some -devices with it. If enough devices are given to complete the array, the -array will be activated. Otherwise it will be left inactive to be completed -and activated by subsequent management commands. +.TP +.BR -S ", " --stop +deactivate array, releasing all resources. -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%. +.TP +.BR -o ", " --readonly +mark array as readonly. -If any discrepancy is found, the array will not automatically be run, though -the presence of a -.B --run -can override this caution. +.TP +.BR -w ", " --readwrite +mark array as readwrite. -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: -.IP "\fB\-\-run\fP" -insist of running the array even if not all devices are present or some look -odd. - -.IP "\fB\-\-readonly\fP" -start the array readonly - not supported yet. .SH ASSEMBLY MODE -Usage: - -.B mdctl ---assemble device options... - -.B mdctl ---assemble --scan options... +.HP 12 +Usage: +.B mdctl --assemble +.I device options... +.HP 12 +Usage: +.B mdctl --assemble --scan +.I options... +.PP This usage assembles one or more raid arrays from pre-existing components. -For each array, mdctl needs to know the md device, the uuid, and a number of -sub devices. These can be found in a number of ways. +For each array, mdctl 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 mdctl command. -The uuid can be given with the +The identity can be given with the .B --uuid -option, or 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 or in a -subsequent -.B --add -command. +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, on subsequent -.B 'mdctl --add' -command lines, or from the config file. Only devices which have an md -superblock which contains the right uuid will be considered for any device. +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/md.conf +.B /etc/mdctl.conf is used. If .B --scan -is not given, then the config file will only be used to find uuids for md -arrays. - -The format of the config file is: - not yet documented +is not given, then the config file will only be used to find the +identity of md arrays. -.SH BUILD MDOE +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. -Usage: -.B mdctl ---build device -chunk=X --level=Y --raid-disks=Z devices +.SH BUILD MODE +.HP 12 +Usage: +.B mdctl --build +.I device +.BI --chunk= X +.BI --level= Y +.BI --raid-disks= Z +.I devices + +.PP This usage is similar to -.B --create. +.BR --create . The difference is that it creates a legacy array without a superblock. With -these arrays there is no different between initially creating the array and +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 or linear. All devices must be listed and the array -will be started once complete. +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 mdctl --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 BUGS -no known bugs. +.SH DETAIL MODE +.HP 12 +Usage: +.B mdctl --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 mdctl +searches +.B /dev +for device files with the right major and minor numbers. + +With +.B --brief +.B mdctl +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/mdctl.conf . + +.SH EXAMINE MODE +.HP 12 +Usage: +.B mdctl --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 mdctl +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 "mdctl -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 mdctl . + +.SS /etc/mdctl.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 mdctl +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 "mdctl --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 "mdctl --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), -- cgit