.\" -*- 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] <raiddevice> [options]
+.BI mdctl " [mode] <raiddevice> [options] <subdevices>"
.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),
projects / thirdparty / mdadm.git / blobdiff