From 9a9dab3670110c2db7fe6f716977b72adedbf855 Mon Sep 17 00:00:00 2001 From: Neil Brown Date: Fri, 8 Mar 2002 00:03:52 +0000 Subject: mdadm-0.7 --- mdctl.8 | 575 ---------------------------------------------------------------- 1 file changed, 575 deletions(-) delete mode 100644 mdctl.8 (limited to 'mdctl.8') diff --git a/mdctl.8 b/mdctl.8 deleted file mode 100644 index 153d7b5..0000000 --- a/mdctl.8 +++ /dev/null @@ -1,575 +0,0 @@ -.\" -*- nroff -*- -.TH mdctl 8 -.SH NAME -mdctl \- manage MD devices -.I aka -Linux Software Raid. - -.SH SYNOPSIS - -.BI mdctl " [mode] [options] " - -.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 mdctl -does not support MULTIPATH as yet. - -.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 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 -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 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 mdctl. - -.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/mdctl.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 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 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 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/mdctl.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 mdctl --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 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 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), -.IR mkraid (8) -- cgit