diff options
| -rw-r--r-- | ANNOUNCE | 39 | ||||
| -rw-r--r-- | ChangeLog | 11 | ||||
| -rw-r--r-- | Create.c | 21 | ||||
| -rw-r--r-- | Makefile | 5 | ||||
| -rw-r--r-- | ReadMe.c | 2 | ||||
| -rw-r--r-- | TODO | 6 | ||||
| -rw-r--r-- | md.4 | 36 | ||||
| -rw-r--r-- | mdadm.8 | 166 | ||||
| -rw-r--r-- | mdadm.c | 1 | ||||
| -rw-r--r-- | mdadm.conf.5 | 51 | ||||
| -rw-r--r-- | mdadm.spec | 8 |
11 files changed, 267 insertions, 79 deletions
diff --git a/ANNOUNCE b/ANNOUNCE new file mode 100644 index 0000000..f16020d --- /dev/null +++ b/ANNOUNCE @@ -0,0 +1,39 @@ +Subject: ANNOUNCE: mdadm 1.0.0 - A tool for managing Soft RAID under Linux + + +I am pleased to announce the availability of + mdadm version 1.0.0 +It is available at + http://www.cse.unsw.edu.au/~neilb/source/mdadm/ + +as both a source tar-ball, as an SRPM, and as an RPM for i386. + +mdadm is a tool for creating, managing and monitoring +device arrays using the "md" driver in Linux, also +known as Software RAID arrays. + +mdadm incorporates much of the functionality of raidtools, though with +a very different interface, and also provides extra functionality +including: + - monitoring array and alerting admin staff of issues + - moving spares between arrays as needed + - assembling arrays based on superblock content + - displaying details of arrays and of superblocks + +The release of version 1 is intended to suggest that mdadm is + - feature-complete + - reasonably bug-free + - reasonably well documented. + +I hope not to make another release until md driver enhancements +necessitate it, but we will have to wait and see.... + +Note: mdadm was previously known as 'mdctl'. It is the same tool, +just a different name. + +Development of mdadm is sponsored by CSE@UNSW: + The School of Computer Science and Engineering +at + The University of New South Wales + +NeilBrown 10may2002 @@ -1,4 +1,13 @@ -Changes Prior to this release +Changes Prior to 1.0.0 reease + - Allow --config with Misc mode (for --examine --scan) + - Add $(CXFLAGS) to end of CFLAGS in makefile + - When making an N disk raid5 array, the Nth drive + is moved to the end of the array as a spare rather than + being shifted up one place. This means that when the + kernel builds onto the last spare and inserts it, + the devices will be in the expected order. + - Man page improvements +Changes Prior to 0.8.2 release - Correct spelling of persist[ae]nce/persist[ae]nt. - Change "disk" to "device" in options and config file - convert array size to "long long" *before* shift-left in -D and -Q @@ -62,6 +62,7 @@ int Create(char *mddev, int mdfd, int first_missing = MD_SB_DISKS*2; int missing_disks = 0; int insert_point = MD_SB_DISKS*2; /* where to insert a missing drive */ + mddev_dev_t moved_disk = NULL; /* the disk that was moved out of the insert point */ mdu_array_info_t array; @@ -270,20 +271,22 @@ int Create(char *mddev, int mdfd, return 1; } - for (dnum=0, dv = devlist ; dv ; dv=dv->next, dnum++) { + for (dnum=0, dv = devlist ; dv ; dv=(dv->next)?(dv->next):moved_disk, dnum++) { int fd; struct stat stb; mdu_disk_info_t disk; disk.number = dnum; - if (dnum >= insert_point) - disk.number++; + if (dnum == insert_point) { + moved_disk = dv; + } disk.raid_disk = disk.number; if (disk.raid_disk < raiddisks) disk.state = 6; /* active and in sync */ else disk.state = 0; - if (strcasecmp(dv->devname, "missing")==0) { + if (dnum == insert_point || + strcasecmp(dv->devname, "missing")==0) { disk.major = 0; disk.minor = 0; disk.state = 1; /* faulty */ @@ -304,15 +307,7 @@ int Create(char *mddev, int mdfd, dv->devname, strerror(errno)); return 1; } - } - - if (insert_point < MD_SB_DISKS) { - mdu_disk_info_t disk; - disk.number = insert_point; - disk.raid_disk = disk.number; - disk.state = 1; /* faulty */ - disk.major = disk.minor = 0; - ioctl(mdfd,ADD_NEW_DISK, &disk); + if (dv == moved_disk && dnum != insert_point) break; } /* param is not actually used */ @@ -27,10 +27,13 @@ # Australia # +# define "CXFLAGS" to give extra flags to CC. +# e.g. make CXFLAGS=-O to optimise CC = gcc +CXFLAGS = -ggdb SYSCONFDIR = /etc CONFFILE = $(SYSCONFDIR)/mdadm.conf -CFLAGS = -Wall -Werror -Wstrict-prototypes -ggdb -DCONFFILE=\"$(CONFFILE)\" +CFLAGS = -Wall -Werror -Wstrict-prototypes -DCONFFILE=\"$(CONFFILE)\" $(CXFLAGS) # If you want a static binary, you might uncomment these # LDFLAGS = -static @@ -29,7 +29,7 @@ #include "mdadm.h" -char Version[] = Name " - v0.8.2 - 11 April 2002\n"; +char Version[] = Name " - v1.0.0 - 10 May 2002\n"; /* * File: ReadMe.c * @@ -1,6 +1,4 @@ -Document "missing" - ?? Allow -S /dev/md? - current complains subsequent not a/d/r - DONE @@ -27,9 +25,9 @@ Document "missing" * --follow to syslog -* --follow to move spares around +* --follow to move spares around DONE -* --follow to notice other events: +* --follow to notice other events: DONE rebuild started spare activated spare removed @@ -14,10 +14,10 @@ redundancy, and hence the acronym RAID which stands for a Redundant Array of Independent Devices. .PP .B md -support RAID levels 1 (mirroring) 4 (striped array with parity device) and 5 -(striped array with distributed parity information. If a single underlying -device fails while using one of these level, the array will continue -to function. +supports RAID levels 1 (mirroring) 4 (striped array with parity +device) and 5 (striped array with distributed parity information). +If a single underlying device fails while using one of these levels, +the array will continue to function. .PP .B md also supports a number of pseudo RAID (non-redundant) configurations @@ -54,7 +54,7 @@ this device is part of. Early versions of the .B md driver only supported Linear and Raid0 configurations and so -did not use an MD superblock (as there is not state that needs to be +did not use an MD superblock (as there is no state that needs to be recorded). While it is strongly recommended that all newly created arrays utilise a superblock to help ensure that they are assembled properly, the @@ -82,16 +82,16 @@ A RAID0 array is configured at creation with a .B "Chunk Size" which must be a power of two, and at least 4 kibibytes. -The RAID0 driver places the first chunk of the array to the first +The RAID0 driver assigns the first chunk of the array to the first device, the second chunk to the second device, and so on until all -drives have been assigned one chuck. This collection of chunks forms +drives have been assigned one chunk. This collection of chunks forms a .BR stripe . Further chunks are gathered into stripes in the same way which are assigned to the remaining space in the drives. -If device in the array are not all the same size, then once the -smallest devices has been exhausted, the RAID0 driver starts +If devices in the array are not all the same size, then once the +smallest device has been exhausted, the RAID0 driver starts collecting chunks into smaller stripes that only span the drives which still have remaining space. @@ -146,24 +146,24 @@ in a MULTIPATH md array. However there are multiple access points (paths) to this device, and one of these paths might fail, so there are some similarities. -A MULTIPATH array is composed of a number of different devices, often -fibre channel interfaces, that all refer the the same real device. -If one of these interfaces fails (e.g. due to cable problems), the -multipath driver to attempt to redirect requests to another -interface. +A MULTIPATH array is composed of a number of logical different +devices, often fibre channel interfaces, that all refer the the same +real device. If one of these interfaces fails (e.g. due to cable +problems), the multipath driver to attempt to redirect requests to +another interface. .SS UNCLEAN SHUTDOWN -When changes are made to an RAID1, RAID4, or RAID5 array there is a +When changes are made to a RAID1, RAID4, or RAID5 array there is a possibility of inconsistency for short periods of time as each update requires are least two block to be written to different devices, and these writes probably wont happen at exactly the same time. -This is a system with one of these arrays is shutdown in the middle of +Thus if a system with one of these arrays is shutdown in the middle of a write operation (e.g. due to power failure), the array may not be consistent. -The handle this situation, the md driver marks an array as "dirty" +To handle this situation, the md driver marks an array as "dirty" before writing any data to it, and marks it as "clean" when the array is being disabled, e.g. at shutdown. If the md driver finds an array to be dirty at startup, it proceeds to @@ -190,7 +190,7 @@ data what was on that failed drive, either by copying a working drive in a RAID1 configuration, or by doing calculations with the parity block on RAID4 and RAID5. -Why this recovery process is happening, the md driver will monitor +While this recovery process is happening, the md driver will monitor accesses to the array and will slow down the rate of recovery if other activity is happening, so that normal access to the array will not be unduly affected. When no other activity is happening, the recovery @@ -14,10 +14,11 @@ 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 +Some RAID levels include redundancy and so can survive some degree of device failure. -Linux Software RAID devices are implemented through the md (Multiple Devices) device driver. +Linux Software RAID devices are implemented through the md (Multiple +Devices) device driver. Currently, Linux supports .B LINEAR @@ -52,7 +53,9 @@ 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 +configuration file. Also +.B mdadm +helps with management of the configuration file. .IP \(bu 4 .B mdadm @@ -103,7 +106,7 @@ Available options are: .TP .BR -A ", " --assemble -Assemble an existing array. +Assemble a pre-existing array. .TP .BR -B ", " --build @@ -202,7 +205,11 @@ 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. +left-asymmetric, +left-symmetric, +right-asymmetric, +right-symmetric, +la, ra, ls, rs. The default is left-symmetric. .TP .BR --layout= @@ -238,7 +245,7 @@ excluded .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 +/dev/md1, then all superblocks will contain the minor number 1, even if the array is later assembled as /dev/md2. .TP @@ -264,7 +271,7 @@ hotadd listed devices. .TP .BR -r ", " --remove -remove listed devices. The must not be active. i.e. they should +remove listed devices. They must not be active. i.e. they should be failed or spare devices. .TP @@ -363,9 +370,9 @@ If 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 +Normally the array will be started after it is assembled. However if .B --scan -is not given and insufficient drives were lists to start a complete +is not given and insufficient drives were listed 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 @@ -412,7 +419,7 @@ 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 +superblocks or filesystems. They are also checked to see if the variance in device size exceeds 1%. If any discrepancy is found, the array will not automatically be run, though @@ -420,6 +427,18 @@ the presence of a .B --run can override this caution. +To create a "degraded" array in which some devices are missing, simply +give the word +.B missing +in place of a device name. This will cause +.B mdadm +to leave the corresponding slot in the array empty. +For a RAID4 or RAID5 array at most one slot can be +.BR missing . +For a RAID1 array, only one real device needs to be given. All of the +others can be +.BR missing . + '''If the '''.B --size '''option is given, it is not necessary to list any component-devices in this command. @@ -451,14 +470,14 @@ This usage will allow individual devices in an array to be failed, removed or added. It is possible to perform multiple operations with on command. For example: .br -mdadm /dev/md0 -f /dev/hda1 -r /dev/hda1 /a /dev/hda1 +.B " mdadm /dev/md0 -f /dev/hda1 -r /dev/hda1 /a /dev/hda1" .br will firstly mark .B /dev/hda1 as faulty in .B /dev/md0 and will then remove it from the array and finally add it back -in as a spare. However only one md array can be affect by a single +in as a spare. However only one md array can be affected by a single command. .SH MISC MODE @@ -480,17 +499,21 @@ The information discovered is reported. .TP --detail -The device should be an active md device. mdadm will display -a detailed description of the array. +The device should be an active md device. +.B mdadm +will display a detailed description of the array. .B --brief -will cause the output to be less detailed and format to be +or +.B --scan +will cause the output to be less detailed and the format to be suitable for inclusion in .BR /etc/mdadm.conf . .TP --examine -The device should be a component of an md array. mdadm will -read the md superblock of the device and display the contents. +The device should be a component of an md array. +.B mdadm +will read the md superblock of the device and display the contents. If .B --brief is given, or @@ -500,7 +523,7 @@ are grouped together and reported in a single entry suitable for inclusion in .BR /etc/mdadm.conf . -Have +Having .B --scan without listing any devices will cause all devices listed in the config file to be examined. @@ -525,6 +548,19 @@ This will change a .B readonly array back to being read/write. +.TP +--scan +For all operations except +.BR --examine , +.B --scan +will cause the operation to be applied to all arrays listed in +.BR /proc/mdstat . +For +.BR --examine, +.B --scan +causes all devices listed in the config file to be examined. + + .SH MONITOR MODE .HP 12 @@ -541,6 +577,13 @@ noticed. will never exit once it decides that there are arrays to be checked, so it should normally be run in the background. +As well as reporting events, +.B mdadm +may move a spare drive from one array to another if they are in the +same +.B spare-group +and if the destination array has a failed drive but not spares. + If any devices are listed on the command line, .B mdadm will only monitor those devices. Otherwise all arrays listed in the @@ -552,7 +595,7 @@ will also be monitored. The result of monitoring the arrays is the generation of events. These events are passed to a separate program (is specified) and may -be mail to a given E-mail address. +be mailed to a given E-mail address. If @@ -564,7 +607,7 @@ will not monitor anything. Without .B --scan .B mdadm -will continue monitoring along as something was found to monitor. If +will continue monitoring as long as something was found to monitor. If no program or email is given, then each event is reported to .BR stdout . @@ -573,7 +616,7 @@ The different events are: .RS 4 .TP .B DeviceDisappeared -An md array which previously was configured appear to no longer be +An md array which previously was configured appears to no longer be configured. .TP @@ -643,7 +686,7 @@ be labelled with the same in the configuration file. The .B spare-group name can be any string. It is only necessary that different spare -groups use different name. +groups use different names. When .B mdadm @@ -656,9 +699,65 @@ first. If the removal succeeds but the adding fails, then it is added back to the original array. +.SH EXAMPLES + +To find out if a devices is a raid array or part of one: +.br +.B " mdadm -Q /dev/name-of-device" + +To assemble and start all array listed in the standard config file: +.br +.B " mdadm -As" + +To shut down all arrays (that are not still in used): +.br +.B " mdadm --stop --scan" + +To monitor all arrays if (and only if) an email address or program +was given in the config file, but poll every 2 minutes: +.br +.B " mdadm -Fs --delay=120" + +To create /dev/md0 as a RAID1 array with /dev/hda1 and /dev/hdc1: +.br +.B " mdadm -C /dev/md0 -l1 -n2 /dev/hd[ac]1" + +To create prototype a config file that describes currently +active arrays that are known to be made from partitions of +IDE or SCSI drives: +.br +.B " echo 'DEVICE /dev/hd*[0-9] /dev/sd*[0-9]' > mdadm.conf" +.br +.B " mdadm --detail --scan >> mdadm.conf" +.br +This file should be reviewed before being used as it may +contain unwanted detail. + +To find out what raid arrays could be assembled from existing +IDE and SCSI whole drives (not partitions): +.br +.B " echo 'DEVICE /dev/hd[a-z] /dev/sd*[a-z]' > mdadm.conf" +.br +.B " mdadm -Es -c mdadm.conf >> mdadm.conf" +This file is very likely to contain unwanted detail, particularly +the +.B devices= +entries. + +To get help about Create mode: +.br +.B " mdadm --create --help" + +To get help about the format of the config file: +.br +.B " mdadm --config --help" + +To get general help: +.br +.B " mdadm --help" + + -'''.SH BUGS -'''no known bugs. .SH FILES @@ -668,9 +767,13 @@ 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 . +lists all active md devices with information about them. +.B mdadm +uses this to find arrays when +.B --scan +is given in Misc mode, and to monitor array reconstruction +on Monitor mode. + .SS /etc/mdadm.conf @@ -681,10 +784,11 @@ they contain MD super block, and gives identifying information for more details. -.SH TODO - -Finish and document Follow mode. - +.SH NOTE +.B mdadm +was previously known as +.BR mdctl . + .SH SEE ALSO For information on the various levels of RAID, check out: @@ -369,6 +369,7 @@ int main(int argc, char *argv[]) continue; case O(ASSEMBLE,'c'): /* config file */ + case O(MISC, 'c'): case O(MONITOR,'c'): if (configfile) { fprintf(stderr, Name ": configfile cannot be set twice. " diff --git a/mdadm.conf.5 b/mdadm.conf.5 index e45ad8c..e11f9d5 100644 --- a/mdadm.conf.5 +++ b/mdadm.conf.5 @@ -11,19 +11,19 @@ is a tool for creating, managing, and monitoring RAID devices using the driver in Linux. .PP Some common tasks, such as assembling all arrays, can be simplified -by describing the devices and array in this configuration file. +by describing the devices and arrays in this configuration file. .SS SYNTAX The file should be seen as a collection of words separated by white space (space, tab, or newline). Any word that beings with a hash sign (#) starts a comment and that -word together with the remainder of the line are ignored. +word together with the remainder of the line is ignored. -Any line that start with white space (space or tab) is treated as +Any line that starts with white space (space or tab) is treated as though it were a continuation of the previous line. Empty lines are ignored, but otherwise each (non continuation) line -must start with a keyword as listed below. The key words are case +must start with a keyword as listed below. The keywords are case insensitive and can be abbreviated to 3 characters. The keywords are: @@ -35,7 +35,7 @@ line lists the devices (whole devices or partitions) that might contain a component of an MD array. When looking for the components of an array, .B mdadm -will scan these devices and no others. +will scan these devices (or any devices listed on the command line). The .B device @@ -61,9 +61,9 @@ assembled, such as .BR /dev/md1 . Subsequent words identify the array, or identify the array as a member of a group. If multiple identities are given, -then the array must match ALL identities to be considered a match. -Each identity word has a tag, and equals sign, and some value. -The options are: +then a component device must match ALL identities to be considered a +match. Each identity word has a tag, and equals sign, and some value. +The tags are: .RS 4 .TP @@ -141,6 +141,41 @@ There should only be one .B program line and it should be give only one program. +.SH EXAMPLE +DEVICE /dev/sd[bcdjkl]1 +.br +DEVICE /dev/hda1 /dev/hdb1 + +# /dev/md0 is known by it's UID. +.br +ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371 +.br +# /dev/md1 contains all devices with a minor number of +.br +# 1 in the superblock. +.br +ARRAY /dev/md1 superminor=1 +.br +# /dev/md2 is made from precisey these two devices +.br +ARRAY /dev/md2 devices=/dev/hda1,/dev/hda2 + +# /dev/md4 and /dev/md5 are a spare-group and spares +.br +# can be moved between them +.br +ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df +.br + spare-group=group1 +.br +ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977 +.br + spare-group=group1 + +MAILADDR root@mydomain.tld +.br +PROGRAM /usr/sbin/handle-mdadm-events + .SH SEE ALSO .BR mdadm (8), @@ -1,6 +1,6 @@ Summary: mdadm is used for controlling Linux md devices (aka RAID arrays) Name: mdadm -Version: 0.8.2 +Version: 1.0.0 Release: 1 Source: http://www.cse.unsw.edu.au/~neilb/source/mdadm/mdadm-%{version}.tgz URL: http://www.cse.unsw.edu.au/~neilb/source/mdadm/ @@ -28,7 +28,7 @@ some common tasks). # people who install RPMs (especially given that the default RPM options # will strip the binary) are not going to be running gdb against the # program. -make CFLAGS="$RPM_OPT_FLAGS" SYSCONFDIR="%{_sysconfdir}" +make CXFLAGS="$RPM_OPT_FLAGS" SYSCONFDIR="%{_sysconfdir}" %install make DESTDIR=$RPM_BUILD_ROOT MANDIR=%{_mandir} BINDIR=%{_sbindir} install @@ -45,6 +45,10 @@ rm -rf $RPM_BUILD_ROOT %{_mandir}/man*/md* %changelog +* Fri May 10 2002 <neilb@cse.unsw.edu.au> +- update to 1.0.0 +- Set CXFLAGS instead of CFLAGS + * Sat Apr 6 2002 <neilb@cse.unsw.edu.au> - change %install to use "make install" |