mdadm-0.7.1
[thirdparty/mdadm.git] / mdadm.8
CommitLineData
52826846 1.\" -*- nroff -*-
9a9dab36 2.TH mdadm 8
52826846 3.SH NAME
9a9dab36 4mdadm \- manage MD devices
cd29a5c8
NB
5.I aka
6Linux Software Raid.
7
52826846
NB
8.SH SYNOPSIS
9
9a9dab36 10.BI mdadm " [mode] <raiddevice> [options] <subdevices>"
52826846
NB
11
12.SH DESCRIPTION
13RAID devices are virtual devices created from two or more
cd29a5c8
NB
14real block devices. This allows multiple devices (typically disk
15drives or partitions there-of) to be combined into a single device to
16hold (for example) a single filesystem.
17Some RAID levels included redundancy and so can survive some degree of
18device failure.
19
20Linux Software RAID devices are implemented through the md (Multiple Devices) device driver.
21
22Currently, Linux supports
23.B LINEAR
24md devices,
25.B RAID0
26(striping),
27.B RAID1
28(mirroring),
29.B RAID4
30and
31.B RAID5.
32
33Recent kernels (2002) also support a mode known as
34.BR MULTIPATH .
9a9dab36 35.B mdadm
cd29a5c8 36does not support MULTIPATH as yet.
52826846 37
9a9dab36 38.B mdadm
cd29a5c8
NB
39is a program that can be used to create and manage MD devices. As
40such it provides a similar set of functionality to the
41.B raidtools
42packages.
43The key differences between
9a9dab36 44.B mdadm
cd29a5c8
NB
45and
46.B raidtools
47are:
48.IP \(bu 4
9a9dab36 49.B mdadm
cd29a5c8
NB
50is a single program and not a collection of programs.
51.IP \(bu 4
9a9dab36 52.B mdadm
cd29a5c8 53can perform (almost) all of its functions without having a
9a9dab36 54configuration file. Also mdadm helps with management of the configuration
cd29a5c8
NB
55file.
56.IP \(bu 4
9a9dab36 57.B mdadm
cd29a5c8
NB
58can provide information about your arrays (through Detail and Examine)
59that
60.B raidtools
61cannot.
62.IP \(bu 4
63.B raidtools
64can manage MULTIPATH devices which
9a9dab36 65.B mdadm
cd29a5c8 66cannot yet manage.
52826846
NB
67
68.SH MODES
9a9dab36 69mdadm has 7 major modes of operation:
cd29a5c8
NB
70.TP
71.B Assemble
72Assemble the parts of a previously created
52826846
NB
73array into an active array. Components can be explicitly given
74or can be searched for.
9a9dab36 75.B mdadm
cd29a5c8
NB
76checks that the components
77do form a bona fide array, and can, on request, fiddle superblock
78information so as to assemble a faulty array.
79
80.TP
81.B Build
82Build a legacy array without per-device superblocks.
83
84.TP
85.B Create
86Create a new array with per-device superblocks.
87'''It can progress
88'''in several step create-add-add-run or it can all happen with one command.
89
90.TP
91.B Detail
92Display the details of a given md device. Details include the RAID
93level, the number of devices, which ones are faulty (if any), and the
94array UUID.
95
96.TP
97.B Examine
98Examine a device to see if it is part of an md array, and print out
99the details of that array.
100This mode can also be used to examine a large number of devices and to
101print out a summary of the arrays found in a format suitable for the
9a9dab36 102.B mdadm.conf
cd29a5c8
NB
103configuration file.
104
105.TP
106.B "Follow or Monitor"
107Monitor one or more md devices and act on any state changes.
108
109.TP
110.B Manage
52826846 111This is for odd bits an pieces like hotadd, hotremove, setfaulty, stop,
cd29a5c8
NB
112readonly, readwrite.
113'''If an array is only partially setup by the
114'''Create or Assemble commands, subsequent Manage commands can finish the
115'''job.
52826846
NB
116
117.SH OPTIONS
118
119Available options are:
120
cd29a5c8
NB
121.TP
122.BR -A ", " --assemble
123Assemble an existing array.
52826846 124
cd29a5c8
NB
125.TP
126.BR -B ", " --build
127Build a legacy array without superblocks.
52826846 128
cd29a5c8
NB
129.TP
130.BR -C ", " --create
131Create a new array.
52826846 132
cd29a5c8
NB
133.TP
134.BR -D ", " --detail
135Print detail of one or more md devices.
52826846 136
cd29a5c8
NB
137.TP
138.BR -E ", " --examine
139Print content of md superblock on device(s).
52826846 140
cd29a5c8
NB
141.TP
142.BR -F ", " --follow ", " --monitor
143Select
144.B Monitor
145mode.
52826846 146
cd29a5c8
NB
147.TP
148.BR -h ", " --help
149Display help message or, after above option, mode specific help message.
52826846 150
cd29a5c8
NB
151.TP
152.BR -V ", " --version
9a9dab36 153Print version information for mdadm.
52826846 154
cd29a5c8
NB
155.TP
156.BR -v ", " --verbose
157Be more verbose about what is happening.
52826846 158
cd29a5c8
NB
159.TP
160.BR -b ", " --brief
161Be less verbose. This is used with
162.B --detail
163and
164.BR --examine .
52826846 165
cd29a5c8 166.SH For create or build:
52826846 167
cd29a5c8
NB
168.TP
169.BR -c ", " --chunk=
170Specify chunk size of kibibytes. The default is 64.
52826846 171
cd29a5c8
NB
172.TP
173.BR --rounding=
174Specify rounding factor for linear array (==chunk size)
52826846 175
cd29a5c8
NB
176.TP
177.BR -l ", " --level=
178Set raid level. Options are: linear, raid0, 0, stripe, raid1, 1, mirror, raid5, 4,
179raid5, 5. Obviously some of these are synonymous.
180Only the first 4 are valid when Building.
52826846 181
cd29a5c8
NB
182.TP
183.BR -p ", " --parity=
184Set raid5 parity algorithm. Options are:
185{left,right}-{,a}symmetric, la, ra, ls, rs. The default is left-symmetric.
52826846 186
cd29a5c8
NB
187.TP
188.BR --layout=
189same as --parity
52826846 190
cd29a5c8
NB
191.TP
192.BR -n ", " --raid-disks=
193number of active devices in array.
194
195.TP
196.BR -x ", " --spare-disks=
197number of spare (eXtra) disks in initial array. Spares can be added
198and removed later.
199
200.TP
201.BR -z ", " --size=
202Amount (in Kibibytes) of space to use from each drive in RAID1/4/5.
203This must be a multiple of the chunk size, and must leave about 128Kb
204of space at the end of the drive for the RAID superblock.
205If this is not specified
206(as it normally is not) the smallest drive (or partition) sets the
207size, though if there is a variance among the drives of greater than 1%, a warning is
208issued.
52826846
NB
209
210.SH For assemble:
211
cd29a5c8
NB
212.TP
213.BR -u ", " --uuid=
214uuid of array to assemble. Devices which don't have this uuid are
215excluded
216
217.TP
218.BR -m ", " --super-minor=
219Minor number of device that array was created for. Devices which
220don't have this minor number are excluded. If you create an array as
221/dev/md1, then all superblock will contain the minor number 1, even if
222the array is later assembled as /dev/md2.
223
224.TP
225.BR -c ", " --config=
226config file. Default is
9a9dab36 227.BR /etc/mdadm.conf .
cd29a5c8
NB
228
229.TP
230.BR -s ", " --scan
52826846
NB
231scan config file for missing information
232
cd29a5c8
NB
233.TP
234.BR -f ", " --force
52826846
NB
235Assemble the array even if some superblocks appear out-of-date
236
cd29a5c8
NB
237.TP
238.BR -R ", " --run
239Attempt to start the array even if fewer drives were given than are
240needed for a full array. Normally if not all drives are found and
241.B --scan
242is not used, then the array will be assembled but not started.
243With
244.B --run
245an attempt will be made to start it anyway.
52826846 246
cd29a5c8 247.SH General management
52826846 248
cd29a5c8
NB
249.TP
250.BR -a ", " --add
251'''add, or
252hotadd listed devices.
52826846 253
cd29a5c8
NB
254.TP
255.BR -r ", " --remove
256remove listed devices. The must not be active. i.e. they should
257be failed or spare devices.
52826846 258
cd29a5c8
NB
259.TP
260.BR -f ", " --fail
261mark listed devices as faulty.
52826846 262
cd29a5c8
NB
263.TP
264.BR --set-faulty
265same as --fail.
52826846 266
cd29a5c8
NB
267.TP
268.BR -R ", " --run
269start a partially built array.
52826846 270
cd29a5c8
NB
271.TP
272.BR -S ", " --stop
273deactivate array, releasing all resources.
52826846 274
cd29a5c8
NB
275.TP
276.BR -o ", " --readonly
277mark array as readonly.
52826846 278
cd29a5c8
NB
279.TP
280.BR -w ", " --readwrite
281mark array as readwrite.
52826846 282
52826846
NB
283
284.SH ASSEMBLY MODE
285
cd29a5c8
NB
286.HP 12
287Usage:
9a9dab36 288.B mdadm --assemble
cd29a5c8
NB
289.I device options...
290.HP 12
291Usage:
9a9dab36 292.B mdadm --assemble --scan
cd29a5c8 293.I options...
52826846 294
cd29a5c8 295.PP
52826846 296This usage assembles one or more raid arrays from pre-existing components.
9a9dab36 297For each array, mdadm needs to know the md device, the identity of the
cd29a5c8 298array, and a number of sub devices. These can be found in a number of ways.
52826846
NB
299
300The md device is either given before
301.B --scan
302or is found from the config file. In the latter case, multiple md devices
9a9dab36 303can be started with a single mdadm command.
52826846 304
cd29a5c8 305The identity can be given with the
52826846 306.B --uuid
cd29a5c8
NB
307option, with the
308.B --super-minor
309option, can be found in in the config file, or will be taken from the
310super block on the first subdevice listed on the command line.
52826846
NB
311
312Devices can be given on the
313.B --assemble
cd29a5c8
NB
314command line or from the config file. Only devices which have an md
315superblock which contains the right identity will be considered for any device.
52826846
NB
316
317The config file is only used if explicitly named with
318.B --config
319or requested with
320.B --scan.
321In the later case,
9a9dab36 322.B /etc/mdadm.conf
52826846
NB
323is used.
324
325If
326.B --scan
cd29a5c8
NB
327is not given, then the config file will only be used to find the
328identity of md arrays.
52826846 329
cd29a5c8
NB
330Normally the array will be started after it is assembled. However is
331.B --scan
332is not given and insufficient drives were lists to start a complete
333(non-degraded) array, then the array is not started (to guard against
334usage errors). To insist that the array be started in this case (as
335may work for RAID1 or RAID5), give the
336.B --run
337flag.
52826846 338
52826846 339
cd29a5c8 340.SH BUILD MODE
52826846 341
cd29a5c8
NB
342.HP 12
343Usage:
9a9dab36 344.B mdadm --build
cd29a5c8
NB
345.I device
346.BI --chunk= X
347.BI --level= Y
348.BI --raid-disks= Z
349.I devices
350
351.PP
52826846 352This usage is similar to
cd29a5c8 353.BR --create .
52826846 354The difference is that it creates a legacy array without a superblock. With
cd29a5c8 355these arrays there is no difference between initially creating the array and
52826846
NB
356subsequently assembling the array, except that hopefully there is useful
357data there in the second case.
358
cd29a5c8
NB
359The level may only be 0, raid0, or linear. All devices must be listed
360and the array will be started once complete.
361
362.SH CREATE MODE
363
364.HP 12
365Usage:
9a9dab36 366.B mdadm --create
cd29a5c8
NB
367.I device
368.BI --chunk= X
369.BI --level= Y
370.br
371.BI --raid-disks= Z
372.I devices
373
374.PP
375This usage will initialise a new md array, associate some devices with
376it, and activate the array.
377
378As devices are added, they are checked to see if they contain raid
379superblocks or filesystems. They are also check to see if the variance in
380device size exceeds 1%.
381
382If any discrepancy is found, the array will not automatically be run, though
383the presence of a
384.B --run
385can override this caution.
386
387'''If the
388'''.B --size
389'''option is given, it is not necessary to list any subdevices in this command.
390'''They can be added later, before a
391'''.B --run.
392'''If no
393'''.B --size
394'''is given, the apparent size of the smallest drive given is used.
395
396The General Management options that are valid with --create are:
397.TP
398.B --run
399insist of running the array even if some devices look like they might
400be in use.
401
402.TP
403.B --readonly
404start the array readonly - not supported yet.
52826846 405
cd29a5c8
NB
406.SH DETAIL MODE
407.HP 12
408Usage:
9a9dab36 409.B mdadm --detail
cd29a5c8
NB
410.RB [ --brief ]
411.I device ...
412.PP
413
414This usage sill print out the details of the given array including a
415list of component devices. To determine names for the devices,
9a9dab36 416.B mdadm
cd29a5c8
NB
417searches
418.B /dev
419for device files with the right major and minor numbers.
420
421With
422.B --brief
9a9dab36 423.B mdadm
cd29a5c8
NB
424prints a single line that identifies the level, number of disks, and
425UUID of the array. This line is suitable for inclusion in
9a9dab36 426.BR /etc/mdadm.conf .
cd29a5c8
NB
427
428.SH EXAMINE MODE
429.HP 12
430Usage:
9a9dab36 431.B mdadm --examine
cd29a5c8
NB
432.RB [ --scan ]
433.RB [ --brief ]
434.I device ...
435.PP
436This usage will examine some block devices to see if that have a valid
437RAID superblock on them. The information in each valid raid
438superblock will be printed.
439
440If
441.B --scan
442is used, the no devices should be listed, and the complete set of
443devices identified in the configuration file are checked.
444.B --scan
445implies
446.B --brief
447but this implication can be countered by specifying
448.BR --verbose .
449
450With
451.B --brief
9a9dab36 452.B mdadm
cd29a5c8
NB
453will output an config file entry of each distinct array that was
454found. This entry will list the UUID, the raid level, and a list of
455the individual devices on which a superblock for that array was found.
456This output will by syntactically suitable for inclusion in the
457configuration file, but should
458.B NOT
459be used blindly. Often the array description that you want in the
460configuration file is much less specific than that given by
9a9dab36 461.BR "mdadm -Bs" .
cd29a5c8
NB
462For example, you normally do not want to list the devices,
463particularly if they are SCSI devices.
464
465'''.SH BUGS
466'''no known bugs.
467
468.SH FILES
469
470.SS /proc/mdstat
471
472If you're using the
473.B /proc
474filesystem,
475.B /proc/mdstat
476gives you informations about md devices status.
477This file is not currently used by
9a9dab36 478.BR mdadm .
cd29a5c8 479
9a9dab36 480.SS /etc/mdadm.conf
cd29a5c8
NB
481
482The config file is line oriented with, as usual, blank lines and lines
483beginning with a hash (or pound sign or sharp or number sign,
484whichever you like to call it) ignored.
485Lines that start with a blank are treated as continuations of the
486previous line (I don't like trailing slashes).
487
488Each line contains a sequence of space-separated words, the first of
489which identified the type of line. Keywords are case-insensitive, and
490the first work on a line can be abbreviated to 3 letters.
491
492There are two types of lines. ARRAY and DEVICE.
493
494The DEVICE lines usually come first. All remaining words on the line
495are treated as names of devices, possibly containing wild cards (see
496.IR glob (7)).
497These list all the devices that
9a9dab36 498.B mdadm
cd29a5c8
NB
499is allowed to scan
500when looking for devices with RAID superblocks.
501Each line can contain multiple device names, and there can be multiple
502DEVICE lines. For example:
503.IP
504DEVICE /dev/hda* /dev/hdc*
505.br
506DEV /dev/sd*
507.br
508DEVICE /dev/discs/disc*/disc
509.PP
510The ARRAY lines identify actual arrays. The second word on the line
511should be the name of the device where the array is normally
512assembled, such as /dev/md1.
513Subsequent words identify the array. If multiple identities are given,
514then the array much match ALL identities to be considered a match.
515Each identity word has a tag, and equals sign, and some value.
516The options are:
517
518.TP
519.B uuid=
520The value should be a 128 bit uuid in hexadecimal, with punctuation
521interspersed if desired. This must match the uuid stored in the
522superblock.
523.TP
524.B super-minor=
525The value is an integer which indicates the minor number that was
526stored in the superblock when the array was created. When an array is
527created as /dev/mdX, then the minor number X is stored.
528.TP
529.B devices=
530The value is a comma separated list of device names. Precisely these
531devices will be used to assemble the array. Note that the devices
532listed there must also be listed on a DEVICE line.
533.TP
534.B level=
535The value is a raid level. This is normally used to identify an
536array, but is supported so that the output of
9a9dab36 537.B "mdadm --examine --scan"
cd29a5c8
NB
538can be use directly in the configuration file.
539.TP
540.B disks=
541The value is the number of disks in a complete active array. As with
542.B level=
543this is mainly for compatibility with the output of
9a9dab36 544.BR "mdadm --examine --scan" .
52826846
NB
545
546.SH TODO
547
cd29a5c8 548Finish and document Follow mode.
52826846
NB
549
550.SH SEE ALSO
cd29a5c8
NB
551For information on the various levels of
552RAID, check out:
553
554.IP
555.UR http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
556http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/
557.UE
558.PP
559for new releases of the RAID driver check out:
560
561.IP
562.UR ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
563ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches
564.UE
565.PP
566or
567.IP
568.UR http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
569http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/
570.URk
571.PP
56eb10c0
NB
572.BR mdadm.conf (5),
573.BR md (4).
574.PP
52826846
NB
575.IR raidtab (5),
576.IR raid0run (8),
577.IR raidstop (8),
578.IR mkraid (8)