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