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