1MDADM(8) System Manager's Manual MDADM(8)
2
6 mdadm - manage MD devices aka Linux Software RAID
7
10 mdadm [mode] <raiddevice> [options] <component-devices>
11
14 RAID devices are virtual devices created from two or more real block
15 devices. This allows multiple devices (typically disk drives or parti‐
16 tions thereof) to be combined into a single device to hold (for exam‐
17 ple) a single filesystem. Some RAID levels include redundancy and so
18 can survive some degree of device failure.
19 Linux Software RAID devices are implemented through the md (Multiple
21 Devices) device driver.
22 Currently, Linux supports LINEAR md devices, RAID0 (striping), RAID1
24 (mirroring), RAID4, RAID5, RAID6, RAID10, MULTIPATH, FAULTY, and CON‐
25 TAINER.
26 MULTIPATH is not a Software RAID mechanism, but does involve multiple
28 devices: each device is a path to one common physical storage device.
29 New installations should not use md/multipath as it is not well sup‐
30 ported and has no ongoing development. Use the Device Mapper based
31 multipath-tools instead.
32 FAULTY is also not true RAID, and it only involves one device. It pro‐
34 vides a layer over a true device that can be used to inject faults.
35 CONTAINER is different again. A CONTAINER is a collection of devices
37 that are managed as a set. This is similar to the set of devices con‐
38 nected to a hardware RAID controller. The set of devices may contain a
39 number of different RAID arrays each utilising some (or all) of the
40 blocks from a number of the devices in the set. For example, two
41 devices in a 5-device set might form a RAID1 using the whole devices.
42 The remaining three might have a RAID5 over the first half of each
43 device, and a RAID0 over the second half.
44 With a CONTAINER, there is one set of metadata that describes all of
46 the arrays in the container. So when mdadm creates a CONTAINER device,
47 the device just represents the metadata. Other normal arrays (RAID1
48 etc) can be created inside the container.
49
52 mdadm has several major modes of operation:
53 Assemble
55 Assemble the components of a previously created array into an
56 active array. Components can be explicitly given or can be
57 searched for. mdadm checks that the components do form a bona
58 fide array, and can, on request, fiddle superblock information
59 so as to assemble a faulty array.
60 Build Build an array that doesn't have per-device metadata
63 (superblocks). For these sorts of arrays, mdadm cannot differ‐
64 entiate between initial creation and subsequent assembly of an
65 array. It also cannot perform any checks that appropriate com‐
66 ponents have been requested. Because of this, the Build mode
67 should only be used together with a complete understanding of
68 what you are doing.
69 Create Create a new array with per-device metadata (superblocks).
72 Appropriate metadata is written to each device, and then the
73 array comprising those devices is activated. A 'resync' process
74 is started to make sure that the array is consistent (e.g. both
75 sides of a mirror contain the same data) but the content of the
76 device is left otherwise untouched. The array can be used as
77 soon as it has been created. There is no need to wait for the
78 initial resync to finish.
79 Follow or Monitor
82 Monitor one or more md devices and act on any state changes.
83 This is only meaningful for RAID1, 4, 5, 6, 10 or multipath
84 arrays, as only these have interesting state. RAID0 or Linear
85 never have missing, spare, or failed drives, so there is nothing
86 to monitor.
87 Grow Grow (or shrink) an array, or otherwise reshape it in some way.
90 Currently supported growth options including changing the active
91 size of component devices and changing the number of active
92 devices in Linear and RAID levels 0/1/4/5/6, changing the RAID
93 level between 0, 1, 5, and 6, and between 0 and 10, changing the
94 chunk size and layout for RAID 0,4,5,6,10 as well as adding or
95 removing a write-intent bitmap.
96 Incremental Assembly
99 Add a single device to an appropriate array. If the addition of
100 the device makes the array runnable, the array will be started.
101 This provides a convenient interface to a hot-plug system. As
102 each device is detected, mdadm has a chance to include it in
103 some array as appropriate. Optionally, when the --fail flag is
104 passed in we will remove the device from any active array
105 instead of adding it.
106 If a CONTAINER is passed to mdadm in this mode, then any arrays
108 within that container will be assembled and started.
109 Manage This is for doing things to specific components of an array such
112 as adding new spares and removing faulty devices.
113 Misc This is an 'everything else' mode that supports operations on
116 active arrays, operations on component devices such as erasing
117 old superblocks, and information gathering operations.
118 Auto-detect
121 This mode does not act on a specific device or array, but rather
122 it requests the Linux Kernel to activate any auto-detected
123 arrays.
124
127 -A, --assemble
128 Assemble a pre-existing array.
129 -B, --build
132 Build a legacy array without superblocks.
133 -C, --create
136 Create a new array.
137 -F, --follow, --monitor
140 Select Monitor mode.
141 -G, --grow
144 Change the size or shape of an active array.
145 -I, --incremental
148 Add/remove a single device to/from an appropriate array, and
149 possibly start the array.
150 --auto-detect
153 Request that the kernel starts any auto-detected arrays. This
154 can only work if md is compiled into the kernel — not if it is a
155 module. Arrays can be auto-detected by the kernel if all the
156 components are in primary MS-DOS partitions with partition type
157 FD, and all use v0.90 metadata. In-kernel autodetect is not
158 recommended for new installations. Using mdadm to detect and
159 assemble arrays — possibly in an initrd — is substantially more
160 flexible and should be preferred.
161 If a device is given before any options, or if the first option is one
164 of --add, --re-add, --add-spare, --fail, --remove, or --replace, then
165 the MANAGE mode is assumed. Anything other than these will cause the
166 Misc mode to be assumed.
167
170 -h, --help
171 Display general help message or, after one of the above options,
172 a mode-specific help message.
173 --help-options
176 Display more detailed help about command line parsing and some
177 commonly used options.
178 -V, --version
181 Print version information for mdadm.
182 -v, --verbose
185 Be more verbose about what is happening. This can be used twice
186 to be extra-verbose. The extra verbosity currently only affects
187 --detail --scan and --examine --scan.
188 -q, --quiet
191 Avoid printing purely informative messages. With this, mdadm
192 will be silent unless there is something really important to
193 report.
194 -f, --force
198 Be more forceful about certain operations. See the various
199 modes for the exact meaning of this option in different con‐
200 texts.
201 -c, --config=
204 Specify the config file or directory. Default is to use
205 /etc/mdadm.conf and /etc/mdadm.conf.d, or if those are missing
206 then /etc/mdadm/mdadm.conf and /etc/mdadm/mdadm.conf.d. If the
207 config file given is partitions then nothing will be read, but
208 mdadm will act as though the config file contained exactly
209 DEVICE partitions containers
210 and will read /proc/partitions to find a list of devices to
211 scan, and /proc/mdstat to find a list of containers to examine.
212 If the word none is given for the config file, then mdadm will
213 act as though the config file were empty.
214 If the name given is of a directory, then mdadm will collect all
216 the files contained in the directory with a name ending in
217 .conf, sort them lexically, and process all of those files as
218 config files.
219 -s, --scan
222 Scan config file or /proc/mdstat for missing information. In
223 general, this option gives mdadm permission to get any missing
224 information (like component devices, array devices, array iden‐
225 tities, and alert destination) from the configuration file (see
226 previous option); one exception is MISC mode when using --detail
227 or --stop, in which case --scan says to get a list of array
228 devices from /proc/mdstat.
229 -e, --metadata=
232 Declare the style of RAID metadata (superblock) to be used. The
233 default is 1.2 for --create, and to guess for other operations.
234 The default can be overridden by setting the metadata value for
235 the CREATE keyword in mdadm.conf.
236 Options are:
238 0, 0.90
241 Use the original 0.90 format superblock. This format
242 limits arrays to 28 component devices and limits compo‐
243 nent devices of levels 1 and greater to 2 terabytes. It
244 is also possible for there to be confusion about whether
245 the superblock applies to a whole device or just the last
246 partition, if that partition starts on a 64K boundary.
247 1, 1.0, 1.1, 1.2 default
250 Use the new version-1 format superblock. This has fewer
251 restrictions. It can easily be moved between hosts with
252 different endian-ness, and a recovery operation can be
253 checkpointed and restarted. The different sub-versions
254 store the superblock at different locations on the
255 device, either at the end (for 1.0), at the start (for
256 1.1) or 4K from the start (for 1.2). "1" is equivalent
257 to "1.2" (the commonly preferred 1.x format). "default"
258 is equivalent to "1.2".
259 ddf Use the "Industry Standard" DDF (Disk Data Format) format
261 defined by SNIA. When creating a DDF array a CONTAINER
262 will be created, and normal arrays can be created in that
263 container.
264 imsm Use the Intel(R) Matrix Storage Manager metadata format.
266 This creates a CONTAINER which is managed in a similar
267 manner to DDF, and is supported by an option-rom on some
268 platforms:
269 http://www.intel.com/design/chipsets/matrixstorage_sb.htm
271 --homehost=
273 This will override any HOMEHOST setting in the config file and
274 provides the identity of the host which should be considered the
275 home for any arrays.
276 When creating an array, the homehost will be recorded in the
278 metadata. For version-1 superblocks, it will be prefixed to the
279 array name. For version-0.90 superblocks, part of the SHA1 hash
280 of the hostname will be stored in the later half of the UUID.
281 When reporting information about an array, any array which is
283 tagged for the given homehost will be reported as such.
284 When using Auto-Assemble, only arrays tagged for the given home‐
286 host will be allowed to use 'local' names (i.e. not ending in
287 '_' followed by a digit string). See below under Auto Assembly.
288 The special name "any" can be used as a wild card. If an array
290 is created with --homehost=any then the name "any" will be
291 stored in the array and it can be assembled in the same way on
292 any host. If an array is assembled with this option, then the
293 homehost recorded on the array will be ignored.
294 --prefer=
297 When mdadm needs to print the name for a device it normally
298 finds the name in /dev which refers to the device and is short‐
299 est. When a path component is given with --prefer mdadm will
300 prefer a longer name if it contains that component. For example
301 --prefer=by-uuid will prefer a name in a subdirectory of /dev
302 called by-uuid.
303 This functionality is currently only provided by --detail and
305 --monitor.
306
309 -n, --raid-devices=
310 Specify the number of active devices in the array. This, plus
311 the number of spare devices (see below) must equal the number of
312 component-devices (including "missing" devices) that are listed
313 on the command line for --create. Setting a value of 1 is prob‐
314 ably a mistake and so requires that --force be specified first.
315 A value of 1 will then be allowed for linear, multipath, RAID0
316 and RAID1. It is never allowed for RAID4, RAID5 or RAID6.
317 This number can only be changed using --grow for RAID1, RAID4,
318 RAID5 and RAID6 arrays, and only on kernels which provide the
319 necessary support.
320 -x, --spare-devices=
323 Specify the number of spare (eXtra) devices in the initial
324 array. Spares can also be added and removed later. The number
325 of component devices listed on the command line must equal the
326 number of RAID devices plus the number of spare devices.
327 -z, --size=
330 Amount (in Kibibytes) of space to use from each drive in RAID
331 levels 1/4/5/6. This must be a multiple of the chunk size, and
332 must leave about 128Kb of space at the end of the drive for the
333 RAID superblock. If this is not specified (as it normally is
334 not) the smallest drive (or partition) sets the size, though if
335 there is a variance among the drives of greater than 1%, a warn‐
336 ing is issued.
337 A suffix of 'M' or 'G' can be given to indicate Megabytes or
339 Gigabytes respectively.
340 Sometimes a replacement drive can be a little smaller than the
342 original drives though this should be minimised by IDEMA stan‐
343 dards. Such a replacement drive will be rejected by md. To
344 guard against this it can be useful to set the initial size
345 slightly smaller than the smaller device with the aim that it
346 will still be larger than any replacement.
347 This value can be set with --grow for RAID level 1/4/5/6 though
349 CONTAINER based arrays such as those with IMSM metadata may not
350 be able to support this. If the array was created with a size
351 smaller than the currently active drives, the extra space can be
352 accessed using --grow. The size can be given as max which means
353 to choose the largest size that fits on all current drives.
354 Before reducing the size of the array (with --grow --size=) you
356 should make sure that space isn't needed. If the device holds a
357 filesystem, you would need to resize the filesystem to use less
358 space.
359 After reducing the array size you should check that the data
361 stored in the device is still available. If the device holds a
362 filesystem, then an 'fsck' of the filesystem is a minimum
363 requirement. If there are problems the array can be made bigger
364 again with no loss with another --grow --size= command.
365 This value cannot be used when creating a CONTAINER such as with
367 DDF and IMSM metadata, though it perfectly valid when creating
368 an array inside a container.
369 -Z, --array-size=
372 This is only meaningful with --grow and its effect is not per‐
373 sistent: when the array is stopped and restarted the default
374 array size will be restored.
375 Setting the array-size causes the array to appear smaller to
377 programs that access the data. This is particularly needed
378 before reshaping an array so that it will be smaller. As the
379 reshape is not reversible, but setting the size with --array-
380 size is, it is required that the array size is reduced as appro‐
381 priate before the number of devices in the array is reduced.
382 Before reducing the size of the array you should make sure that
384 space isn't needed. If the device holds a filesystem, you would
385 need to resize the filesystem to use less space.
386 After reducing the array size you should check that the data
388 stored in the device is still available. If the device holds a
389 filesystem, then an 'fsck' of the filesystem is a minimum
390 requirement. If there are problems the array can be made bigger
391 again with no loss with another --grow --array-size= command.
392 A suffix of 'M' or 'G' can be given to indicate Megabytes or
394 Gigabytes respectively. A value of max restores the apparent
395 size of the array to be whatever the real amount of available
396 space is.
397 -c, --chunk=
400 Specify chunk size of kibibytes. The default when creating an
401 array is 512KB. To ensure compatibility with earlier versions,
402 the default when building an array with no persistent metadata
403 is 64KB. This is only meaningful for RAID0, RAID4, RAID5,
404 RAID6, and RAID10.
405 RAID4, RAID5, RAID6, and RAID10 require the chunk size to be a
407 power of 2. In any case it must be a multiple of 4KB.
408 A suffix of 'M' or 'G' can be given to indicate Megabytes or
410 Gigabytes respectively.
411 --rounding=
414 Specify rounding factor for a Linear array. The size of each
415 component will be rounded down to a multiple of this size. This
416 is a synonym for --chunk but highlights the different meaning
417 for Linear as compared to other RAID levels. The default is 64K
418 if a kernel earlier than 2.6.16 is in use, and is 0K (i.e. no
419 rounding) in later kernels.
420 -l, --level=
423 Set RAID level. When used with --create, options are: linear,
424 raid0, 0, stripe, raid1, 1, mirror, raid4, 4, raid5, 5, raid6,
425 6, raid10, 10, multipath, mp, faulty, container. Obviously some
426 of these are synonymous.
427 When a CONTAINER metadata type is requested, only the container
429 level is permitted, and it does not need to be explicitly given.
430 When used with --build, only linear, stripe, raid0, 0, raid1,
432 multipath, mp, and faulty are valid.
433 Can be used with --grow to change the RAID level in some cases.
435 See LEVEL CHANGES below.
436 -p, --layout=
439 This option configures the fine details of data layout for
440 RAID5, RAID6, and RAID10 arrays, and controls the failure modes
441 for faulty.
442 The layout of the RAID5 parity block can be one of left-asymmet‐
444 ric, left-symmetric, right-asymmetric, right-symmetric, la, ra,
445 ls, rs. The default is left-symmetric.
446 It is also possible to cause RAID5 to use a RAID4-like layout by
448 choosing parity-first, or parity-last.
449 Finally for RAID5 there are DDF-compatible layouts,
451 ddf-zero-restart, ddf-N-restart, and ddf-N-continue.
452 These same layouts are available for RAID6. There are also 4
454 layouts that will provide an intermediate stage for converting
455 between RAID5 and RAID6. These provide a layout which is iden‐
456 tical to the corresponding RAID5 layout on the first N-1
457 devices, and has the 'Q' syndrome (the second 'parity' block
458 used by RAID6) on the last device. These layouts are: left-sym‐
459 metric-6, right-symmetric-6, left-asymmetric-6, right-asymmet‐
460 ric-6, and parity-first-6.
461 When setting the failure mode for level faulty, the options are:
463 write-transient, wt, read-transient, rt, write-persistent, wp,
464 read-persistent, rp, write-all, read-fixable, rf, clear, flush,
465 none.
466 Each failure mode can be followed by a number, which is used as
468 a period between fault generation. Without a number, the fault
469 is generated once on the first relevant request. With a number,
470 the fault will be generated after that many requests, and will
471 continue to be generated every time the period elapses.
472 Multiple failure modes can be current simultaneously by using
474 the --grow option to set subsequent failure modes.
475 "clear" or "none" will remove any pending or periodic failure
477 modes, and "flush" will clear any persistent faults.
478 Finally, the layout options for RAID10 are one of 'n', 'o' or
480 'f' followed by a small number. The default is 'n2'. The sup‐
481 ported options are:
482 'n' signals 'near' copies. Multiple copies of one data block
484 are at similar offsets in different devices.
485 'o' signals 'offset' copies. Rather than the chunks being
487 duplicated within a stripe, whole stripes are duplicated but are
488 rotated by one device so duplicate blocks are on different
489 devices. Thus subsequent copies of a block are in the next
490 drive, and are one chunk further down.
491 'f' signals 'far' copies (multiple copies have very different
493 offsets). See md(4) for more detail about 'near', 'offset', and
494 'far'.
495 The number is the number of copies of each datablock. 2 is nor‐
497 mal, 3 can be useful. This number can be at most equal to the
498 number of devices in the array. It does not need to divide
499 evenly into that number (e.g. it is perfectly legal to have an
500 'n2' layout for an array with an odd number of devices).
501 When an array is converted between RAID5 and RAID6 an intermedi‐
503 ate RAID6 layout is used in which the second parity block (Q) is
504 always on the last device. To convert a RAID5 to RAID6 and
505 leave it in this new layout (which does not require re-striping)
506 use --layout=preserve. This will try to avoid any restriping.
507 The converse of this is --layout=normalise which will change a
509 non-standard RAID6 layout into a more standard arrangement.
510 --parity=
513 same as --layout (thus explaining the p of -p).
514 -b, --bitmap=
517 Specify a file to store a write-intent bitmap in. The file
518 should not exist unless --force is also given. The same file
519 should be provided when assembling the array. If the word
520 internal is given, then the bitmap is stored with the metadata
521 on the array, and so is replicated on all devices. If the word
522 none is given with --grow mode, then any bitmap that is present
523 is removed.
524 To help catch typing errors, the filename must contain at least
526 one slash ('/') if it is a real file (not 'internal' or 'none').
527 Note: external bitmaps are only known to work on ext2 and ext3.
529 Storing bitmap files on other filesystems may result in serious
530 problems.
531 When creating an array on devices which are 100G or larger,
533 mdadm automatically adds an internal bitmap as it will usually
534 be beneficial. This can be suppressed with --bitmap=none .
535 --bitmap-chunk=
538 Set the chunksize of the bitmap. Each bit corresponds to that
539 many Kilobytes of storage. When using a file based bitmap, the
540 default is to use the smallest size that is at-least 4 and
541 requires no more than 2^21 chunks. When using an internal bit‐
542 map, the chunksize defaults to 64Meg, or larger if necessary to
543 fit the bitmap into the available space.
544 A suffix of 'M' or 'G' can be given to indicate Megabytes or
546 Gigabytes respectively.
547 -W, --write-mostly
550 subsequent devices listed in a --build, --create, or --add com‐
551 mand will be flagged as 'write-mostly'. This is valid for RAID1
552 only and means that the 'md' driver will avoid reading from
553 these devices if at all possible. This can be useful if mirror‐
554 ing over a slow link.
555 --write-behind=
558 Specify that write-behind mode should be enabled (valid for
559 RAID1 only). If an argument is specified, it will set the maxi‐
560 mum number of outstanding writes allowed. The default value is
561 256. A write-intent bitmap is required in order to use write-
562 behind mode, and write-behind is only attempted on drives marked
563 as write-mostly.
564 --assume-clean
567 Tell mdadm that the array pre-existed and is known to be clean.
568 It can be useful when trying to recover from a major failure as
569 you can be sure that no data will be affected unless you actu‐
570 ally write to the array. It can also be used when creating a
571 RAID1 or RAID10 if you want to avoid the initial resync, however
572 this practice — while normally safe — is not recommended. Use
573 this only if you really know what you are doing.
574 When the devices that will be part of a new array were filled
576 with zeros before creation the operator knows the array is actu‐
577 ally clean. If that is the case, such as after running bad‐
578 blocks, this argument can be used to tell mdadm the facts the
579 operator knows.
580 When an array is resized to a larger size with --grow --size=
582 the new space is normally resynced in that same way that the
583 whole array is resynced at creation. From Linux version 3.0,
584 --assume-clean can be used with that command to avoid the auto‐
585 matic resync.
586 --backup-file=
589 This is needed when --grow is used to increase the number of
590 raid-devices in a RAID5 or RAID6 if there are no spare devices
591 available, or to shrink, change RAID level or layout. See the
592 GROW MODE section below on RAID-DEVICES CHANGES. The file must
593 be stored on a separate device, not on the RAID array being
594 reshaped.
595 --data-offset=
598 Arrays with 1.x metadata can leave a gap between the start of
599 the device and the start of array data. This gap can be used
600 for various metadata. The start of data is known as the
601 data-offset. Normally an appropriate data offset is computed
602 automatically. However it can be useful to set it explicitly
603 such as when re-creating an array which was originally created
604 using a different version of mdadm which computed a different
605 offset.
606 Setting the offset explicitly over-rides the default. The value
608 given is in Kilobytes unless an 'M' or 'G' suffix is given.
609 Since Linux 3.4, --data-offset can also be used with --grow for
611 some RAID levels (initially on RAID10). This allows the
612 data-offset to be changed as part of the reshape process. When
613 the data offset is changed, no backup file is required as the
614 difference in offsets is used to provide the same functionality.
615 When the new offset is earlier than the old offset, the number
617 of devices in the array cannot shrink. When it is after the old
618 offset, the number of devices in the array cannot increase.
619 When creating an array, --data-offset can be specified as vari‐
621 able. In the case each member device is expected to have a off‐
622 set appended to the name, separated by a colon. This makes it
623 possible to recreate exactly an array which has varying data
624 offsets (as can happen when different versions of mdadm are used
625 to add different devices).
626 --continue
629 This option is complementary to the --freeze-reshape option for
630 assembly. It is needed when --grow operation is interrupted and
631 it is not restarted automatically due to --freeze-reshape usage
632 during array assembly. This option is used together with -G , (
633 --grow ) command and device for a pending reshape to be contin‐
634 ued. All parameters required for reshape continuation will be
635 read from array metadata. If initial --grow command had
636 required --backup-file= option to be set, continuation option
637 will require to have exactly the same backup file given as well.
638 Any other parameter passed together with --continue option will
640 be ignored.
641 -N, --name=
644 Set a name for the array. This is currently only effective when
645 creating an array with a version-1 superblock, or an array in a
646 DDF container. The name is a simple textual string that can be
647 used to identify array components when assembling. If name is
648 needed but not specified, it is taken from the basename of the
649 device that is being created. e.g. when creating /dev/md/home
650 the name will default to home.
651 -R, --run
654 Insist that mdadm run the array, even if some of the components
655 appear to be active in another array or filesystem. Normally
656 mdadm will ask for confirmation before including such components
657 in an array. This option causes that question to be suppressed.
658 -f, --force
661 Insist that mdadm accept the geometry and layout specified with‐
662 out question. Normally mdadm will not allow creation of an
663 array with only one device, and will try to create a RAID5 array
664 with one missing drive (as this makes the initial resync work
665 faster). With --force, mdadm will not try to be so clever.
666 -o, --readonly
669 Start the array read only rather than read-write as normal. No
670 writes will be allowed to the array, and no resync, recovery, or
671 reshape will be started.
672 -a, --auto{=yes,md,mdp,part,p}{NN}
675 Instruct mdadm how to create the device file if needed, possibly
676 allocating an unused minor number. "md" causes a non-partition‐
677 able array to be used (though since Linux 2.6.28, these array
678 devices are in fact partitionable). "mdp", "part" or "p" causes
679 a partitionable array (2.6 and later) to be used. "yes"
680 requires the named md device to have a 'standard' format, and
681 the type and minor number will be determined from this. With
682 mdadm 3.0, device creation is normally left up to udev so this
683 option is unlikely to be needed. See DEVICE NAMES below.
684 The argument can also come immediately after "-a". e.g. "-ap".
686 If --auto is not given on the command line or in the config
688 file, then the default will be --auto=yes.
689 If --scan is also given, then any auto= entries in the config
691 file will override the --auto instruction given on the command
692 line.
693 For partitionable arrays, mdadm will create the device file for
695 the whole array and for the first 4 partitions. A different
696 number of partitions can be specified at the end of this option
697 (e.g. --auto=p7). If the device name ends with a digit, the
698 partition names add a 'p', and a number, e.g. /dev/md/home1p3.
699 If there is no trailing digit, then the partition names just
700 have a number added, e.g. /dev/md/scratch3.
701 If the md device name is in a 'standard' format as described in
703 DEVICE NAMES, then it will be created, if necessary, with the
704 appropriate device number based on that name. If the device
705 name is not in one of these formats, then a unused device number
706 will be allocated. The device number will be considered unused
707 if there is no active array for that number, and there is no
708 entry in /dev for that number and with a non-standard name.
709 Names that are not in 'standard' format are only allowed in
710 "/dev/md/".
711 This is meaningful with --create or --build.
713 -a, --add
716 This option can be used in Grow mode in two cases.
717 If the target array is a Linear array, then --add can be used to
719 add one or more devices to the array. They are simply catenated
720 on to the end of the array. Once added, the devices cannot be
721 removed.
722 If the --raid-disks option is being used to increase the number
724 of devices in an array, then --add can be used to add some extra
725 devices to be included in the array. In most cases this is not
726 needed as the extra devices can be added as spares first, and
727 then the number of raid-disks can be changed. However for
728 RAID0, it is not possible to add spares. So to increase the
729 number of devices in a RAID0, it is necessary to set the new
730 number of devices, and to add the new devices, in the same com‐
731 mand.
732
735 -u, --uuid=
736 uuid of array to assemble. Devices which don't have this uuid
737 are excluded
738 -m, --super-minor=
741 Minor number of device that array was created for. Devices
742 which don't have this minor number are excluded. If you create
743 an array as /dev/md1, then all superblocks will contain the
744 minor number 1, even if the array is later assembled as
745 /dev/md2.
746 Giving the literal word "dev" for --super-minor will cause mdadm
748 to use the minor number of the md device that is being assem‐
749 bled. e.g. when assembling /dev/md0, --super-minor=dev will
750 look for super blocks with a minor number of 0.
751 --super-minor is only relevant for v0.90 metadata, and should
753 not normally be used. Using --uuid is much safer.
754 -N, --name=
757 Specify the name of the array to assemble. This must be the
758 name that was specified when creating the array. It must either
759 match the name stored in the superblock exactly, or it must
760 match with the current homehost prefixed to the start of the
761 given name.
762 -f, --force
765 Assemble the array even if the metadata on some devices appears
766 to be out-of-date. If mdadm cannot find enough working devices
767 to start the array, but can find some devices that are recorded
768 as having failed, then it will mark those devices as working so
769 that the array can be started. An array which requires --force
770 to be started may contain data corruption. Use it carefully.
771 -R, --run
774 Attempt to start the array even if fewer drives were given than
775 were present last time the array was active. Normally if not
776 all the expected drives are found and --scan is not used, then
777 the array will be assembled but not started. With --run an
778 attempt will be made to start it anyway.
779 --no-degraded
782 This is the reverse of --run in that it inhibits the startup of
783 array unless all expected drives are present. This is only
784 needed with --scan, and can be used if the physical connections
785 to devices are not as reliable as you would like.
786 -a, --auto{=no,yes,md,mdp,part}
789 See this option under Create and Build options.
790 -b, --bitmap=
793 Specify the bitmap file that was given when the array was cre‐
794 ated. If an array has an internal bitmap, there is no need to
795 specify this when assembling the array.
796 --backup-file=
799 If --backup-file was used while reshaping an array (e.g. chang‐
800 ing number of devices or chunk size) and the system crashed dur‐
801 ing the critical section, then the same --backup-file must be
802 presented to --assemble to allow possibly corrupted data to be
803 restored, and the reshape to be completed.
804 --invalid-backup
807 If the file needed for the above option is not available for any
808 reason an empty file can be given together with this option to
809 indicate that the backup file is invalid. In this case the data
810 that was being rearranged at the time of the crash could be
811 irrecoverably lost, but the rest of the array may still be
812 recoverable. This option should only be used as a last resort
813 if there is no way to recover the backup file.
814 -U, --update=
818 Update the superblock on each device while assembling the array.
819 The argument given to this flag can be one of sparc2.2, sum‐
820 maries, uuid, name, homehost, resync, byteorder, devicesize,
821 no-bitmap, bbl, no-bbl, metadata, or super-minor.
822 The sparc2.2 option will adjust the superblock of an array what
824 was created on a Sparc machine running a patched 2.2 Linux ker‐
825 nel. This kernel got the alignment of part of the superblock
826 wrong. You can use the --examine --sparc2.2 option to mdadm to
827 see what effect this would have.
828 The super-minor option will update the preferred minor field on
830 each superblock to match the minor number of the array being
831 assembled. This can be useful if --examine reports a different
832 "Preferred Minor" to --detail. In some cases this update will
833 be performed automatically by the kernel driver. In particular
834 the update happens automatically at the first write to an array
835 with redundancy (RAID level 1 or greater) on a 2.6 (or later)
836 kernel.
837 The uuid option will change the uuid of the array. If a UUID is
839 given with the --uuid option that UUID will be used as a new
840 UUID and will NOT be used to help identify the devices in the
841 array. If no --uuid is given, a random UUID is chosen.
842 The name option will change the name of the array as stored in
844 the superblock. This is only supported for version-1
845 superblocks.
846 The homehost option will change the homehost as recorded in the
848 superblock. For version-0 superblocks, this is the same as
849 updating the UUID. For version-1 superblocks, this involves
850 updating the name.
851 The resync option will cause the array to be marked dirty mean‐
853 ing that any redundancy in the array (e.g. parity for RAID5,
854 copies for RAID1) may be incorrect. This will cause the RAID
855 system to perform a "resync" pass to make sure that all redun‐
856 dant information is correct.
857 The byteorder option allows arrays to be moved between machines
859 with different byte-order. When assembling such an array for
860 the first time after a move, giving --update=byteorder will
861 cause mdadm to expect superblocks to have their byteorder
862 reversed, and will correct that order before assembling the
863 array. This is only valid with original (Version 0.90)
864 superblocks.
865 The summaries option will correct the summaries in the
867 superblock. That is the counts of total, working, active,
868 failed, and spare devices.
869 The devicesize option will rarely be of use. It applies to ver‐
871 sion 1.1 and 1.2 metadata only (where the metadata is at the
872 start of the device) and is only useful when the component
873 device has changed size (typically become larger). The version
874 1 metadata records the amount of the device that can be used to
875 store data, so if a device in a version 1.1 or 1.2 array becomes
876 larger, the metadata will still be visible, but the extra space
877 will not. In this case it might be useful to assemble the array
878 with --update=devicesize. This will cause mdadm to determine
879 the maximum usable amount of space on each device and update the
880 relevant field in the metadata.
881 The metadata option only works on v0.90 metadata arrays and will
883 convert them to v1.0 metadata. The array must not be dirty
884 (i.e. it must not need a sync) and it must not have a write-
885 intent bitmap.
886 The old metadata will remain on the devices, but will appear
888 older than the new metadata and so will usually be ignored. The
889 old metadata (or indeed the new metadata) can be removed by giv‐
890 ing the appropriate --metadata= option to --zero-superblock.
891 The no-bitmap option can be used when an array has an internal
893 bitmap which is corrupt in some way so that assembling the array
894 normally fails. It will cause any internal bitmap to be
895 ignored.
896 The bbl option will reserve space in each device for a bad block
898 list. This will be 4K in size and positioned near the end of
899 any free space between the superblock and the data.
900 The no-bbl option will cause any reservation of space for a bad
902 block list to be removed. If the bad block list contains
903 entries, this will fail, as removing the list could cause data
904 corruption.
905 --freeze-reshape
908 Option is intended to be used in start-up scripts during initrd
909 boot phase. When array under reshape is assembled during initrd
910 phase, this option stops reshape after reshape critical section
911 is being restored. This happens before file system pivot opera‐
912 tion and avoids loss of file system context. Losing file system
913 context would cause reshape to be broken.
914 Reshape can be continued later using the --continue option for
916 the grow command.
917
920 -t, --test
921 Unless a more serious error occurred, mdadm will exit with a
922 status of 2 if no changes were made to the array and 0 if at
923 least one change was made. This can be useful when an indirect
924 specifier such as missing, detached or faulty is used in
925 requesting an operation on the array. --test will report fail‐
926 ure if these specifiers didn't find any match.
927 -a, --add
930 hot-add listed devices. If a device appears to have recently
931 been part of the array (possibly it failed or was removed) the
932 device is re-added as described in the next point. If that
933 fails or the device was never part of the array, the device is
934 added as a hot-spare. If the array is degraded, it will immedi‐
935 ately start to rebuild data onto that spare.
936 Note that this and the following options are only meaningful on
938 array with redundancy. They don't apply to RAID0 or Linear.
939 --re-add
942 re-add a device that was previously removed from an array. If
943 the metadata on the device reports that it is a member of the
944 array, and the slot that it used is still vacant, then the
945 device will be added back to the array in the same position.
946 This will normally cause the data for that device to be recov‐
947 ered. However based on the event count on the device, the
948 recovery may only require sections that are flagged a write-
949 intent bitmap to be recovered or may not require any recovery at
950 all.
951 When used on an array that has no metadata (i.e. it was built
953 with --build) it will be assumed that bitmap-based recovery is
954 enough to make the device fully consistent with the array.
955 When used with v1.x metadata, --re-add can be accompanied by
957 --update=devicesize, --update=bbl, or --update=no-bbl. See the
958 description of these option when used in Assemble mode for an
959 explanation of their use.
960 If the device name given is missing then mdadm will try to find
962 any device that looks like it should be part of the array but
963 isn't and will try to re-add all such devices.
964 If the device name given is faulty then mdadm will find all
966 devices in the array that are marked faulty, remove them and
967 attempt to immediately re-add them. This can be useful if you
968 are certain that the reason for failure has been resolved.
969 --add-spare
972 Add a device as a spare. This is similar to --add except that
973 it does not attempt --re-add first. The device will be added as
974 a spare even if it looks like it could be an recent member of
975 the array.
976 -r, --remove
979 remove listed devices. They must not be active. i.e. they
980 should be failed or spare devices.
981 As well as the name of a device file (e.g. /dev/sda1) the words
983 failed, detached and names like set-A can be given to --remove.
984 The first causes all failed device to be removed. The second
985 causes any device which is no longer connected to the system
986 (i.e an 'open' returns ENXIO) to be removed. The third will
987 remove a set as describe below under --fail.
988 -f, --fail
991 Mark listed devices as faulty. As well as the name of a device
992 file, the word detached or a set name like set-A can be given.
993 The former will cause any device that has been detached from the
994 system to be marked as failed. It can then be removed.
995 For RAID10 arrays where the number of copies evenly divides the
997 number of devices, the devices can be conceptually divided into
998 sets where each set contains a single complete copy of the data
999 on the array. Sometimes a RAID10 array will be configured so
1000 that these sets are on separate controllers. In this case all
1001 the devices in one set can be failed by giving a name like set-A
1002 or set-B to --fail. The appropriate set names are reported by
1003 --detail.
1004 --set-faulty
1007 same as --fail.
1008 --replace
1011 Mark listed devices as requiring replacement. As soon as a
1012 spare is available, it will be rebuilt and will replace the
1013 marked device. This is similar to marking a device as faulty,
1014 but the device remains in service during the recovery process to
1015 increase resilience against multiple failures. When the
1016 replacement process finishes, the replaced device will be marked
1017 as faulty.
1018 --with This can follow a list of --replace devices. The devices listed
1021 after --with will be preferentially used to replace the devices
1022 listed after --replace. These device must already be spare
1023 devices in the array.
1024 --write-mostly
1027 Subsequent devices that are added or re-added will have the
1028 'write-mostly' flag set. This is only valid for RAID1 and means
1029 that the 'md' driver will avoid reading from these devices if
1030 possible.
1031 --readwrite
1033 Subsequent devices that are added or re-added will have the
1034 'write-mostly' flag cleared.
1035 Each of these options requires that the first device listed is the
1038 array to be acted upon, and the remainder are component devices to be
1039 added, removed, marked as faulty, etc. Several different operations
1040 can be specified for different devices, e.g.
1041 mdadm /dev/md0 --add /dev/sda1 --fail /dev/sdb1 --remove /dev/sdb1
1042 Each operation applies to all devices listed until the next operation.
1043 If an array is using a write-intent bitmap, then devices which have
1045 been removed can be re-added in a way that avoids a full reconstruction
1046 but instead just updates the blocks that have changed since the device
1047 was removed. For arrays with persistent metadata (superblocks) this is
1048 done automatically. For arrays created with --build mdadm needs to be
1049 told that this device we removed recently with --re-add.
1050 Devices can only be removed from an array if they are not in active
1052 use, i.e. that must be spares or failed devices. To remove an active
1053 device, it must first be marked as faulty.
1054
1057 -Q, --query
1058 Examine a device to see (1) if it is an md device and (2) if it
1059 is a component of an md array. Information about what is dis‐
1060 covered is presented.
1061 -D, --detail
1064 Print details of one or more md devices.
1065 --detail-platform
1068 Print details of the platform's RAID capabilities (firmware /
1069 hardware topology) for a given metadata format. If used without
1070 argument, mdadm will scan all controllers looking for their
1071 capabilities. Otherwise, mdadm will only look at the controller
1072 specified by the argument in form of an absolute filepath or a
1073 link, e.g. /sys/devices/pci0000:00/0000:00:1f.2.
1074 -Y, --export
1077 When used with --detail, --detail-platform, --examine, or
1078 --incremental output will be formatted as key=value pairs for
1079 easy import into the environment.
1080 With --incremental The value MD_STARTED indicates whether an
1082 array was started (yes) or not, which may include a reason
1083 (unsafe, nothing, no). Also the value MD_FOREIGN indicates if
1084 the array is expected on this host (no), or seems to be from
1085 elsewhere (yes).
1086 -E, --examine
1089 Print contents of the metadata stored on the named device(s).
1090 Note the contrast between --examine and --detail. --examine
1091 applies to devices which are components of an array, while
1092 --detail applies to a whole array which is currently active.
1093 --sparc2.2
1095 If an array was created on a SPARC machine with a 2.2 Linux ker‐
1096 nel patched with RAID support, the superblock will have been
1097 created incorrectly, or at least incompatibly with 2.4 and later
1098 kernels. Using the --sparc2.2 flag with --examine will fix the
1099 superblock before displaying it. If this appears to do the
1100 right thing, then the array can be successfully assembled using
1101 --assemble --update=sparc2.2.
1102 -X, --examine-bitmap
1105 Report information about a bitmap file. The argument is either
1106 an external bitmap file or an array component in case of an
1107 internal bitmap. Note that running this on an array device
1108 (e.g. /dev/md0) does not report the bitmap for that array.
1109 --examine-badblocks
1112 List the bad-blocks recorded for the device, if a bad-blocks
1113 list has been configured. Currently only 1.x metadata supports
1114 bad-blocks lists.
1115 --dump=directory
1118 --restore=directory
1120 Save metadata from lists devices, or restore metadata to listed
1121 devices.
1122 -R, --run
1125 start a partially assembled array. If --assemble did not find
1126 enough devices to fully start the array, it might leaving it
1127 partially assembled. If you wish, you can then use --run to
1128 start the array in degraded mode.
1129 -S, --stop
1132 deactivate array, releasing all resources.
1133 -o, --readonly
1136 mark array as readonly.
1137 -w, --readwrite
1140 mark array as readwrite.
1141 --zero-superblock
1144 If the device contains a valid md superblock, the block is over‐
1145 written with zeros. With --force the block where the superblock
1146 would be is overwritten even if it doesn't appear to be valid.
1147 --kill-subarray=
1150 If the device is a container and the argument to --kill-subarray
1151 specifies an inactive subarray in the container, then the subar‐
1152 ray is deleted. Deleting all subarrays will leave an 'empty-
1153 container' or spare superblock on the drives. See
1154 --zero-superblock for completely removing a superblock. Note
1155 that some formats depend on the subarray index for generating a
1156 UUID, this command will fail if it would change the UUID of an
1157 active subarray.
1158 --update-subarray=
1161 If the device is a container and the argument to --update-subar‐
1162 ray specifies a subarray in the container, then attempt to
1163 update the given superblock field in the subarray. See below in
1164 MISC MODE for details.
1165 -t, --test
1168 When used with --detail, the exit status of mdadm is set to
1169 reflect the status of the device. See below in MISC MODE for
1170 details.
1171 -W, --wait
1174 For each md device given, wait for any resync, recovery, or
1175 reshape activity to finish before returning. mdadm will return
1176 with success if it actually waited for every device listed, oth‐
1177 erwise it will return failure.
1178 --wait-clean
1181 For each md device given, or each device in /proc/mdstat if
1182 --scan is given, arrange for the array to be marked clean as
1183 soon as possible. mdadm will return with success if the array
1184 uses external metadata and we successfully waited. For native
1185 arrays this returns immediately as the kernel handles dirty-
1186 clean transitions at shutdown. No action is taken if safe-mode
1187 handling is disabled.
1188 --action=
1191 Set the "sync_action" for all md devices given to one of idle,
1192 frozen, check, repair. Setting to idle will abort any currently
1193 running action though some actions will automatically restart.
1194 Setting to frozen will abort any current action and ensure no
1195 other action starts automatically.
1196 Details of check and repair can be found it md(4) under SCRUB‐
1198 BING AND MISMATCHES.
1199
1202 --rebuild-map, -r
1203 Rebuild the map file (/dev/md/md-device-map) that mdadm uses to
1204 help track which arrays are currently being assembled.
1205 --run, -R
1208 Run any array assembled as soon as a minimal number of devices
1209 are available, rather than waiting until all expected devices
1210 are present.
1211 --scan, -s
1214 Only meaningful with -R this will scan the map file for arrays
1215 that are being incrementally assembled and will try to start any
1216 that are not already started. If any such array is listed in
1217 mdadm.conf as requiring an external bitmap, that bitmap will be
1218 attached first.
1219 --fail, -f
1222 This allows the hot-plug system to remove devices that have
1223 fully disappeared from the kernel. It will first fail and then
1224 remove the device from any array it belongs to. The device name
1225 given should be a kernel device name such as "sda", not a name
1226 in /dev.
1227 --path=
1230 Only used with --fail. The 'path' given will be recorded so
1231 that if a new device appears at the same location it can be
1232 automatically added to the same array. This allows the failed
1233 device to be automatically replaced by a new device without
1234 metadata if it appears at specified path. This option is nor‐
1235 mally only set by a udev script.
1236
1239 -m, --mail
1240 Give a mail address to send alerts to.
1241 -p, --program, --alert
1244 Give a program to be run whenever an event is detected.
1245 -y, --syslog
1248 Cause all events to be reported through 'syslog'. The messages
1249 have facility of 'daemon' and varying priorities.
1250 -d, --delay
1253 Give a delay in seconds. mdadm polls the md arrays and then
1254 waits this many seconds before polling again. The default is 60
1255 seconds. Since 2.6.16, there is no need to reduce this as the
1256 kernel alerts mdadm immediately when there is any change.
1257 -r, --increment
1260 Give a percentage increment. mdadm will generate RebuildNN
1261 events with the given percentage increment.
1262 -f, --daemonise
1265 Tell mdadm to run as a background daemon if it decides to moni‐
1266 tor anything. This causes it to fork and run in the child, and
1267 to disconnect from the terminal. The process id of the child is
1268 written to stdout. This is useful with --scan which will only
1269 continue monitoring if a mail address or alert program is found
1270 in the config file.
1271 -i, --pid-file
1274 When mdadm is running in daemon mode, write the pid of the dae‐
1275 mon process to the specified file, instead of printing it on
1276 standard output.
1277 -1, --oneshot
1280 Check arrays only once. This will generate NewArray events and
1281 more significantly DegradedArray and SparesMissing events. Run‐
1282 ning
1283 mdadm --monitor --scan -1
1284 from a cron script will ensure regular notification of any
1285 degraded arrays.
1286 -t, --test
1289 Generate a TestMessage alert for every array found at startup.
1290 This alert gets mailed and passed to the alert program. This
1291 can be used for testing that alert message do get through suc‐
1292 cessfully.
1293 --no-sharing
1296 This inhibits the functionality for moving spares between
1297 arrays. Only one monitoring process started with --scan but
1298 without this flag is allowed, otherwise the two could interfere
1299 with each other.
1300
1303 Usage: mdadm --assemble md-device options-and-component-devices...
1304 Usage: mdadm --assemble --scan md-devices-and-options...
1306 Usage: mdadm --assemble --scan options...
1308 This usage assembles one or more RAID arrays from pre-existing compo‐
1311 nents. For each array, mdadm needs to know the md device, the identity
1312 of the array, and a number of component-devices. These can be found in
1313 a number of ways.
1314 In the first usage example (without the --scan) the first device given
1316 is the md device. In the second usage example, all devices listed are
1317 treated as md devices and assembly is attempted. In the third (where
1318 no devices are listed) all md devices that are listed in the configura‐
1319 tion file are assembled. If no arrays are described by the configura‐
1320 tion file, then any arrays that can be found on unused devices will be
1321 assembled.
1322 If precisely one device is listed, but --scan is not given, then mdadm
1324 acts as though --scan was given and identity information is extracted
1325 from the configuration file.
1326 The identity can be given with the --uuid option, the --name option, or
1328 the --super-minor option, will be taken from the md-device record in
1329 the config file, or will be taken from the super block of the first
1330 component-device listed on the command line.
1331 Devices can be given on the --assemble command line or in the config
1333 file. Only devices which have an md superblock which contains the
1334 right identity will be considered for any array.
1335 The config file is only used if explicitly named with --config or
1337 requested with (a possibly implicit) --scan. In the later case,
1338 /etc/mdadm.conf or /etc/mdadm/mdadm.conf is used.
1339 If --scan is not given, then the config file will only be used to find
1341 the identity of md arrays.
1342 Normally the array will be started after it is assembled. However if
1344 --scan is not given and not all expected drives were listed, then the
1345 array is not started (to guard against usage errors). To insist that
1346 the array be started in this case (as may work for RAID1, 4, 5, 6, or
1347 10), give the --run flag.
1348 If udev is active, mdadm does not create any entries in /dev but leaves
1350 that to udev. It does record information in /dev/md/md-device-map
1351 which will allow udev to choose the correct name.
1352 If mdadm detects that udev is not configured, it will create the
1354 devices in /dev itself.
1355 In Linux kernels prior to version 2.6.28 there were two distinctly dif‐
1357 ferent types of md devices that could be created: one that could be
1358 partitioned using standard partitioning tools and one that could not.
1359 Since 2.6.28 that distinction is no longer relevant as both type of
1360 devices can be partitioned. mdadm will normally create the type that
1361 originally could not be partitioned as it has a well defined major num‐
1362 ber (9).
1363 Prior to 2.6.28, it is important that mdadm chooses the correct type of
1365 array device to use. This can be controlled with the --auto option.
1366 In particular, a value of "mdp" or "part" or "p" tells mdadm to use a
1367 partitionable device rather than the default.
1368 In the no-udev case, the value given to --auto can be suffixed by a
1370 number. This tells mdadm to create that number of partition devices
1371 rather than the default of 4.
1372 The value given to --auto can also be given in the configuration file
1374 as a word starting auto= on the ARRAY line for the relevant array.
1375 Auto Assembly
1378 When --assemble is used with --scan and no devices are listed, mdadm
1379 will first attempt to assemble all the arrays listed in the config
1380 file.
1381 If no arrays are listed in the config (other than those marked
1383 <ignore>) it will look through the available devices for possible
1384 arrays and will try to assemble anything that it finds. Arrays which
1385 are tagged as belonging to the given homehost will be assembled and
1386 started normally. Arrays which do not obviously belong to this host
1387 are given names that are expected not to conflict with anything local,
1388 and are started "read-auto" so that nothing is written to any device
1389 until the array is written to. i.e. automatic resync etc is delayed.
1390 If mdadm finds a consistent set of devices that look like they should
1392 comprise an array, and if the superblock is tagged as belonging to the
1393 given home host, it will automatically choose a device name and try to
1394 assemble the array. If the array uses version-0.90 metadata, then the
1395 minor number as recorded in the superblock is used to create a name in
1396 /dev/md/ so for example /dev/md/3. If the array uses version-1 meta‐
1397 data, then the name from the superblock is used to similarly create a
1398 name in /dev/md/ (the name will have any 'host' prefix stripped first).
1399 This behaviour can be modified by the AUTO line in the mdadm.conf con‐
1401 figuration file. This line can indicate that specific metadata type
1402 should, or should not, be automatically assembled. If an array is
1403 found which is not listed in mdadm.conf and has a metadata format that
1404 is denied by the AUTO line, then it will not be assembled. The AUTO
1405 line can also request that all arrays identified as being for this
1406 homehost should be assembled regardless of their metadata type. See
1407 mdadm.conf(5) for further details.
1408 Note: Auto assembly cannot be used for assembling and activating some
1410 arrays which are undergoing reshape. In particular as the backup-file
1411 cannot be given, any reshape which requires a backup-file to continue
1412 cannot be started by auto assembly. An array which is growing to more
1413 devices and has passed the critical section can be assembled using
1414 auto-assembly.
1415
1418 Usage: mdadm --build md-device --chunk=X --level=Y --raid-devices=Z
1419 devices
1420 This usage is similar to --create. The difference is that it creates
1423 an array without a superblock. With these arrays there is no differ‐
1424 ence between initially creating the array and subsequently assembling
1425 the array, except that hopefully there is useful data there in the sec‐
1426 ond case.
1427 The level may raid0, linear, raid1, raid10, multipath, or faulty, or
1429 one of their synonyms. All devices must be listed and the array will
1430 be started once complete. It will often be appropriate to use
1431 --assume-clean with levels raid1 or raid10.
1432
1435 Usage: mdadm --create md-device --chunk=X --level=Y
1436 --raid-devices=Z devices
1437 This usage will initialise a new md array, associate some devices with
1440 it, and activate the array.
1441 The named device will normally not exist when mdadm --create is run,
1443 but will be created by udev once the array becomes active.
1444 As devices are added, they are checked to see if they contain RAID
1446 superblocks or filesystems. They are also checked to see if the vari‐
1447 ance in device size exceeds 1%.
1448 If any discrepancy is found, the array will not automatically be run,
1450 though the presence of a --run can override this caution.
1451 To create a "degraded" array in which some devices are missing, simply
1453 give the word "missing" in place of a device name. This will cause
1454 mdadm to leave the corresponding slot in the array empty. For a RAID4
1455 or RAID5 array at most one slot can be "missing"; for a RAID6 array at
1456 most two slots. For a RAID1 array, only one real device needs to be
1457 given. All of the others can be "missing".
1458 When creating a RAID5 array, mdadm will automatically create a degraded
1460 array with an extra spare drive. This is because building the spare
1461 into a degraded array is in general faster than resyncing the parity on
1462 a non-degraded, but not clean, array. This feature can be overridden
1463 with the --force option.
1464 When creating an array with version-1 metadata a name for the array is
1466 required. If this is not given with the --name option, mdadm will
1467 choose a name based on the last component of the name of the device
1468 being created. So if /dev/md3 is being created, then the name 3 will
1469 be chosen. If /dev/md/home is being created, then the name home will
1470 be used.
1471 When creating a partition based array, using mdadm with version-1.x
1473 metadata, the partition type should be set to 0xDA (non fs-data). This
1474 type selection allows for greater precision since using any other [RAID
1475 auto-detect (0xFD) or a GNU/Linux partition (0x83)], might create prob‐
1476 lems in the event of array recovery through a live cdrom.
1477 A new array will normally get a randomly assigned 128bit UUID which is
1479 very likely to be unique. If you have a specific need, you can choose
1480 a UUID for the array by giving the --uuid= option. Be warned that cre‐
1481 ating two arrays with the same UUID is a recipe for disaster. Also,
1482 using --uuid= when creating a v0.90 array will silently override any
1483 --homehost= setting.
1484 If the array type supports a write-intent bitmap, and if the devices in
1486 the array exceed 100G is size, an internal write-intent bitmap will
1487 automatically be added unless some other option is explicitly requested
1488 with the --bitmap option. In any case space for a bitmap will be
1489 reserved so that one can be added layer with --grow --bitmap=internal.
1490 If the metadata type supports it (currently only 1.x metadata), space
1492 will be allocated to store a bad block list. This allows a modest num‐
1493 ber of bad blocks to be recorded, allowing the drive to remain in ser‐
1494 vice while only partially functional.
1495 When creating an array within a CONTAINER mdadm can be given either the
1497 list of devices to use, or simply the name of the container. The for‐
1498 mer case gives control over which devices in the container will be used
1499 for the array. The latter case allows mdadm to automatically choose
1500 which devices to use based on how much spare space is available.
1501 The General Management options that are valid with --create are:
1503 --run insist on running the array even if some devices look like they
1505 might be in use.
1506 --readonly
1509 start the array readonly — not supported yet.
1510
1513 Usage: mdadm device options... devices...
1514 This usage will allow individual devices in an array to be failed,
1516 removed or added. It is possible to perform multiple operations with
1517 on command. For example:
1518 mdadm /dev/md0 -f /dev/hda1 -r /dev/hda1 -a /dev/hda1
1519 will firstly mark /dev/hda1 as faulty in /dev/md0 and will then remove
1520 it from the array and finally add it back in as a spare. However only
1521 one md array can be affected by a single command.
1522 When a device is added to an active array, mdadm checks to see if it
1524 has metadata on it which suggests that it was recently a member of the
1525 array. If it does, it tries to "re-add" the device. If there have
1526 been no changes since the device was removed, or if the array has a
1527 write-intent bitmap which has recorded whatever changes there were,
1528 then the device will immediately become a full member of the array and
1529 those differences recorded in the bitmap will be resolved.
1530
1533 Usage: mdadm options ... devices ...
1534 MISC mode includes a number of distinct operations that operate on dis‐
1536 tinct devices. The operations are:
1537 --query
1539 The device is examined to see if it is (1) an active md array,
1540 or (2) a component of an md array. The information discovered
1541 is reported.
1542 --detail
1545 The device should be an active md device. mdadm will display a
1546 detailed description of the array. --brief or --scan will cause
1547 the output to be less detailed and the format to be suitable for
1548 inclusion in mdadm.conf. The exit status of mdadm will normally
1549 be 0 unless mdadm failed to get useful information about the
1550 device(s); however, if the --test option is given, then the exit
1551 status will be:
1552 0 The array is functioning normally.
1554 1 The array has at least one failed device.
1556 2 The array has multiple failed devices such that it is
1558 unusable.
1559 4 There was an error while trying to get information about
1561 the device.
1562 --detail-platform
1565 Print detail of the platform's RAID capabilities (firmware /
1566 hardware topology). If the metadata is specified with -e or
1567 --metadata= then the return status will be:
1568 0 metadata successfully enumerated its platform components
1570 on this system
1571 1 metadata is platform independent
1573 2 metadata failed to find its platform components on this
1575 system
1576 --update-subarray=
1579 If the device is a container and the argument to --update-subar‐
1580 ray specifies a subarray in the container, then attempt to
1581 update the given superblock field in the subarray. Similar to
1582 updating an array in "assemble" mode, the field to update is
1583 selected by -U or --update= option. Currently only name is sup‐
1584 ported.
1585 The name option updates the subarray name in the metadata, it
1587 may not affect the device node name or the device node symlink
1588 until the subarray is re-assembled. If updating name would
1589 change the UUID of an active subarray this operation is blocked,
1590 and the command will end in an error.
1591 --examine
1594 The device should be a component of an md array. mdadm will
1595 read the md superblock of the device and display the contents.
1596 If --brief or --scan is given, then multiple devices that are
1597 components of the one array are grouped together and reported in
1598 a single entry suitable for inclusion in mdadm.conf.
1599 Having --scan without listing any devices will cause all devices
1601 listed in the config file to be examined.
1602 --dump=directory
1605 If the device contains RAID metadata, a file will be created in
1606 the directory and the metadata will be written to it. The file
1607 will be the same size as the device and have the metadata writ‐
1608 ten in the file at the same locate that it exists in the device.
1609 However the file will be "sparse" so that only those blocks con‐
1610 taining metadata will be allocated. The total space used will be
1611 small.
1612 The file name used in the directory will be the base name of the
1614 device. Further if any links appear in /dev/disk/by-id which
1615 point to the device, then hard links to the file will be created
1616 in directory based on these by-id names.
1617 Multiple devices can be listed and their metadata will all be
1619 stored in the one directory.
1620 --restore=directory
1623 This is the reverse of --dump. mdadm will locate a file in the
1624 directory that has a name appropriate for the given device and
1625 will restore metadata from it. Names that match /dev/disk/by-id
1626 names are preferred, however if two of those refer to different
1627 files, mdadm will not choose between them but will abort the
1628 operation.
1629 If a file name is given instead of a directory then mdadm will
1631 restore from that file to a single device, always provided the
1632 size of the file matches that of the device, and the file con‐
1633 tains valid metadata.
1634 --stop The devices should be active md arrays which will be deacti‐
1636 vated, as long as they are not currently in use.
1637 --run This will fully activate a partially assembled md array.
1640 --readonly
1643 This will mark an active array as read-only, providing that it
1644 is not currently being used.
1645 --readwrite
1648 This will change a readonly array back to being read/write.
1649 --scan For all operations except --examine, --scan will cause the oper‐
1652 ation to be applied to all arrays listed in /proc/mdstat. For
1653 --examine, --scan causes all devices listed in the config file
1654 to be examined.
1655 -b, --brief
1658 Be less verbose. This is used with --detail and --examine.
1659 Using --brief with --verbose gives an intermediate level of ver‐
1660 bosity.
1661
1664 Usage: mdadm --monitor options... devices...
1665 This usage causes mdadm to periodically poll a number of md arrays and
1668 to report on any events noticed. mdadm will never exit once it decides
1669 that there are arrays to be checked, so it should normally be run in
1670 the background.
1671 As well as reporting events, mdadm may move a spare drive from one
1673 array to another if they are in the same spare-group or domain and if
1674 the destination array has a failed drive but no spares.
1675 If any devices are listed on the command line, mdadm will only monitor
1677 those devices. Otherwise all arrays listed in the configuration file
1678 will be monitored. Further, if --scan is given, then any other md
1679 devices that appear in /proc/mdstat will also be monitored.
1680 The result of monitoring the arrays is the generation of events. These
1682 events are passed to a separate program (if specified) and may be
1683 mailed to a given E-mail address.
1684 When passing events to a program, the program is run once for each
1686 event, and is given 2 or 3 command-line arguments: the first is the
1687 name of the event (see below), the second is the name of the md device
1688 which is affected, and the third is the name of a related device if
1689 relevant (such as a component device that has failed).
1690 If --scan is given, then a program or an E-mail address must be speci‐
1692 fied on the command line or in the config file. If neither are avail‐
1693 able, then mdadm will not monitor anything. Without --scan, mdadm will
1694 continue monitoring as long as something was found to monitor. If no
1695 program or email is given, then each event is reported to stdout.
1696 The different events are:
1698 DeviceDisappeared
1701 An md array which previously was configured appears to no
1702 longer be configured. (syslog priority: Critical)
1703 If mdadm was told to monitor an array which is RAID0 or Lin‐
1705 ear, then it will report DeviceDisappeared with the extra
1706 information Wrong-Level. This is because RAID0 and Linear
1707 do not support the device-failed, hot-spare and resync oper‐
1708 ations which are monitored.
1709 RebuildStarted
1712 An md array started reconstruction (e.g. recovery, resync,
1713 reshape, check, repair). (syslog priority: Warning)
1714 RebuildNN
1717 Where NN is a two-digit number (ie. 05, 48). This indicates
1718 that rebuild has passed that many percent of the total. The
1719 events are generated with fixed increment since 0. Increment
1720 size may be specified with a commandline option (default is
1721 20). (syslog priority: Warning)
1722 RebuildFinished
1725 An md array that was rebuilding, isn't any more, either
1726 because it finished normally or was aborted. (syslog prior‐
1727 ity: Warning)
1728 Fail An active component device of an array has been marked as
1731 faulty. (syslog priority: Critical)
1732 FailSpare
1735 A spare component device which was being rebuilt to replace
1736 a faulty device has failed. (syslog priority: Critical)
1737 SpareActive
1740 A spare component device which was being rebuilt to replace
1741 a faulty device has been successfully rebuilt and has been
1742 made active. (syslog priority: Info)
1743 NewArray
1746 A new md array has been detected in the /proc/mdstat file.
1747 (syslog priority: Info)
1748 DegradedArray
1751 A newly noticed array appears to be degraded. This message
1752 is not generated when mdadm notices a drive failure which
1753 causes degradation, but only when mdadm notices that an
1754 array is degraded when it first sees the array. (syslog
1755 priority: Critical)
1756 MoveSpare
1759 A spare drive has been moved from one array in a spare-group
1760 or domain to another to allow a failed drive to be replaced.
1761 (syslog priority: Info)
1762 SparesMissing
1765 If mdadm has been told, via the config file, that an array
1766 should have a certain number of spare devices, and mdadm
1767 detects that it has fewer than this number when it first
1768 sees the array, it will report a SparesMissing message.
1769 (syslog priority: Warning)
1770 TestMessage
1773 An array was found at startup, and the --test flag was
1774 given. (syslog priority: Info)
1775 Only Fail, FailSpare, DegradedArray, SparesMissing and TestMessage
1777 cause Email to be sent. All events cause the program to be run. The
1778 program is run with two or three arguments: the event name, the array
1779 device and possibly a second device.
1780 Each event has an associated array device (e.g. /dev/md1) and possibly
1782 a second device. For Fail, FailSpare, and SpareActive the second
1783 device is the relevant component device. For MoveSpare the second
1784 device is the array that the spare was moved from.
1785 For mdadm to move spares from one array to another, the different
1787 arrays need to be labeled with the same spare-group or the spares must
1788 be allowed to migrate through matching POLICY domains in the configura‐
1789 tion file. The spare-group name can be any string; it is only neces‐
1790 sary that different spare groups use different names.
1791 When mdadm detects that an array in a spare group has fewer active
1793 devices than necessary for the complete array, and has no spare
1794 devices, it will look for another array in the same spare group that
1795 has a full complement of working drive and a spare. It will then
1796 attempt to remove the spare from the second drive and add it to the
1797 first. If the removal succeeds but the adding fails, then it is added
1798 back to the original array.
1799 If the spare group for a degraded array is not defined, mdadm will look
1801 at the rules of spare migration specified by POLICY lines in mdadm.conf
1802 and then follow similar steps as above if a matching spare is found.
1803
1806 The GROW mode is used for changing the size or shape of an active
1807 array. For this to work, the kernel must support the necessary change.
1808 Various types of growth are being added during 2.6 development.
1809 Currently the supported changes include
1811 · change the "size" attribute for RAID1, RAID4, RAID5 and RAID6.
1813 · increase or decrease the "raid-devices" attribute of RAID0, RAID1,
1815 RAID4, RAID5, and RAID6.
1816 · change the chunk-size and layout of RAID0, RAID4, RAID5, RAID6 and
1818 RAID10.
1819 · convert between RAID1 and RAID5, between RAID5 and RAID6, between
1821 RAID0, RAID4, and RAID5, and between RAID0 and RAID10 (in the
1822 near-2 mode).
1823 · add a write-intent bitmap to any array which supports these bit‐
1825 maps, or remove a write-intent bitmap from such an array.
1826 Using GROW on containers is currently supported only for Intel's IMSM
1828 container format. The number of devices in a container can be
1829 increased - which affects all arrays in the container - or an array in
1830 a container can be converted between levels where those levels are sup‐
1831 ported by the container, and the conversion is on of those listed
1832 above. Resizing arrays in an IMSM container with --grow --size is not
1833 yet supported.
1834 Grow functionality (e.g. expand a number of raid devices) for Intel's
1836 IMSM container format has an experimental status. It is guarded by the
1837 MDADM_EXPERIMENTAL environment variable which must be set to '1' for a
1838 GROW command to succeed. This is for the following reasons:
1839 1. Intel's native IMSM check-pointing is not fully tested yet.
1842 This can causes IMSM incompatibility during the grow process: an
1843 array which is growing cannot roam between Microsoft Windows(R)
1844 and Linux systems.
1845 2. Interrupting a grow operation is not recommended, because it has
1848 not been fully tested for Intel's IMSM container format yet.
1849 Note: Intel's native checkpointing doesn't use --backup-file option and
1852 it is transparent for assembly feature.
1853 SIZE CHANGES
1856 Normally when an array is built the "size" is taken from the smallest
1857 of the drives. If all the small drives in an arrays are, one at a
1858 time, removed and replaced with larger drives, then you could have an
1859 array of large drives with only a small amount used. In this situa‐
1860 tion, changing the "size" with "GROW" mode will allow the extra space
1861 to start being used. If the size is increased in this way, a "resync"
1862 process will start to make sure the new parts of the array are synchro‐
1863 nised.
1864 Note that when an array changes size, any filesystem that may be stored
1866 in the array will not automatically grow or shrink to use or vacate the
1867 space. The filesystem will need to be explicitly told to use the extra
1868 space after growing, or to reduce its size prior to shrinking the
1869 array.
1870 Also the size of an array cannot be changed while it has an active bit‐
1872 map. If an array has a bitmap, it must be removed before the size can
1873 be changed. Once the change is complete a new bitmap can be created.
1874 RAID-DEVICES CHANGES
1877 A RAID1 array can work with any number of devices from 1 upwards
1878 (though 1 is not very useful). There may be times which you want to
1879 increase or decrease the number of active devices. Note that this is
1880 different to hot-add or hot-remove which changes the number of inactive
1881 devices.
1882 When reducing the number of devices in a RAID1 array, the slots which
1884 are to be removed from the array must already be vacant. That is, the
1885 devices which were in those slots must be failed and removed.
1886 When the number of devices is increased, any hot spares that are
1888 present will be activated immediately.
1889 Changing the number of active devices in a RAID5 or RAID6 is much more
1891 effort. Every block in the array will need to be read and written back
1892 to a new location. From 2.6.17, the Linux Kernel is able to increase
1893 the number of devices in a RAID5 safely, including restarting an inter‐
1894 rupted "reshape". From 2.6.31, the Linux Kernel is able to increase or
1895 decrease the number of devices in a RAID5 or RAID6.
1896 From 2.6.35, the Linux Kernel is able to convert a RAID0 in to a RAID4
1898 or RAID5. mdadm uses this functionality and the ability to add devices
1899 to a RAID4 to allow devices to be added to a RAID0. When requested to
1900 do this, mdadm will convert the RAID0 to a RAID4, add the necessary
1901 disks and make the reshape happen, and then convert the RAID4 back to
1902 RAID0.
1903 When decreasing the number of devices, the size of the array will also
1905 decrease. If there was data in the array, it could get destroyed and
1906 this is not reversible, so you should firstly shrink the filesystem on
1907 the array to fit within the new size. To help prevent accidents, mdadm
1908 requires that the size of the array be decreased first with mdadm
1909 --grow --array-size. This is a reversible change which simply makes
1910 the end of the array inaccessible. The integrity of any data can then
1911 be checked before the non-reversible reduction in the number of devices
1912 is request.
1913 When relocating the first few stripes on a RAID5 or RAID6, it is not
1915 possible to keep the data on disk completely consistent and crash-
1916 proof. To provide the required safety, mdadm disables writes to the
1917 array while this "critical section" is reshaped, and takes a backup of
1918 the data that is in that section. For grows, this backup may be stored
1919 in any spare devices that the array has, however it can also be stored
1920 in a separate file specified with the --backup-file option, and is
1921 required to be specified for shrinks, RAID level changes and layout
1922 changes. If this option is used, and the system does crash during the
1923 critical period, the same file must be passed to --assemble to restore
1924 the backup and reassemble the array. When shrinking rather than grow‐
1925 ing the array, the reshape is done from the end towards the beginning,
1926 so the "critical section" is at the end of the reshape.
1927 LEVEL CHANGES
1930 Changing the RAID level of any array happens instantaneously. However
1931 in the RAID5 to RAID6 case this requires a non-standard layout of the
1932 RAID6 data, and in the RAID6 to RAID5 case that non-standard layout is
1933 required before the change can be accomplished. So while the level
1934 change is instant, the accompanying layout change can take quite a long
1935 time. A --backup-file is required. If the array is not simultaneously
1936 being grown or shrunk, so that the array size will remain the same -
1937 for example, reshaping a 3-drive RAID5 into a 4-drive RAID6 - the
1938 backup file will be used not just for a "cricital section" but through‐
1939 out the reshape operation, as described below under LAYOUT CHANGES.
1940 CHUNK-SIZE AND LAYOUT CHANGES
1943 Changing the chunk-size of layout without also changing the number of
1944 devices as the same time will involve re-writing all blocks in-place.
1945 To ensure against data loss in the case of a crash, a --backup-file
1946 must be provided for these changes. Small sections of the array will
1947 be copied to the backup file while they are being rearranged. This
1948 means that all the data is copied twice, once to the backup and once to
1949 the new layout on the array, so this type of reshape will go very
1950 slowly.
1951 If the reshape is interrupted for any reason, this backup file must be
1953 made available to mdadm --assemble so the array can be reassembled.
1954 Consequently the file cannot be stored on the device being reshaped.
1955 BITMAP CHANGES
1959 A write-intent bitmap can be added to, or removed from, an active
1960 array. Either internal bitmaps, or bitmaps stored in a separate file,
1961 can be added. Note that if you add a bitmap stored in a file which is
1962 in a filesystem that is on the RAID array being affected, the system
1963 will deadlock. The bitmap must be on a separate filesystem.
1964
1967 Usage: mdadm --incremental [--run] [--quiet] component-device
1968 [optional-aliases-for-device]
1969 Usage: mdadm --incremental --fail component-device
1971 Usage: mdadm --incremental --rebuild-map
1973 Usage: mdadm --incremental --run --scan
1975 This mode is designed to be used in conjunction with a device discovery
1978 system. As devices are found in a system, they can be passed to mdadm
1979 --incremental to be conditionally added to an appropriate array.
1980 Conversely, it can also be used with the --fail flag to do just the
1982 opposite and find whatever array a particular device is part of and
1983 remove the device from that array.
1984 If the device passed is a CONTAINER device created by a previous call
1986 to mdadm, then rather than trying to add that device to an array, all
1987 the arrays described by the metadata of the container will be started.
1988 mdadm performs a number of tests to determine if the device is part of
1990 an array, and which array it should be part of. If an appropriate
1991 array is found, or can be created, mdadm adds the device to the array
1992 and conditionally starts the array.
1993 Note that mdadm will normally only add devices to an array which were
1995 previously working (active or spare) parts of that array. The support
1996 for automatic inclusion of a new drive as a spare in some array
1997 requires a configuration through POLICY in config file.
1998 The tests that mdadm makes are as follow:
2000 + Is the device permitted by mdadm.conf? That is, is it listed in
2002 a DEVICES line in that file. If DEVICES is absent then the
2003 default it to allow any device. Similarly if DEVICES contains
2004 the special word partitions then any device is allowed. Other‐
2005 wise the device name given to mdadm, or one of the aliases
2006 given, or an alias found in the filesystem, must match one of
2007 the names or patterns in a DEVICES line.
2008 This is the only context where the aliases are used. They are
2010 usually provided by a udev rules mentioning ${DEVLINKS}.
2011 + Does the device have a valid md superblock? If a specific meta‐
2014 data version is requested with --metadata or -e then only that
2015 style of metadata is accepted, otherwise mdadm finds any known
2016 version of metadata. If no md metadata is found, the device may
2017 be still added to an array as a spare if POLICY allows.
2018 mdadm keeps a list of arrays that it has partially assembled in
2022 /dev/md/md-device-map. If no array exists which matches the metadata
2023 on the new device, mdadm must choose a device name and unit number. It
2024 does this based on any name given in mdadm.conf or any name information
2025 stored in the metadata. If this name suggests a unit number, that num‐
2026 ber will be used, otherwise a free unit number will be chosen. Nor‐
2027 mally mdadm will prefer to create a partitionable array, however if the
2028 CREATE line in mdadm.conf suggests that a non-partitionable array is
2029 preferred, that will be honoured.
2030 If the array is not found in the config file and its metadata does not
2032 identify it as belonging to the "homehost", then mdadm will choose a
2033 name for the array which is certain not to conflict with any array
2034 which does belong to this host. It does this be adding an underscore
2035 and a small number to the name preferred by the metadata.
2036 Once an appropriate array is found or created and the device is added,
2038 mdadm must decide if the array is ready to be started. It will nor‐
2039 mally compare the number of available (non-spare) devices to the number
2040 of devices that the metadata suggests need to be active. If there are
2041 at least that many, the array will be started. This means that if any
2042 devices are missing the array will not be restarted.
2043 As an alternative, --run may be passed to mdadm in which case the array
2045 will be run as soon as there are enough devices present for the data to
2046 be accessible. For a RAID1, that means one device will start the
2047 array. For a clean RAID5, the array will be started as soon as all but
2048 one drive is present.
2049 Note that neither of these approaches is really ideal. If it can be
2051 known that all device discovery has completed, then
2052 mdadm -IRs
2053 can be run which will try to start all arrays that are being incremen‐
2054 tally assembled. They are started in "read-auto" mode in which they
2055 are read-only until the first write request. This means that no meta‐
2056 data updates are made and no attempt at resync or recovery happens.
2057 Further devices that are found before the first write can still be
2058 added safely.
2059
2062 This section describes environment variables that affect how mdadm
2063 operates.
2064 MDADM_NO_MDMON
2067 Setting this value to 1 will prevent mdadm from automatically
2068 launching mdmon. This variable is intended primarily for debug‐
2069 ging mdadm/mdmon.
2070 MDADM_NO_UDEV
2073 Normally, mdadm does not create any device nodes in /dev, but
2074 leaves that task to udev. If udev appears not to be configured,
2075 or if this environment variable is set to '1', the mdadm will
2076 create and devices that are needed.
2077 MDADM_NO_SYSTEMCTL
2080 If mdadm detects that systemd is in use it will normally request
2081 systemd to start various background tasks (particularly mdmon)
2082 rather than forking and running them in the background. This
2083 can be suppressed by setting MDADM_NO_SYSTEMCTL=1.
2084 IMSM_NO_PLATFORM
2087 A key value of IMSM metadata is that it allows interoperability
2088 with boot ROMs on Intel platforms, and with other major operat‐
2089 ing systems. Consequently, mdadm will only allow an IMSM array
2090 to be created or modified if detects that it is running on an
2091 Intel platform which supports IMSM, and supports the particular
2092 configuration of IMSM that is being requested (some functional‐
2093 ity requires newer OROM support).
2094 These checks can be suppressed by setting IMSM_NO_PLATFORM=1 in
2096 the environment. This can be useful for testing or for disaster
2097 recovery. You should be aware that interoperability may be com‐
2098 promised by setting this value.
2099 MDADM_GROW_ALLOW_OLD
2102 If an array is stopped while it is performing a reshape and that
2103 reshape was making use of a backup file, then when the array is
2104 re-assembled mdadm will sometimes complain that the backup file
2105 is too old. If this happens and you are certain it is the right
2106 backup file, you can over-ride this check by setting
2107 MDADM_GROW_ALLOW_OLD=1 in the environment.
2108 MDADM_CONF_AUTO
2111 Any string given in this variable is added to the start of the
2112 AUTO line in the config file, or treated as the whole AUTO line
2113 if none is given. It can be used to disable certain metadata
2114 types when mdadm is called from a boot script. For example
2115 export MDADM_CONF_AUTO='-ddf -imsm'
2116 will make sure that mdadm does not automatically assemble any
2117 DDF or IMSM arrays that are found. This can be useful on sys‐
2118 tems configured to manage such arrays with dmraid.
2119
2123 mdadm --query /dev/name-of-device
2124 This will find out if a given device is a RAID array, or is part of
2125 one, and will provide brief information about the device.
2126 mdadm --assemble --scan
2128 This will assemble and start all arrays listed in the standard config
2129 file. This command will typically go in a system startup file.
2130 mdadm --stop --scan
2132 This will shut down all arrays that can be shut down (i.e. are not cur‐
2133 rently in use). This will typically go in a system shutdown script.
2134 mdadm --follow --scan --delay=120
2136 If (and only if) there is an Email address or program given in the
2137 standard config file, then monitor the status of all arrays listed in
2138 that file by polling them ever 2 minutes.
2139 mdadm --create /dev/md0 --level=1 --raid-devices=2 /dev/hd[ac]1
2141 Create /dev/md0 as a RAID1 array consisting of /dev/hda1 and /dev/hdc1.
2142 echo 'DEVICE /dev/hd*[0-9] /dev/sd*[0-9]' > mdadm.conf
2144 mdadm --detail --scan >> mdadm.conf
2145 This will create a prototype config file that describes currently
2146 active arrays that are known to be made from partitions of IDE or SCSI
2147 drives. This file should be reviewed before being used as it may con‐
2148 tain unwanted detail.
2149 echo 'DEVICE /dev/hd[a-z] /dev/sd*[a-z]' > mdadm.conf
2151 mdadm --examine --scan --config=mdadm.conf >> mdadm.conf
2152 This will find arrays which could be assembled from existing IDE and
2153 SCSI whole drives (not partitions), and store the information in the
2154 format of a config file. This file is very likely to contain unwanted
2155 detail, particularly the devices= entries. It should be reviewed and
2156 edited before being used as an actual config file.
2157 mdadm --examine --brief --scan --config=partitions
2159 mdadm -Ebsc partitions
2160 Create a list of devices by reading /proc/partitions, scan these for
2161 RAID superblocks, and printout a brief listing of all that were found.
2162 mdadm -Ac partitions -m 0 /dev/md0
2164 Scan all partitions and devices listed in /proc/partitions and assemble
2165 /dev/md0 out of all such devices with a RAID superblock with a minor
2166 number of 0.
2167 mdadm --monitor --scan --daemonise > /run/mdadm/mon.pid
2169 If config file contains a mail address or alert program, run mdadm in
2170 the background in monitor mode monitoring all md devices. Also write
2171 pid of mdadm daemon to /run/mdadm/mon.pid.
2172 mdadm -Iq /dev/somedevice
2174 Try to incorporate newly discovered device into some array as appropri‐
2175 ate.
2176 mdadm --incremental --rebuild-map --run --scan
2178 Rebuild the array map from any current arrays, and then start any that
2179 can be started.
2180 mdadm /dev/md4 --fail detached --remove detached
2182 Any devices which are components of /dev/md4 will be marked as faulty
2183 and then remove from the array.
2184 mdadm --grow /dev/md4 --level=6 --backup-file=/root/backup-md4
2186 The array /dev/md4 which is currently a RAID5 array will be converted
2187 to RAID6. There should normally already be a spare drive attached to
2188 the array as a RAID6 needs one more drive than a matching RAID5.
2189 mdadm --create /dev/md/ddf --metadata=ddf --raid-disks 6 /dev/sd[a-f]
2191 Create a DDF array over 6 devices.
2192 mdadm --create /dev/md/home -n3 -l5 -z 30000000 /dev/md/ddf
2194 Create a RAID5 array over any 3 devices in the given DDF set. Use only
2195 30 gigabytes of each device.
2196 mdadm -A /dev/md/ddf1 /dev/sd[a-f]
2198 Assemble a pre-exist ddf array.
2199 mdadm -I /dev/md/ddf1
2201 Assemble all arrays contained in the ddf array, assigning names as
2202 appropriate.
2203 mdadm --create --help
2205 Provide help about the Create mode.
2206 mdadm --config --help
2208 Provide help about the format of the config file.
2209 mdadm --help
2211 Provide general help.
2212
2215 /proc/mdstat
2216 If you're using the /proc filesystem, /proc/mdstat lists all active md
2217 devices with information about them. mdadm uses this to find arrays
2218 when --scan is given in Misc mode, and to monitor array reconstruction
2219 on Monitor mode.
2220 /etc/mdadm.conf
2223 The config file lists which devices may be scanned to see if they con‐
2224 tain MD super block, and gives identifying information (e.g. UUID)
2225 about known MD arrays. See mdadm.conf(5) for more details.
2226 /etc/mdadm.conf.d
2229 A directory containing configuration files which are read in lexical
2230 order.
2231 /dev/md/md-device-map
2234 When --incremental mode is used, this file gets a list of arrays cur‐
2235 rently being created.
2236
2239 mdadm understand two sorts of names for array devices.
2240 The first is the so-called 'standard' format name, which matches the
2242 names used by the kernel and which appear in /proc/mdstat.
2243 The second sort can be freely chosen, but must reside in /dev/md/.
2245 When giving a device name to mdadm to create or assemble an array,
2246 either full path name such as /dev/md0 or /dev/md/home can be given, or
2247 just the suffix of the second sort of name, such as home can be given.
2248 When mdadm chooses device names during auto-assembly or incremental
2250 assembly, it will sometimes add a small sequence number to the end of
2251 the name to avoid conflicted between multiple arrays that have the same
2252 name. If mdadm can reasonably determine that the array really is meant
2253 for this host, either by a hostname in the metadata, or by the presence
2254 of the array in mdadm.conf, then it will leave off the suffix if possi‐
2255 ble. Also if the homehost is specified as <ignore> mdadm will only use
2256 a suffix if a different array of the same name already exists or is
2257 listed in the config file.
2258 The standard names for non-partitioned arrays (the only sort of md
2260 array available in 2.4 and earlier) are of the form
2261 /dev/mdNN
2263 where NN is a number. The standard names for partitionable arrays (as
2265 available from 2.6 onwards) are of the form:
2266 /dev/md_dNN
2268 Partition numbers should be indicated by adding "pMM" to these, thus
2270 "/dev/md/d1p2".
2271 From kernel version 2.6.28 the "non-partitioned array" can actually be
2273 partitioned. So the "md_dNN" names are no longer needed, and parti‐
2274 tions such as "/dev/mdNNpXX" are possible.
2275 From kernel version 2.6.29 standard names can be non-numeric following
2277 the form:
2278 /dev/md_XXX
2280 where XXX is any string. These names are supported by mdadm since ver‐
2282 sion 3.3 provided they are enabled in mdadm.conf.
2283
2286 mdadm was previously known as mdctl.
2287
2290 For further information on mdadm usage, MD and the various levels of
2291 RAID, see:
2292 http://raid.wiki.kernel.org/
2294 (based upon Jakob Østergaard's Software-RAID.HOWTO)
2296 The latest version of mdadm should always be available from
2298 http://www.kernel.org/pub/linux/utils/raid/mdadm/
2300 Related man pages:
2302 mdmon(8), mdadm.conf(5), md(4).
2304v3.3.4 MDADM(8)