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 and changing the array's consis‐
96 tency policy.
97 Incremental Assembly
100 Add a single device to an appropriate array. If the addition of
101 the device makes the array runnable, the array will be started.
102 This provides a convenient interface to a hot-plug system. As
103 each device is detected, mdadm has a chance to include it in
104 some array as appropriate. Optionally, when the --fail flag is
105 passed in we will remove the device from any active array
106 instead of adding it.
107 If a CONTAINER is passed to mdadm in this mode, then any arrays
109 within that container will be assembled and started.
110 Manage This is for doing things to specific components of an array such
113 as adding new spares and removing faulty devices.
114 Misc This is an 'everything else' mode that supports operations on
117 active arrays, operations on component devices such as erasing
118 old superblocks, and information gathering operations.
119 Auto-detect
122 This mode does not act on a specific device or array, but rather
123 it requests the Linux Kernel to activate any auto-detected
124 arrays.
125
128 -A, --assemble
129 Assemble a pre-existing array.
130 -B, --build
133 Build a legacy array without superblocks.
134 -C, --create
137 Create a new array.
138 -F, --follow, --monitor
141 Select Monitor mode.
142 -G, --grow
145 Change the size or shape of an active array.
146 -I, --incremental
149 Add/remove a single device to/from an appropriate array, and
150 possibly start the array.
151 --auto-detect
154 Request that the kernel starts any auto-detected arrays. This
155 can only work if md is compiled into the kernel — not if it is a
156 module. Arrays can be auto-detected by the kernel if all the
157 components are in primary MS-DOS partitions with partition type
158 FD, and all use v0.90 metadata. In-kernel autodetect is not
159 recommended for new installations. Using mdadm to detect and
160 assemble arrays — possibly in an initrd — is substantially more
161 flexible and should be preferred.
162 If a device is given before any options, or if the first option is one
165 of --add, --re-add, --add-spare, --fail, --remove, or --replace, then
166 the MANAGE mode is assumed. Anything other than these will cause the
167 Misc mode to be assumed.
168
171 -h, --help
172 Display general help message or, after one of the above options,
173 a mode-specific help message.
174 --help-options
177 Display more detailed help about command line parsing and some
178 commonly used options.
179 -V, --version
182 Print version information for mdadm.
183 -v, --verbose
186 Be more verbose about what is happening. This can be used twice
187 to be extra-verbose. The extra verbosity currently only affects
188 --detail --scan and --examine --scan.
189 -q, --quiet
192 Avoid printing purely informative messages. With this, mdadm
193 will be silent unless there is something really important to
194 report.
195 -f, --force
199 Be more forceful about certain operations. See the various
200 modes for the exact meaning of this option in different con‐
201 texts.
202 -c, --config=
205 Specify the config file or directory. Default is to use
206 /etc/mdadm.conf and /etc/mdadm.conf.d, or if those are missing
207 then /etc/mdadm/mdadm.conf and /etc/mdadm/mdadm.conf.d. If the
208 config file given is partitions then nothing will be read, but
209 mdadm will act as though the config file contained exactly
210 DEVICE partitions containers
211 and will read /proc/partitions to find a list of devices to
212 scan, and /proc/mdstat to find a list of containers to examine.
213 If the word none is given for the config file, then mdadm will
214 act as though the config file were empty.
215 If the name given is of a directory, then mdadm will collect all
217 the files contained in the directory with a name ending in
218 .conf, sort them lexically, and process all of those files as
219 config files.
220 -s, --scan
223 Scan config file or /proc/mdstat for missing information. In
224 general, this option gives mdadm permission to get any missing
225 information (like component devices, array devices, array iden‐
226 tities, and alert destination) from the configuration file (see
227 previous option); one exception is MISC mode when using --detail
228 or --stop, in which case --scan says to get a list of array
229 devices from /proc/mdstat.
230 -e, --metadata=
233 Declare the style of RAID metadata (superblock) to be used. The
234 default is 1.2 for --create, and to guess for other operations.
235 The default can be overridden by setting the metadata value for
236 the CREATE keyword in mdadm.conf.
237 Options are:
239 0, 0.90
242 Use the original 0.90 format superblock. This format
243 limits arrays to 28 component devices and limits compo‐
244 nent devices of levels 1 and greater to 2 terabytes. It
245 is also possible for there to be confusion about whether
246 the superblock applies to a whole device or just the last
247 partition, if that partition starts on a 64K boundary.
248 1, 1.0, 1.1, 1.2 default
251 Use the new version-1 format superblock. This has fewer
252 restrictions. It can easily be moved between hosts with
253 different endian-ness, and a recovery operation can be
254 checkpointed and restarted. The different sub-versions
255 store the superblock at different locations on the
256 device, either at the end (for 1.0), at the start (for
257 1.1) or 4K from the start (for 1.2). "1" is equivalent
258 to "1.2" (the commonly preferred 1.x format). "default"
259 is equivalent to "1.2".
260 ddf Use the "Industry Standard" DDF (Disk Data Format) format
262 defined by SNIA. When creating a DDF array a CONTAINER
263 will be created, and normal arrays can be created in that
264 container.
265 imsm Use the Intel(R) Matrix Storage Manager metadata format.
267 This creates a CONTAINER which is managed in a similar
268 manner to DDF, and is supported by an option-rom on some
269 platforms:
270 http://www.intel.com/design/chipsets/matrixstorage_sb.htm
272 --homehost=
274 This will override any HOMEHOST setting in the config file and
275 provides the identity of the host which should be considered the
276 home for any arrays.
277 When creating an array, the homehost will be recorded in the
279 metadata. For version-1 superblocks, it will be prefixed to the
280 array name. For version-0.90 superblocks, part of the SHA1 hash
281 of the hostname will be stored in the later half of the UUID.
282 When reporting information about an array, any array which is
284 tagged for the given homehost will be reported as such.
285 When using Auto-Assemble, only arrays tagged for the given home‐
287 host will be allowed to use 'local' names (i.e. not ending in
288 '_' followed by a digit string). See below under Auto Assembly.
289 The special name "any" can be used as a wild card. If an array
291 is created with --homehost=any then the name "any" will be
292 stored in the array and it can be assembled in the same way on
293 any host. If an array is assembled with this option, then the
294 homehost recorded on the array will be ignored.
295 --prefer=
298 When mdadm needs to print the name for a device it normally
299 finds the name in /dev which refers to the device and is short‐
300 est. When a path component is given with --prefer mdadm will
301 prefer a longer name if it contains that component. For example
302 --prefer=by-uuid will prefer a name in a subdirectory of /dev
303 called by-uuid.
304 This functionality is currently only provided by --detail and
306 --monitor.
307 --home-cluster=
310 specifies the cluster name for the md device. The md device can
311 be assembled only on the cluster which matches the name speci‐
312 fied. If this option is not provided, mdadm tries to detect the
313 cluster name automatically.
314
317 -n, --raid-devices=
318 Specify the number of active devices in the array. This, plus
319 the number of spare devices (see below) must equal the number of
320 component-devices (including "missing" devices) that are listed
321 on the command line for --create. Setting a value of 1 is prob‐
322 ably a mistake and so requires that --force be specified first.
323 A value of 1 will then be allowed for linear, multipath, RAID0
324 and RAID1. It is never allowed for RAID4, RAID5 or RAID6.
325 This number can only be changed using --grow for RAID1, RAID4,
326 RAID5 and RAID6 arrays, and only on kernels which provide the
327 necessary support.
328 -x, --spare-devices=
331 Specify the number of spare (eXtra) devices in the initial
332 array. Spares can also be added and removed later. The number
333 of component devices listed on the command line must equal the
334 number of RAID devices plus the number of spare devices.
335 -z, --size=
338 Amount (in Kilobytes) of space to use from each drive in RAID
339 levels 1/4/5/6. This must be a multiple of the chunk size, and
340 must leave about 128Kb of space at the end of the drive for the
341 RAID superblock. If this is not specified (as it normally is
342 not) the smallest drive (or partition) sets the size, though if
343 there is a variance among the drives of greater than 1%, a warn‐
344 ing is issued.
345 A suffix of 'K', 'M' or 'G' can be given to indicate Kilobytes,
347 Megabytes or Gigabytes respectively.
348 Sometimes a replacement drive can be a little smaller than the
350 original drives though this should be minimised by IDEMA stan‐
351 dards. Such a replacement drive will be rejected by md. To
352 guard against this it can be useful to set the initial size
353 slightly smaller than the smaller device with the aim that it
354 will still be larger than any replacement.
355 This value can be set with --grow for RAID level 1/4/5/6 though
357 CONTAINER based arrays such as those with IMSM metadata may not
358 be able to support this. If the array was created with a size
359 smaller than the currently active drives, the extra space can be
360 accessed using --grow. The size can be given as max which means
361 to choose the largest size that fits on all current drives.
362 Before reducing the size of the array (with --grow --size=) you
364 should make sure that space isn't needed. If the device holds a
365 filesystem, you would need to resize the filesystem to use less
366 space.
367 After reducing the array size you should check that the data
369 stored in the device is still available. If the device holds a
370 filesystem, then an 'fsck' of the filesystem is a minimum
371 requirement. If there are problems the array can be made bigger
372 again with no loss with another --grow --size= command.
373 This value cannot be used when creating a CONTAINER such as with
375 DDF and IMSM metadata, though it perfectly valid when creating
376 an array inside a container.
377 -Z, --array-size=
380 This is only meaningful with --grow and its effect is not per‐
381 sistent: when the array is stopped and restarted the default
382 array size will be restored.
383 Setting the array-size causes the array to appear smaller to
385 programs that access the data. This is particularly needed
386 before reshaping an array so that it will be smaller. As the
387 reshape is not reversible, but setting the size with --array-
388 size is, it is required that the array size is reduced as appro‐
389 priate before the number of devices in the array is reduced.
390 Before reducing the size of the array you should make sure that
392 space isn't needed. If the device holds a filesystem, you would
393 need to resize the filesystem to use less space.
394 After reducing the array size you should check that the data
396 stored in the device is still available. If the device holds a
397 filesystem, then an 'fsck' of the filesystem is a minimum
398 requirement. If there are problems the array can be made bigger
399 again with no loss with another --grow --array-size= command.
400 A suffix of 'K', 'M' or 'G' can be given to indicate Kilobytes,
402 Megabytes or Gigabytes respectively. A value of max restores
403 the apparent size of the array to be whatever the real amount of
404 available space is.
405 Clustered arrays do not support this parameter yet.
407 -c, --chunk=
410 Specify chunk size of kilobytes. The default when creating an
411 array is 512KB. To ensure compatibility with earlier versions,
412 the default when building an array with no persistent metadata
413 is 64KB. This is only meaningful for RAID0, RAID4, RAID5,
414 RAID6, and RAID10.
415 RAID4, RAID5, RAID6, and RAID10 require the chunk size to be a
417 power of 2. In any case it must be a multiple of 4KB.
418 A suffix of 'K', 'M' or 'G' can be given to indicate Kilobytes,
420 Megabytes or Gigabytes respectively.
421 --rounding=
424 Specify rounding factor for a Linear array. The size of each
425 component will be rounded down to a multiple of this size. This
426 is a synonym for --chunk but highlights the different meaning
427 for Linear as compared to other RAID levels. The default is 64K
428 if a kernel earlier than 2.6.16 is in use, and is 0K (i.e. no
429 rounding) in later kernels.
430 -l, --level=
433 Set RAID level. When used with --create, options are: linear,
434 raid0, 0, stripe, raid1, 1, mirror, raid4, 4, raid5, 5, raid6,
435 6, raid10, 10, multipath, mp, faulty, container. Obviously some
436 of these are synonymous.
437 When a CONTAINER metadata type is requested, only the container
439 level is permitted, and it does not need to be explicitly given.
440 When used with --build, only linear, stripe, raid0, 0, raid1,
442 multipath, mp, and faulty are valid.
443 Can be used with --grow to change the RAID level in some cases.
445 See LEVEL CHANGES below.
446 -p, --layout=
449 This option configures the fine details of data layout for
450 RAID5, RAID6, and RAID10 arrays, and controls the failure modes
451 for faulty.
452 The layout of the RAID5 parity block can be one of left-asymmet‐
454 ric, left-symmetric, right-asymmetric, right-symmetric, la, ra,
455 ls, rs. The default is left-symmetric.
456 It is also possible to cause RAID5 to use a RAID4-like layout by
458 choosing parity-first, or parity-last.
459 Finally for RAID5 there are DDF-compatible layouts,
461 ddf-zero-restart, ddf-N-restart, and ddf-N-continue.
462 These same layouts are available for RAID6. There are also 4
464 layouts that will provide an intermediate stage for converting
465 between RAID5 and RAID6. These provide a layout which is iden‐
466 tical to the corresponding RAID5 layout on the first N-1
467 devices, and has the 'Q' syndrome (the second 'parity' block
468 used by RAID6) on the last device. These layouts are: left-sym‐
469 metric-6, right-symmetric-6, left-asymmetric-6, right-asymmet‐
470 ric-6, and parity-first-6.
471 When setting the failure mode for level faulty, the options are:
473 write-transient, wt, read-transient, rt, write-persistent, wp,
474 read-persistent, rp, write-all, read-fixable, rf, clear, flush,
475 none.
476 Each failure mode can be followed by a number, which is used as
478 a period between fault generation. Without a number, the fault
479 is generated once on the first relevant request. With a number,
480 the fault will be generated after that many requests, and will
481 continue to be generated every time the period elapses.
482 Multiple failure modes can be current simultaneously by using
484 the --grow option to set subsequent failure modes.
485 "clear" or "none" will remove any pending or periodic failure
487 modes, and "flush" will clear any persistent faults.
488 Finally, the layout options for RAID10 are one of 'n', 'o' or
490 'f' followed by a small number. The default is 'n2'. The sup‐
491 ported options are:
492 'n' signals 'near' copies. Multiple copies of one data block
494 are at similar offsets in different devices.
495 'o' signals 'offset' copies. Rather than the chunks being
497 duplicated within a stripe, whole stripes are duplicated but are
498 rotated by one device so duplicate blocks are on different
499 devices. Thus subsequent copies of a block are in the next
500 drive, and are one chunk further down.
501 'f' signals 'far' copies (multiple copies have very different
503 offsets). See md(4) for more detail about 'near', 'offset', and
504 'far'.
505 The number is the number of copies of each datablock. 2 is nor‐
507 mal, 3 can be useful. This number can be at most equal to the
508 number of devices in the array. It does not need to divide
509 evenly into that number (e.g. it is perfectly legal to have an
510 'n2' layout for an array with an odd number of devices).
511 When an array is converted between RAID5 and RAID6 an intermedi‐
513 ate RAID6 layout is used in which the second parity block (Q) is
514 always on the last device. To convert a RAID5 to RAID6 and
515 leave it in this new layout (which does not require re-striping)
516 use --layout=preserve. This will try to avoid any restriping.
517 The converse of this is --layout=normalise which will change a
519 non-standard RAID6 layout into a more standard arrangement.
520 --parity=
523 same as --layout (thus explaining the p of -p).
524 -b, --bitmap=
527 Specify a file to store a write-intent bitmap in. The file
528 should not exist unless --force is also given. The same file
529 should be provided when assembling the array. If the word
530 internal is given, then the bitmap is stored with the metadata
531 on the array, and so is replicated on all devices. If the word
532 none is given with --grow mode, then any bitmap that is present
533 is removed. If the word clustered is given, the array is created
534 for a clustered environment. One bitmap is created for each node
535 as defined by the --nodes parameter and are stored internally.
536 To help catch typing errors, the filename must contain at least
538 one slash ('/') if it is a real file (not 'internal' or 'none').
539 Note: external bitmaps are only known to work on ext2 and ext3.
541 Storing bitmap files on other filesystems may result in serious
542 problems.
543 When creating an array on devices which are 100G or larger,
545 mdadm automatically adds an internal bitmap as it will usually
546 be beneficial. This can be suppressed with --bitmap=none or by
547 selecting a different consistency policy with --consistency-pol‐
548 icy.
549 --bitmap-chunk=
552 Set the chunksize of the bitmap. Each bit corresponds to that
553 many Kilobytes of storage. When using a file based bitmap, the
554 default is to use the smallest size that is at-least 4 and
555 requires no more than 2^21 chunks. When using an internal bit‐
556 map, the chunksize defaults to 64Meg, or larger if necessary to
557 fit the bitmap into the available space.
558 A suffix of 'K', 'M' or 'G' can be given to indicate Kilobytes,
560 Megabytes or Gigabytes respectively.
561 -W, --write-mostly
564 subsequent devices listed in a --build, --create, or --add com‐
565 mand will be flagged as 'write-mostly'. This is valid for RAID1
566 only and means that the 'md' driver will avoid reading from
567 these devices if at all possible. This can be useful if mirror‐
568 ing over a slow link.
569 --write-behind=
572 Specify that write-behind mode should be enabled (valid for
573 RAID1 only). If an argument is specified, it will set the maxi‐
574 mum number of outstanding writes allowed. The default value is
575 256. A write-intent bitmap is required in order to use write-
576 behind mode, and write-behind is only attempted on drives marked
577 as write-mostly.
578 --failfast
581 subsequent devices listed in a --create or --add command will be
582 flagged as 'failfast'. This is valid for RAID1 and RAID10
583 only. IO requests to these devices will be encouraged to fail
584 quickly rather than cause long delays due to error handling.
585 Also no attempt is made to repair a read error on these devices.
586 If an array becomes degraded so that the 'failfast' device is
588 the only usable device, the 'failfast' flag will then be ignored
589 and extended delays will be preferred to complete failure.
590 The 'failfast' flag is appropriate for storage arrays which have
592 a low probability of true failure, but which may sometimes cause
593 unacceptable delays due to internal maintenance functions.
594 --assume-clean
597 Tell mdadm that the array pre-existed and is known to be clean.
598 It can be useful when trying to recover from a major failure as
599 you can be sure that no data will be affected unless you actu‐
600 ally write to the array. It can also be used when creating a
601 RAID1 or RAID10 if you want to avoid the initial resync, however
602 this practice — while normally safe — is not recommended. Use
603 this only if you really know what you are doing.
604 When the devices that will be part of a new array were filled
606 with zeros before creation the operator knows the array is actu‐
607 ally clean. If that is the case, such as after running bad‐
608 blocks, this argument can be used to tell mdadm the facts the
609 operator knows.
610 When an array is resized to a larger size with --grow --size=
612 the new space is normally resynced in that same way that the
613 whole array is resynced at creation. From Linux version 3.0,
614 --assume-clean can be used with that command to avoid the auto‐
615 matic resync.
616 --backup-file=
619 This is needed when --grow is used to increase the number of
620 raid-devices in a RAID5 or RAID6 if there are no spare devices
621 available, or to shrink, change RAID level or layout. See the
622 GROW MODE section below on RAID-DEVICES CHANGES. The file must
623 be stored on a separate device, not on the RAID array being
624 reshaped.
625 --data-offset=
628 Arrays with 1.x metadata can leave a gap between the start of
629 the device and the start of array data. This gap can be used
630 for various metadata. The start of data is known as the
631 data-offset. Normally an appropriate data offset is computed
632 automatically. However it can be useful to set it explicitly
633 such as when re-creating an array which was originally created
634 using a different version of mdadm which computed a different
635 offset.
636 Setting the offset explicitly over-rides the default. The value
638 given is in Kilobytes unless a suffix of 'K', 'M' or 'G' is used
639 to explicitly indicate Kilobytes, Megabytes or Gigabytes respec‐
640 tively.
641 Since Linux 3.4, --data-offset can also be used with --grow for
643 some RAID levels (initially on RAID10). This allows the
644 data-offset to be changed as part of the reshape process. When
645 the data offset is changed, no backup file is required as the
646 difference in offsets is used to provide the same functionality.
647 When the new offset is earlier than the old offset, the number
649 of devices in the array cannot shrink. When it is after the old
650 offset, the number of devices in the array cannot increase.
651 When creating an array, --data-offset can be specified as vari‐
653 able. In the case each member device is expected to have a off‐
654 set appended to the name, separated by a colon. This makes it
655 possible to recreate exactly an array which has varying data
656 offsets (as can happen when different versions of mdadm are used
657 to add different devices).
658 --continue
661 This option is complementary to the --freeze-reshape option for
662 assembly. It is needed when --grow operation is interrupted and
663 it is not restarted automatically due to --freeze-reshape usage
664 during array assembly. This option is used together with -G , (
665 --grow ) command and device for a pending reshape to be contin‐
666 ued. All parameters required for reshape continuation will be
667 read from array metadata. If initial --grow command had
668 required --backup-file= option to be set, continuation option
669 will require to have exactly the same backup file given as well.
670 Any other parameter passed together with --continue option will
672 be ignored.
673 -N, --name=
676 Set a name for the array. This is currently only effective when
677 creating an array with a version-1 superblock, or an array in a
678 DDF container. The name is a simple textual string that can be
679 used to identify array components when assembling. If name is
680 needed but not specified, it is taken from the basename of the
681 device that is being created. e.g. when creating /dev/md/home
682 the name will default to home.
683 -R, --run
686 Insist that mdadm run the array, even if some of the components
687 appear to be active in another array or filesystem. Normally
688 mdadm will ask for confirmation before including such components
689 in an array. This option causes that question to be suppressed.
690 -f, --force
693 Insist that mdadm accept the geometry and layout specified with‐
694 out question. Normally mdadm will not allow creation of an
695 array with only one device, and will try to create a RAID5 array
696 with one missing drive (as this makes the initial resync work
697 faster). With --force, mdadm will not try to be so clever.
698 -o, --readonly
701 Start the array read only rather than read-write as normal. No
702 writes will be allowed to the array, and no resync, recovery, or
703 reshape will be started. It works with Create, Assemble, Manage
704 and Misc mode.
705 -a, --auto{=yes,md,mdp,part,p}{NN}
708 Instruct mdadm how to create the device file if needed, possibly
709 allocating an unused minor number. "md" causes a non-partition‐
710 able array to be used (though since Linux 2.6.28, these array
711 devices are in fact partitionable). "mdp", "part" or "p" causes
712 a partitionable array (2.6 and later) to be used. "yes"
713 requires the named md device to have a 'standard' format, and
714 the type and minor number will be determined from this. With
715 mdadm 3.0, device creation is normally left up to udev so this
716 option is unlikely to be needed. See DEVICE NAMES below.
717 The argument can also come immediately after "-a". e.g. "-ap".
719 If --auto is not given on the command line or in the config
721 file, then the default will be --auto=yes.
722 If --scan is also given, then any auto= entries in the config
724 file will override the --auto instruction given on the command
725 line.
726 For partitionable arrays, mdadm will create the device file for
728 the whole array and for the first 4 partitions. A different
729 number of partitions can be specified at the end of this option
730 (e.g. --auto=p7). If the device name ends with a digit, the
731 partition names add a 'p', and a number, e.g. /dev/md/home1p3.
732 If there is no trailing digit, then the partition names just
733 have a number added, e.g. /dev/md/scratch3.
734 If the md device name is in a 'standard' format as described in
736 DEVICE NAMES, then it will be created, if necessary, with the
737 appropriate device number based on that name. If the device
738 name is not in one of these formats, then a unused device number
739 will be allocated. The device number will be considered unused
740 if there is no active array for that number, and there is no
741 entry in /dev for that number and with a non-standard name.
742 Names that are not in 'standard' format are only allowed in
743 "/dev/md/".
744 This is meaningful with --create or --build.
746 -a, --add
749 This option can be used in Grow mode in two cases.
750 If the target array is a Linear array, then --add can be used to
752 add one or more devices to the array. They are simply catenated
753 on to the end of the array. Once added, the devices cannot be
754 removed.
755 If the --raid-disks option is being used to increase the number
757 of devices in an array, then --add can be used to add some extra
758 devices to be included in the array. In most cases this is not
759 needed as the extra devices can be added as spares first, and
760 then the number of raid-disks can be changed. However for
761 RAID0, it is not possible to add spares. So to increase the
762 number of devices in a RAID0, it is necessary to set the new
763 number of devices, and to add the new devices, in the same com‐
764 mand.
765 --nodes
768 Only works when the array is for clustered environment. It spec‐
769 ifies the maximum number of nodes in the cluster that will use
770 this device simultaneously. If not specified, this defaults to
771 4.
772 --write-journal
775 Specify journal device for the RAID-4/5/6 array. The journal
776 device should be a SSD with reasonable lifetime.
777 --symlinks
780 Auto creation of symlinks in /dev to /dev/md, option --symlinks
781 must be 'no' or 'yes' and work with --create and --build.
782 -k, --consistency-policy=
785 Specify how the array maintains consistency in case of unex‐
786 pected shutdown. Only relevant for RAID levels with redundancy.
787 Currently supported options are:
788 resync Full resync is performed and all redundancy is regener‐
791 ated when the array is started after unclean shutdown.
792 bitmap Resync assisted by a write-intent bitmap. Implicitly
795 selected when using --bitmap.
796 journal
799 For RAID levels 4/5/6, journal device is used to log
800 transactions and replay after unclean shutdown. Implic‐
801 itly selected when using --write-journal.
802 ppl For RAID5 only, Partial Parity Log is used to close the
805 write hole and eliminate resync. PPL is stored in the
806 metadata region of RAID member drives, no additional
807 journal drive is needed.
808 Can be used with --grow to change the consistency policy of an
811 active array in some cases. See CONSISTENCY POLICY CHANGES
812 below.
813
817 -u, --uuid=
818 uuid of array to assemble. Devices which don't have this uuid
819 are excluded
820 -m, --super-minor=
823 Minor number of device that array was created for. Devices
824 which don't have this minor number are excluded. If you create
825 an array as /dev/md1, then all superblocks will contain the
826 minor number 1, even if the array is later assembled as
827 /dev/md2.
828 Giving the literal word "dev" for --super-minor will cause mdadm
830 to use the minor number of the md device that is being assem‐
831 bled. e.g. when assembling /dev/md0, --super-minor=dev will
832 look for super blocks with a minor number of 0.
833 --super-minor is only relevant for v0.90 metadata, and should
835 not normally be used. Using --uuid is much safer.
836 -N, --name=
839 Specify the name of the array to assemble. This must be the
840 name that was specified when creating the array. It must either
841 match the name stored in the superblock exactly, or it must
842 match with the current homehost prefixed to the start of the
843 given name.
844 -f, --force
847 Assemble the array even if the metadata on some devices appears
848 to be out-of-date. If mdadm cannot find enough working devices
849 to start the array, but can find some devices that are recorded
850 as having failed, then it will mark those devices as working so
851 that the array can be started. An array which requires --force
852 to be started may contain data corruption. Use it carefully.
853 -R, --run
856 Attempt to start the array even if fewer drives were given than
857 were present last time the array was active. Normally if not
858 all the expected drives are found and --scan is not used, then
859 the array will be assembled but not started. With --run an
860 attempt will be made to start it anyway.
861 --no-degraded
864 This is the reverse of --run in that it inhibits the startup of
865 array unless all expected drives are present. This is only
866 needed with --scan, and can be used if the physical connections
867 to devices are not as reliable as you would like.
868 -a, --auto{=no,yes,md,mdp,part}
871 See this option under Create and Build options.
872 -b, --bitmap=
875 Specify the bitmap file that was given when the array was cre‐
876 ated. If an array has an internal bitmap, there is no need to
877 specify this when assembling the array.
878 --backup-file=
881 If --backup-file was used while reshaping an array (e.g. chang‐
882 ing number of devices or chunk size) and the system crashed dur‐
883 ing the critical section, then the same --backup-file must be
884 presented to --assemble to allow possibly corrupted data to be
885 restored, and the reshape to be completed.
886 --invalid-backup
889 If the file needed for the above option is not available for any
890 reason an empty file can be given together with this option to
891 indicate that the backup file is invalid. In this case the data
892 that was being rearranged at the time of the crash could be
893 irrecoverably lost, but the rest of the array may still be
894 recoverable. This option should only be used as a last resort
895 if there is no way to recover the backup file.
896 -U, --update=
900 Update the superblock on each device while assembling the array.
901 The argument given to this flag can be one of sparc2.2, sum‐
902 maries, uuid, name, nodes, homehost, home-cluster, resync, byte‐
903 order, devicesize, no-bitmap, bbl, no-bbl, ppl, no-ppl, meta‐
904 data, or super-minor.
905 The sparc2.2 option will adjust the superblock of an array what
907 was created on a Sparc machine running a patched 2.2 Linux ker‐
908 nel. This kernel got the alignment of part of the superblock
909 wrong. You can use the --examine --sparc2.2 option to mdadm to
910 see what effect this would have.
911 The super-minor option will update the preferred minor field on
913 each superblock to match the minor number of the array being
914 assembled. This can be useful if --examine reports a different
915 "Preferred Minor" to --detail. In some cases this update will
916 be performed automatically by the kernel driver. In particular
917 the update happens automatically at the first write to an array
918 with redundancy (RAID level 1 or greater) on a 2.6 (or later)
919 kernel.
920 The uuid option will change the uuid of the array. If a UUID is
922 given with the --uuid option that UUID will be used as a new
923 UUID and will NOT be used to help identify the devices in the
924 array. If no --uuid is given, a random UUID is chosen.
925 The name option will change the name of the array as stored in
927 the superblock. This is only supported for version-1
928 superblocks.
929 The nodes option will change the nodes of the array as stored in
931 the bitmap superblock. This option only works for a clustered
932 environment.
933 The homehost option will change the homehost as recorded in the
935 superblock. For version-0 superblocks, this is the same as
936 updating the UUID. For version-1 superblocks, this involves
937 updating the name.
938 The home-cluster option will change the cluster name as recorded
940 in the superblock and bitmap. This option only works for clus‐
941 tered environment.
942 The resync option will cause the array to be marked dirty mean‐
944 ing that any redundancy in the array (e.g. parity for RAID5,
945 copies for RAID1) may be incorrect. This will cause the RAID
946 system to perform a "resync" pass to make sure that all redun‐
947 dant information is correct.
948 The byteorder option allows arrays to be moved between machines
950 with different byte-order, such as from a big-endian machine
951 like a Sparc or some MIPS machines, to a little-endian x86_64
952 machine. When assembling such an array for the first time after
953 a move, giving --update=byteorder will cause mdadm to expect
954 superblocks to have their byteorder reversed, and will correct
955 that order before assembling the array. This is only valid with
956 original (Version 0.90) superblocks.
957 The summaries option will correct the summaries in the
959 superblock. That is the counts of total, working, active,
960 failed, and spare devices.
961 The devicesize option will rarely be of use. It applies to ver‐
963 sion 1.1 and 1.2 metadata only (where the metadata is at the
964 start of the device) and is only useful when the component
965 device has changed size (typically become larger). The version
966 1 metadata records the amount of the device that can be used to
967 store data, so if a device in a version 1.1 or 1.2 array becomes
968 larger, the metadata will still be visible, but the extra space
969 will not. In this case it might be useful to assemble the array
970 with --update=devicesize. This will cause mdadm to determine
971 the maximum usable amount of space on each device and update the
972 relevant field in the metadata.
973 The metadata option only works on v0.90 metadata arrays and will
975 convert them to v1.0 metadata. The array must not be dirty
976 (i.e. it must not need a sync) and it must not have a write-
977 intent bitmap.
978 The old metadata will remain on the devices, but will appear
980 older than the new metadata and so will usually be ignored. The
981 old metadata (or indeed the new metadata) can be removed by giv‐
982 ing the appropriate --metadata= option to --zero-superblock.
983 The no-bitmap option can be used when an array has an internal
985 bitmap which is corrupt in some way so that assembling the array
986 normally fails. It will cause any internal bitmap to be
987 ignored.
988 The bbl option will reserve space in each device for a bad block
990 list. This will be 4K in size and positioned near the end of
991 any free space between the superblock and the data.
992 The no-bbl option will cause any reservation of space for a bad
994 block list to be removed. If the bad block list contains
995 entries, this will fail, as removing the list could cause data
996 corruption.
997 The ppl option will enable PPL for a RAID5 array and reserve
999 space for PPL on each device. There must be enough free space
1000 between the data and superblock and a write-intent bitmap or
1001 journal must not be used.
1002 The no-ppl option will disable PPL in the superblock.
1004 --freeze-reshape
1007 Option is intended to be used in start-up scripts during initrd
1008 boot phase. When array under reshape is assembled during initrd
1009 phase, this option stops reshape after reshape critical section
1010 is being restored. This happens before file system pivot opera‐
1011 tion and avoids loss of file system context. Losing file system
1012 context would cause reshape to be broken.
1013 Reshape can be continued later using the --continue option for
1015 the grow command.
1016 --symlinks
1019 See this option under Create and Build options.
1020
1023 -t, --test
1024 Unless a more serious error occurred, mdadm will exit with a
1025 status of 2 if no changes were made to the array and 0 if at
1026 least one change was made. This can be useful when an indirect
1027 specifier such as missing, detached or faulty is used in
1028 requesting an operation on the array. --test will report fail‐
1029 ure if these specifiers didn't find any match.
1030 -a, --add
1033 hot-add listed devices. If a device appears to have recently
1034 been part of the array (possibly it failed or was removed) the
1035 device is re-added as described in the next point. If that
1036 fails or the device was never part of the array, the device is
1037 added as a hot-spare. If the array is degraded, it will immedi‐
1038 ately start to rebuild data onto that spare.
1039 Note that this and the following options are only meaningful on
1041 array with redundancy. They don't apply to RAID0 or Linear.
1042 --re-add
1045 re-add a device that was previously removed from an array. If
1046 the metadata on the device reports that it is a member of the
1047 array, and the slot that it used is still vacant, then the
1048 device will be added back to the array in the same position.
1049 This will normally cause the data for that device to be recov‐
1050 ered. However based on the event count on the device, the
1051 recovery may only require sections that are flagged a write-
1052 intent bitmap to be recovered or may not require any recovery at
1053 all.
1054 When used on an array that has no metadata (i.e. it was built
1056 with --build) it will be assumed that bitmap-based recovery is
1057 enough to make the device fully consistent with the array.
1058 When used with v1.x metadata, --re-add can be accompanied by
1060 --update=devicesize, --update=bbl, or --update=no-bbl. See the
1061 description of these option when used in Assemble mode for an
1062 explanation of their use.
1063 If the device name given is missing then mdadm will try to find
1065 any device that looks like it should be part of the array but
1066 isn't and will try to re-add all such devices.
1067 If the device name given is faulty then mdadm will find all
1069 devices in the array that are marked faulty, remove them and
1070 attempt to immediately re-add them. This can be useful if you
1071 are certain that the reason for failure has been resolved.
1072 --add-spare
1075 Add a device as a spare. This is similar to --add except that
1076 it does not attempt --re-add first. The device will be added as
1077 a spare even if it looks like it could be an recent member of
1078 the array.
1079 -r, --remove
1082 remove listed devices. They must not be active. i.e. they
1083 should be failed or spare devices.
1084 As well as the name of a device file (e.g. /dev/sda1) the words
1086 failed, detached and names like set-A can be given to --remove.
1087 The first causes all failed device to be removed. The second
1088 causes any device which is no longer connected to the system
1089 (i.e an 'open' returns ENXIO) to be removed. The third will
1090 remove a set as describe below under --fail.
1091 -f, --fail
1094 Mark listed devices as faulty. As well as the name of a device
1095 file, the word detached or a set name like set-A can be given.
1096 The former will cause any device that has been detached from the
1097 system to be marked as failed. It can then be removed.
1098 For RAID10 arrays where the number of copies evenly divides the
1100 number of devices, the devices can be conceptually divided into
1101 sets where each set contains a single complete copy of the data
1102 on the array. Sometimes a RAID10 array will be configured so
1103 that these sets are on separate controllers. In this case all
1104 the devices in one set can be failed by giving a name like set-A
1105 or set-B to --fail. The appropriate set names are reported by
1106 --detail.
1107 --set-faulty
1110 same as --fail.
1111 --replace
1114 Mark listed devices as requiring replacement. As soon as a
1115 spare is available, it will be rebuilt and will replace the
1116 marked device. This is similar to marking a device as faulty,
1117 but the device remains in service during the recovery process to
1118 increase resilience against multiple failures. When the
1119 replacement process finishes, the replaced device will be marked
1120 as faulty.
1121 --with This can follow a list of --replace devices. The devices listed
1124 after --with will be preferentially used to replace the devices
1125 listed after --replace. These device must already be spare
1126 devices in the array.
1127 --write-mostly
1130 Subsequent devices that are added or re-added will have the
1131 'write-mostly' flag set. This is only valid for RAID1 and means
1132 that the 'md' driver will avoid reading from these devices if
1133 possible.
1134 --readwrite
1136 Subsequent devices that are added or re-added will have the
1137 'write-mostly' flag cleared.
1138 --cluster-confirm
1140 Confirm the existence of the device. This is issued in response
1141 to an --add request by a node in a cluster. When a node adds a
1142 device it sends a message to all nodes in the cluster to look
1143 for a device with a UUID. This translates to a udev notification
1144 with the UUID of the device to be added and the slot number. The
1145 receiving node must acknowledge this message with --cluster-con‐
1146 firm. Valid arguments are <slot>:<devicename> in case the device
1147 is found or <slot>:missing in case the device is not found.
1148 --add-journal
1151 Add journal to an existing array, or recreate journal for
1152 RAID-4/5/6 array that lost a journal device. To avoid interrupt‐
1153 ing on-going write opertions, --add-journal only works for array
1154 in Read-Only state.
1155 --failfast
1158 Subsequent devices that are added or re-added will have the
1159 'failfast' flag set. This is only valid for RAID1 and RAID10
1160 and means that the 'md' driver will avoid long timeouts on error
1161 handling where possible.
1162 --nofailfast
1164 Subsequent devices that are re-added will be re-added without
1165 the 'failfast' flag set.
1166 Each of these options requires that the first device listed is the
1169 array to be acted upon, and the remainder are component devices to be
1170 added, removed, marked as faulty, etc. Several different operations
1171 can be specified for different devices, e.g.
1172 mdadm /dev/md0 --add /dev/sda1 --fail /dev/sdb1 --remove /dev/sdb1
1173 Each operation applies to all devices listed until the next operation.
1174 If an array is using a write-intent bitmap, then devices which have
1176 been removed can be re-added in a way that avoids a full reconstruction
1177 but instead just updates the blocks that have changed since the device
1178 was removed. For arrays with persistent metadata (superblocks) this is
1179 done automatically. For arrays created with --build mdadm needs to be
1180 told that this device we removed recently with --re-add.
1181 Devices can only be removed from an array if they are not in active
1183 use, i.e. that must be spares or failed devices. To remove an active
1184 device, it must first be marked as faulty.
1185
1188 -Q, --query
1189 Examine a device to see (1) if it is an md device and (2) if it
1190 is a component of an md array. Information about what is dis‐
1191 covered is presented.
1192 -D, --detail
1195 Print details of one or more md devices.
1196 --detail-platform
1199 Print details of the platform's RAID capabilities (firmware /
1200 hardware topology) for a given metadata format. If used without
1201 argument, mdadm will scan all controllers looking for their
1202 capabilities. Otherwise, mdadm will only look at the controller
1203 specified by the argument in form of an absolute filepath or a
1204 link, e.g. /sys/devices/pci0000:00/0000:00:1f.2.
1205 -Y, --export
1208 When used with --detail, --detail-platform, --examine, or
1209 --incremental output will be formatted as key=value pairs for
1210 easy import into the environment.
1211 With --incremental The value MD_STARTED indicates whether an
1213 array was started (yes) or not, which may include a reason
1214 (unsafe, nothing, no). Also the value MD_FOREIGN indicates if
1215 the array is expected on this host (no), or seems to be from
1216 elsewhere (yes).
1217 -E, --examine
1220 Print contents of the metadata stored on the named device(s).
1221 Note the contrast between --examine and --detail. --examine
1222 applies to devices which are components of an array, while
1223 --detail applies to a whole array which is currently active.
1224 --sparc2.2
1226 If an array was created on a SPARC machine with a 2.2 Linux ker‐
1227 nel patched with RAID support, the superblock will have been
1228 created incorrectly, or at least incompatibly with 2.4 and later
1229 kernels. Using the --sparc2.2 flag with --examine will fix the
1230 superblock before displaying it. If this appears to do the
1231 right thing, then the array can be successfully assembled using
1232 --assemble --update=sparc2.2.
1233 -X, --examine-bitmap
1236 Report information about a bitmap file. The argument is either
1237 an external bitmap file or an array component in case of an
1238 internal bitmap. Note that running this on an array device
1239 (e.g. /dev/md0) does not report the bitmap for that array.
1240 --examine-badblocks
1243 List the bad-blocks recorded for the device, if a bad-blocks
1244 list has been configured. Currently only 1.x metadata supports
1245 bad-blocks lists.
1246 --dump=directory
1249 --restore=directory
1251 Save metadata from lists devices, or restore metadata to listed
1252 devices.
1253 -R, --run
1256 start a partially assembled array. If --assemble did not find
1257 enough devices to fully start the array, it might leaving it
1258 partially assembled. If you wish, you can then use --run to
1259 start the array in degraded mode.
1260 -S, --stop
1263 deactivate array, releasing all resources.
1264 -o, --readonly
1267 mark array as readonly.
1268 -w, --readwrite
1271 mark array as readwrite.
1272 --zero-superblock
1275 If the device contains a valid md superblock, the block is over‐
1276 written with zeros. With --force the block where the superblock
1277 would be is overwritten even if it doesn't appear to be valid.
1278 Note: Be careful to call --zero-superblock with clustered raid,
1280 make sure array isn't used or assembled in other cluster node
1281 before execute it.
1282 --kill-subarray=
1285 If the device is a container and the argument to --kill-subarray
1286 specifies an inactive subarray in the container, then the subar‐
1287 ray is deleted. Deleting all subarrays will leave an 'empty-
1288 container' or spare superblock on the drives. See
1289 --zero-superblock for completely removing a superblock. Note
1290 that some formats depend on the subarray index for generating a
1291 UUID, this command will fail if it would change the UUID of an
1292 active subarray.
1293 --update-subarray=
1296 If the device is a container and the argument to --update-subar‐
1297 ray specifies a subarray in the container, then attempt to
1298 update the given superblock field in the subarray. See below in
1299 MISC MODE for details.
1300 -t, --test
1303 When used with --detail, the exit status of mdadm is set to
1304 reflect the status of the device. See below in MISC MODE for
1305 details.
1306 -W, --wait
1309 For each md device given, wait for any resync, recovery, or
1310 reshape activity to finish before returning. mdadm will return
1311 with success if it actually waited for every device listed, oth‐
1312 erwise it will return failure.
1313 --wait-clean
1316 For each md device given, or each device in /proc/mdstat if
1317 --scan is given, arrange for the array to be marked clean as
1318 soon as possible. mdadm will return with success if the array
1319 uses external metadata and we successfully waited. For native
1320 arrays this returns immediately as the kernel handles dirty-
1321 clean transitions at shutdown. No action is taken if safe-mode
1322 handling is disabled.
1323 --action=
1326 Set the "sync_action" for all md devices given to one of idle,
1327 frozen, check, repair. Setting to idle will abort any currently
1328 running action though some actions will automatically restart.
1329 Setting to frozen will abort any current action and ensure no
1330 other action starts automatically.
1331 Details of check and repair can be found it md(4) under SCRUB‐
1333 BING AND MISMATCHES.
1334
1337 --rebuild-map, -r
1338 Rebuild the map file (/run/mdadm/map) that mdadm uses to help
1339 track which arrays are currently being assembled.
1340 --run, -R
1343 Run any array assembled as soon as a minimal number of devices
1344 are available, rather than waiting until all expected devices
1345 are present.
1346 --scan, -s
1349 Only meaningful with -R this will scan the map file for arrays
1350 that are being incrementally assembled and will try to start any
1351 that are not already started. If any such array is listed in
1352 mdadm.conf as requiring an external bitmap, that bitmap will be
1353 attached first.
1354 --fail, -f
1357 This allows the hot-plug system to remove devices that have
1358 fully disappeared from the kernel. It will first fail and then
1359 remove the device from any array it belongs to. The device name
1360 given should be a kernel device name such as "sda", not a name
1361 in /dev.
1362 --path=
1365 Only used with --fail. The 'path' given will be recorded so
1366 that if a new device appears at the same location it can be
1367 automatically added to the same array. This allows the failed
1368 device to be automatically replaced by a new device without
1369 metadata if it appears at specified path. This option is nor‐
1370 mally only set by a udev script.
1371
1374 -m, --mail
1375 Give a mail address to send alerts to.
1376 -p, --program, --alert
1379 Give a program to be run whenever an event is detected.
1380 -y, --syslog
1383 Cause all events to be reported through 'syslog'. The messages
1384 have facility of 'daemon' and varying priorities.
1385 -d, --delay
1388 Give a delay in seconds. mdadm polls the md arrays and then
1389 waits this many seconds before polling again. The default is 60
1390 seconds. Since 2.6.16, there is no need to reduce this as the
1391 kernel alerts mdadm immediately when there is any change.
1392 -r, --increment
1395 Give a percentage increment. mdadm will generate RebuildNN
1396 events with the given percentage increment.
1397 -f, --daemonise
1400 Tell mdadm to run as a background daemon if it decides to moni‐
1401 tor anything. This causes it to fork and run in the child, and
1402 to disconnect from the terminal. The process id of the child is
1403 written to stdout. This is useful with --scan which will only
1404 continue monitoring if a mail address or alert program is found
1405 in the config file.
1406 -i, --pid-file
1409 When mdadm is running in daemon mode, write the pid of the dae‐
1410 mon process to the specified file, instead of printing it on
1411 standard output.
1412 -1, --oneshot
1415 Check arrays only once. This will generate NewArray events and
1416 more significantly DegradedArray and SparesMissing events. Run‐
1417 ning
1418 mdadm --monitor --scan -1
1419 from a cron script will ensure regular notification of any
1420 degraded arrays.
1421 -t, --test
1424 Generate a TestMessage alert for every array found at startup.
1425 This alert gets mailed and passed to the alert program. This
1426 can be used for testing that alert message do get through suc‐
1427 cessfully.
1428 --no-sharing
1431 This inhibits the functionality for moving spares between
1432 arrays. Only one monitoring process started with --scan but
1433 without this flag is allowed, otherwise the two could interfere
1434 with each other.
1435
1438 Usage: mdadm --assemble md-device options-and-component-devices...
1439 Usage: mdadm --assemble --scan md-devices-and-options...
1441 Usage: mdadm --assemble --scan options...
1443 This usage assembles one or more RAID arrays from pre-existing compo‐
1446 nents. For each array, mdadm needs to know the md device, the identity
1447 of the array, and a number of component-devices. These can be found in
1448 a number of ways.
1449 In the first usage example (without the --scan) the first device given
1451 is the md device. In the second usage example, all devices listed are
1452 treated as md devices and assembly is attempted. In the third (where
1453 no devices are listed) all md devices that are listed in the configura‐
1454 tion file are assembled. If no arrays are described by the configura‐
1455 tion file, then any arrays that can be found on unused devices will be
1456 assembled.
1457 If precisely one device is listed, but --scan is not given, then mdadm
1459 acts as though --scan was given and identity information is extracted
1460 from the configuration file.
1461 The identity can be given with the --uuid option, the --name option, or
1463 the --super-minor option, will be taken from the md-device record in
1464 the config file, or will be taken from the super block of the first
1465 component-device listed on the command line.
1466 Devices can be given on the --assemble command line or in the config
1468 file. Only devices which have an md superblock which contains the
1469 right identity will be considered for any array.
1470 The config file is only used if explicitly named with --config or
1472 requested with (a possibly implicit) --scan. In the later case,
1473 /etc/mdadm.conf or /etc/mdadm/mdadm.conf is used.
1474 If --scan is not given, then the config file will only be used to find
1476 the identity of md arrays.
1477 Normally the array will be started after it is assembled. However if
1479 --scan is not given and not all expected drives were listed, then the
1480 array is not started (to guard against usage errors). To insist that
1481 the array be started in this case (as may work for RAID1, 4, 5, 6, or
1482 10), give the --run flag.
1483 If udev is active, mdadm does not create any entries in /dev but leaves
1485 that to udev. It does record information in /run/mdadm/map which will
1486 allow udev to choose the correct name.
1487 If mdadm detects that udev is not configured, it will create the
1489 devices in /dev itself.
1490 In Linux kernels prior to version 2.6.28 there were two distinctly dif‐
1492 ferent types of md devices that could be created: one that could be
1493 partitioned using standard partitioning tools and one that could not.
1494 Since 2.6.28 that distinction is no longer relevant as both type of
1495 devices can be partitioned. mdadm will normally create the type that
1496 originally could not be partitioned as it has a well defined major num‐
1497 ber (9).
1498 Prior to 2.6.28, it is important that mdadm chooses the correct type of
1500 array device to use. This can be controlled with the --auto option.
1501 In particular, a value of "mdp" or "part" or "p" tells mdadm to use a
1502 partitionable device rather than the default.
1503 In the no-udev case, the value given to --auto can be suffixed by a
1505 number. This tells mdadm to create that number of partition devices
1506 rather than the default of 4.
1507 The value given to --auto can also be given in the configuration file
1509 as a word starting auto= on the ARRAY line for the relevant array.
1510 Auto Assembly
1513 When --assemble is used with --scan and no devices are listed, mdadm
1514 will first attempt to assemble all the arrays listed in the config
1515 file.
1516 If no arrays are listed in the config (other than those marked
1518 <ignore>) it will look through the available devices for possible
1519 arrays and will try to assemble anything that it finds. Arrays which
1520 are tagged as belonging to the given homehost will be assembled and
1521 started normally. Arrays which do not obviously belong to this host
1522 are given names that are expected not to conflict with anything local,
1523 and are started "read-auto" so that nothing is written to any device
1524 until the array is written to. i.e. automatic resync etc is delayed.
1525 If mdadm finds a consistent set of devices that look like they should
1527 comprise an array, and if the superblock is tagged as belonging to the
1528 given home host, it will automatically choose a device name and try to
1529 assemble the array. If the array uses version-0.90 metadata, then the
1530 minor number as recorded in the superblock is used to create a name in
1531 /dev/md/ so for example /dev/md/3. If the array uses version-1 meta‐
1532 data, then the name from the superblock is used to similarly create a
1533 name in /dev/md/ (the name will have any 'host' prefix stripped first).
1534 This behaviour can be modified by the AUTO line in the mdadm.conf con‐
1536 figuration file. This line can indicate that specific metadata type
1537 should, or should not, be automatically assembled. If an array is
1538 found which is not listed in mdadm.conf and has a metadata format that
1539 is denied by the AUTO line, then it will not be assembled. The AUTO
1540 line can also request that all arrays identified as being for this
1541 homehost should be assembled regardless of their metadata type. See
1542 mdadm.conf(5) for further details.
1543 Note: Auto assembly cannot be used for assembling and activating some
1545 arrays which are undergoing reshape. In particular as the backup-file
1546 cannot be given, any reshape which requires a backup-file to continue
1547 cannot be started by auto assembly. An array which is growing to more
1548 devices and has passed the critical section can be assembled using
1549 auto-assembly.
1550
1553 Usage: mdadm --build md-device --chunk=X --level=Y --raid-devices=Z
1554 devices
1555 This usage is similar to --create. The difference is that it creates
1558 an array without a superblock. With these arrays there is no differ‐
1559 ence between initially creating the array and subsequently assembling
1560 the array, except that hopefully there is useful data there in the sec‐
1561 ond case.
1562 The level may raid0, linear, raid1, raid10, multipath, or faulty, or
1564 one of their synonyms. All devices must be listed and the array will
1565 be started once complete. It will often be appropriate to use
1566 --assume-clean with levels raid1 or raid10.
1567
1570 Usage: mdadm --create md-device --chunk=X --level=Y
1571 --raid-devices=Z devices
1572 This usage will initialise a new md array, associate some devices with
1575 it, and activate the array.
1576 The named device will normally not exist when mdadm --create is run,
1578 but will be created by udev once the array becomes active.
1579 As devices are added, they are checked to see if they contain RAID
1581 superblocks or filesystems. They are also checked to see if the vari‐
1582 ance in device size exceeds 1%.
1583 If any discrepancy is found, the array will not automatically be run,
1585 though the presence of a --run can override this caution.
1586 To create a "degraded" array in which some devices are missing, simply
1588 give the word "missing" in place of a device name. This will cause
1589 mdadm to leave the corresponding slot in the array empty. For a RAID4
1590 or RAID5 array at most one slot can be "missing"; for a RAID6 array at
1591 most two slots. For a RAID1 array, only one real device needs to be
1592 given. All of the others can be "missing".
1593 When creating a RAID5 array, mdadm will automatically create a degraded
1595 array with an extra spare drive. This is because building the spare
1596 into a degraded array is in general faster than resyncing the parity on
1597 a non-degraded, but not clean, array. This feature can be overridden
1598 with the --force option.
1599 When creating an array with version-1 metadata a name for the array is
1601 required. If this is not given with the --name option, mdadm will
1602 choose a name based on the last component of the name of the device
1603 being created. So if /dev/md3 is being created, then the name 3 will
1604 be chosen. If /dev/md/home is being created, then the name home will
1605 be used.
1606 When creating a partition based array, using mdadm with version-1.x
1608 metadata, the partition type should be set to 0xDA (non fs-data). This
1609 type selection allows for greater precision since using any other [RAID
1610 auto-detect (0xFD) or a GNU/Linux partition (0x83)], might create prob‐
1611 lems in the event of array recovery through a live cdrom.
1612 A new array will normally get a randomly assigned 128bit UUID which is
1614 very likely to be unique. If you have a specific need, you can choose
1615 a UUID for the array by giving the --uuid= option. Be warned that cre‐
1616 ating two arrays with the same UUID is a recipe for disaster. Also,
1617 using --uuid= when creating a v0.90 array will silently override any
1618 --homehost= setting.
1619 If the array type supports a write-intent bitmap, and if the devices in
1621 the array exceed 100G is size, an internal write-intent bitmap will
1622 automatically be added unless some other option is explicitly requested
1623 with the --bitmap option or a different consistency policy is selected
1624 with the --consistency-policy option. In any case space for a bitmap
1625 will be reserved so that one can be added later with --grow --bit‐
1626 map=internal.
1627 If the metadata type supports it (currently only 1.x and IMSM meta‐
1629 data), space will be allocated to store a bad block list. This allows
1630 a modest number of bad blocks to be recorded, allowing the drive to
1631 remain in service while only partially functional.
1632 When creating an array within a CONTAINER mdadm can be given either the
1634 list of devices to use, or simply the name of the container. The for‐
1635 mer case gives control over which devices in the container will be used
1636 for the array. The latter case allows mdadm to automatically choose
1637 which devices to use based on how much spare space is available.
1638 The General Management options that are valid with --create are:
1640 --run insist on running the array even if some devices look like they
1642 might be in use.
1643 --readonly
1646 start the array in readonly mode.
1647
1650 Usage: mdadm device options... devices...
1651 This usage will allow individual devices in an array to be failed,
1653 removed or added. It is possible to perform multiple operations with
1654 on command. For example:
1655 mdadm /dev/md0 -f /dev/hda1 -r /dev/hda1 -a /dev/hda1
1656 will firstly mark /dev/hda1 as faulty in /dev/md0 and will then remove
1657 it from the array and finally add it back in as a spare. However only
1658 one md array can be affected by a single command.
1659 When a device is added to an active array, mdadm checks to see if it
1661 has metadata on it which suggests that it was recently a member of the
1662 array. If it does, it tries to "re-add" the device. If there have
1663 been no changes since the device was removed, or if the array has a
1664 write-intent bitmap which has recorded whatever changes there were,
1665 then the device will immediately become a full member of the array and
1666 those differences recorded in the bitmap will be resolved.
1667
1670 Usage: mdadm options ... devices ...
1671 MISC mode includes a number of distinct operations that operate on dis‐
1673 tinct devices. The operations are:
1674 --query
1676 The device is examined to see if it is (1) an active md array,
1677 or (2) a component of an md array. The information discovered
1678 is reported.
1679 --detail
1682 The device should be an active md device. mdadm will display a
1683 detailed description of the array. --brief or --scan will cause
1684 the output to be less detailed and the format to be suitable for
1685 inclusion in mdadm.conf. The exit status of mdadm will normally
1686 be 0 unless mdadm failed to get useful information about the
1687 device(s); however, if the --test option is given, then the exit
1688 status will be:
1689 0 The array is functioning normally.
1691 1 The array has at least one failed device.
1693 2 The array has multiple failed devices such that it is
1695 unusable.
1696 4 There was an error while trying to get information about
1698 the device.
1699 --detail-platform
1702 Print detail of the platform's RAID capabilities (firmware /
1703 hardware topology). If the metadata is specified with -e or
1704 --metadata= then the return status will be:
1705 0 metadata successfully enumerated its platform components
1707 on this system
1708 1 metadata is platform independent
1710 2 metadata failed to find its platform components on this
1712 system
1713 --update-subarray=
1716 If the device is a container and the argument to --update-subar‐
1717 ray specifies a subarray in the container, then attempt to
1718 update the given superblock field in the subarray. Similar to
1719 updating an array in "assemble" mode, the field to update is
1720 selected by -U or --update= option. The supported options are
1721 name, ppl and no-ppl.
1722 The name option updates the subarray name in the metadata, it
1724 may not affect the device node name or the device node symlink
1725 until the subarray is re-assembled. If updating name would
1726 change the UUID of an active subarray this operation is blocked,
1727 and the command will end in an error.
1728 The ppl and no-ppl options enable and disable PPL in the meta‐
1730 data. Currently supported only for IMSM subarrays.
1731 --examine
1734 The device should be a component of an md array. mdadm will
1735 read the md superblock of the device and display the contents.
1736 If --brief or --scan is given, then multiple devices that are
1737 components of the one array are grouped together and reported in
1738 a single entry suitable for inclusion in mdadm.conf.
1739 Having --scan without listing any devices will cause all devices
1741 listed in the config file to be examined.
1742 --dump=directory
1745 If the device contains RAID metadata, a file will be created in
1746 the directory and the metadata will be written to it. The file
1747 will be the same size as the device and have the metadata writ‐
1748 ten in the file at the same locate that it exists in the device.
1749 However the file will be "sparse" so that only those blocks con‐
1750 taining metadata will be allocated. The total space used will be
1751 small.
1752 The file name used in the directory will be the base name of the
1754 device. Further if any links appear in /dev/disk/by-id which
1755 point to the device, then hard links to the file will be created
1756 in directory based on these by-id names.
1757 Multiple devices can be listed and their metadata will all be
1759 stored in the one directory.
1760 --restore=directory
1763 This is the reverse of --dump. mdadm will locate a file in the
1764 directory that has a name appropriate for the given device and
1765 will restore metadata from it. Names that match /dev/disk/by-id
1766 names are preferred, however if two of those refer to different
1767 files, mdadm will not choose between them but will abort the
1768 operation.
1769 If a file name is given instead of a directory then mdadm will
1771 restore from that file to a single device, always provided the
1772 size of the file matches that of the device, and the file con‐
1773 tains valid metadata.
1774 --stop The devices should be active md arrays which will be deacti‐
1776 vated, as long as they are not currently in use.
1777 --run This will fully activate a partially assembled md array.
1780 --readonly
1783 This will mark an active array as read-only, providing that it
1784 is not currently being used.
1785 --readwrite
1788 This will change a readonly array back to being read/write.
1789 --scan For all operations except --examine, --scan will cause the oper‐
1792 ation to be applied to all arrays listed in /proc/mdstat. For
1793 --examine, --scan causes all devices listed in the config file
1794 to be examined.
1795 -b, --brief
1798 Be less verbose. This is used with --detail and --examine.
1799 Using --brief with --verbose gives an intermediate level of ver‐
1800 bosity.
1801
1804 Usage: mdadm --monitor options... devices...
1805 This usage causes mdadm to periodically poll a number of md arrays and
1808 to report on any events noticed. mdadm will never exit once it decides
1809 that there are arrays to be checked, so it should normally be run in
1810 the background.
1811 As well as reporting events, mdadm may move a spare drive from one
1813 array to another if they are in the same spare-group or domain and if
1814 the destination array has a failed drive but no spares.
1815 If any devices are listed on the command line, mdadm will only monitor
1817 those devices. Otherwise all arrays listed in the configuration file
1818 will be monitored. Further, if --scan is given, then any other md
1819 devices that appear in /proc/mdstat will also be monitored.
1820 The result of monitoring the arrays is the generation of events. These
1822 events are passed to a separate program (if specified) and may be
1823 mailed to a given E-mail address.
1824 When passing events to a program, the program is run once for each
1826 event, and is given 2 or 3 command-line arguments: the first is the
1827 name of the event (see below), the second is the name of the md device
1828 which is affected, and the third is the name of a related device if
1829 relevant (such as a component device that has failed).
1830 If --scan is given, then a program or an E-mail address must be speci‐
1832 fied on the command line or in the config file. If neither are avail‐
1833 able, then mdadm will not monitor anything. Without --scan, mdadm will
1834 continue monitoring as long as something was found to monitor. If no
1835 program or email is given, then each event is reported to stdout.
1836 The different events are:
1838 DeviceDisappeared
1841 An md array which previously was configured appears to no
1842 longer be configured. (syslog priority: Critical)
1843 If mdadm was told to monitor an array which is RAID0 or Lin‐
1845 ear, then it will report DeviceDisappeared with the extra
1846 information Wrong-Level. This is because RAID0 and Linear
1847 do not support the device-failed, hot-spare and resync oper‐
1848 ations which are monitored.
1849 RebuildStarted
1852 An md array started reconstruction (e.g. recovery, resync,
1853 reshape, check, repair). (syslog priority: Warning)
1854 RebuildNN
1857 Where NN is a two-digit number (ie. 05, 48). This indicates
1858 that rebuild has passed that many percent of the total. The
1859 events are generated with fixed increment since 0. Increment
1860 size may be specified with a commandline option (default is
1861 20). (syslog priority: Warning)
1862 RebuildFinished
1865 An md array that was rebuilding, isn't any more, either
1866 because it finished normally or was aborted. (syslog prior‐
1867 ity: Warning)
1868 Fail An active component device of an array has been marked as
1871 faulty. (syslog priority: Critical)
1872 FailSpare
1875 A spare component device which was being rebuilt to replace
1876 a faulty device has failed. (syslog priority: Critical)
1877 SpareActive
1880 A spare component device which was being rebuilt to replace
1881 a faulty device has been successfully rebuilt and has been
1882 made active. (syslog priority: Info)
1883 NewArray
1886 A new md array has been detected in the /proc/mdstat file.
1887 (syslog priority: Info)
1888 DegradedArray
1891 A newly noticed array appears to be degraded. This message
1892 is not generated when mdadm notices a drive failure which
1893 causes degradation, but only when mdadm notices that an
1894 array is degraded when it first sees the array. (syslog
1895 priority: Critical)
1896 MoveSpare
1899 A spare drive has been moved from one array in a spare-group
1900 or domain to another to allow a failed drive to be replaced.
1901 (syslog priority: Info)
1902 SparesMissing
1905 If mdadm has been told, via the config file, that an array
1906 should have a certain number of spare devices, and mdadm
1907 detects that it has fewer than this number when it first
1908 sees the array, it will report a SparesMissing message.
1909 (syslog priority: Warning)
1910 TestMessage
1913 An array was found at startup, and the --test flag was
1914 given. (syslog priority: Info)
1915 Only Fail, FailSpare, DegradedArray, SparesMissing and TestMessage
1917 cause Email to be sent. All events cause the program to be run. The
1918 program is run with two or three arguments: the event name, the array
1919 device and possibly a second device.
1920 Each event has an associated array device (e.g. /dev/md1) and possibly
1922 a second device. For Fail, FailSpare, and SpareActive the second
1923 device is the relevant component device. For MoveSpare the second
1924 device is the array that the spare was moved from.
1925 For mdadm to move spares from one array to another, the different
1927 arrays need to be labeled with the same spare-group or the spares must
1928 be allowed to migrate through matching POLICY domains in the configura‐
1929 tion file. The spare-group name can be any string; it is only neces‐
1930 sary that different spare groups use different names.
1931 When mdadm detects that an array in a spare group has fewer active
1933 devices than necessary for the complete array, and has no spare
1934 devices, it will look for another array in the same spare group that
1935 has a full complement of working drive and a spare. It will then
1936 attempt to remove the spare from the second drive and add it to the
1937 first. If the removal succeeds but the adding fails, then it is added
1938 back to the original array.
1939 If the spare group for a degraded array is not defined, mdadm will look
1941 at the rules of spare migration specified by POLICY lines in mdadm.conf
1942 and then follow similar steps as above if a matching spare is found.
1943
1946 The GROW mode is used for changing the size or shape of an active
1947 array. For this to work, the kernel must support the necessary change.
1948 Various types of growth are being added during 2.6 development.
1949 Currently the supported changes include
1951 · change the "size" attribute for RAID1, RAID4, RAID5 and RAID6.
1953 · increase or decrease the "raid-devices" attribute of RAID0, RAID1,
1955 RAID4, RAID5, and RAID6.
1956 · change the chunk-size and layout of RAID0, RAID4, RAID5, RAID6 and
1958 RAID10.
1959 · convert between RAID1 and RAID5, between RAID5 and RAID6, between
1961 RAID0, RAID4, and RAID5, and between RAID0 and RAID10 (in the
1962 near-2 mode).
1963 · add a write-intent bitmap to any array which supports these bit‐
1965 maps, or remove a write-intent bitmap from such an array.
1966 · change the array's consistency policy.
1968 Using GROW on containers is currently supported only for Intel's IMSM
1970 container format. The number of devices in a container can be
1971 increased - which affects all arrays in the container - or an array in
1972 a container can be converted between levels where those levels are sup‐
1973 ported by the container, and the conversion is on of those listed
1974 above. Resizing arrays in an IMSM container with --grow --size is not
1975 yet supported.
1976 Notes:
1979 · Intel's native checkpointing doesn't use --backup-file option and
1981 it is transparent for assembly feature.
1982 · Roaming between Windows(R) and Linux systems for IMSM metadata is
1984 not supported during grow process.
1985 SIZE CHANGES
1988 Normally when an array is built the "size" is taken from the smallest
1989 of the drives. If all the small drives in an arrays are, one at a
1990 time, removed and replaced with larger drives, then you could have an
1991 array of large drives with only a small amount used. In this situa‐
1992 tion, changing the "size" with "GROW" mode will allow the extra space
1993 to start being used. If the size is increased in this way, a "resync"
1994 process will start to make sure the new parts of the array are synchro‐
1995 nised.
1996 Note that when an array changes size, any filesystem that may be stored
1998 in the array will not automatically grow or shrink to use or vacate the
1999 space. The filesystem will need to be explicitly told to use the extra
2000 space after growing, or to reduce its size prior to shrinking the
2001 array.
2002 Also the size of an array cannot be changed while it has an active bit‐
2004 map. If an array has a bitmap, it must be removed before the size can
2005 be changed. Once the change is complete a new bitmap can be created.
2006 Note: --grow --size is not yet supported for external file bitmap.
2009 RAID-DEVICES CHANGES
2012 A RAID1 array can work with any number of devices from 1 upwards
2013 (though 1 is not very useful). There may be times which you want to
2014 increase or decrease the number of active devices. Note that this is
2015 different to hot-add or hot-remove which changes the number of inactive
2016 devices.
2017 When reducing the number of devices in a RAID1 array, the slots which
2019 are to be removed from the array must already be vacant. That is, the
2020 devices which were in those slots must be failed and removed.
2021 When the number of devices is increased, any hot spares that are
2023 present will be activated immediately.
2024 Changing the number of active devices in a RAID5 or RAID6 is much more
2026 effort. Every block in the array will need to be read and written back
2027 to a new location. From 2.6.17, the Linux Kernel is able to increase
2028 the number of devices in a RAID5 safely, including restarting an inter‐
2029 rupted "reshape". From 2.6.31, the Linux Kernel is able to increase or
2030 decrease the number of devices in a RAID5 or RAID6.
2031 From 2.6.35, the Linux Kernel is able to convert a RAID0 in to a RAID4
2033 or RAID5. mdadm uses this functionality and the ability to add devices
2034 to a RAID4 to allow devices to be added to a RAID0. When requested to
2035 do this, mdadm will convert the RAID0 to a RAID4, add the necessary
2036 disks and make the reshape happen, and then convert the RAID4 back to
2037 RAID0.
2038 When decreasing the number of devices, the size of the array will also
2040 decrease. If there was data in the array, it could get destroyed and
2041 this is not reversible, so you should firstly shrink the filesystem on
2042 the array to fit within the new size. To help prevent accidents, mdadm
2043 requires that the size of the array be decreased first with mdadm
2044 --grow --array-size. This is a reversible change which simply makes
2045 the end of the array inaccessible. The integrity of any data can then
2046 be checked before the non-reversible reduction in the number of devices
2047 is request.
2048 When relocating the first few stripes on a RAID5 or RAID6, it is not
2050 possible to keep the data on disk completely consistent and crash-
2051 proof. To provide the required safety, mdadm disables writes to the
2052 array while this "critical section" is reshaped, and takes a backup of
2053 the data that is in that section. For grows, this backup may be stored
2054 in any spare devices that the array has, however it can also be stored
2055 in a separate file specified with the --backup-file option, and is
2056 required to be specified for shrinks, RAID level changes and layout
2057 changes. If this option is used, and the system does crash during the
2058 critical period, the same file must be passed to --assemble to restore
2059 the backup and reassemble the array. When shrinking rather than grow‐
2060 ing the array, the reshape is done from the end towards the beginning,
2061 so the "critical section" is at the end of the reshape.
2062 LEVEL CHANGES
2065 Changing the RAID level of any array happens instantaneously. However
2066 in the RAID5 to RAID6 case this requires a non-standard layout of the
2067 RAID6 data, and in the RAID6 to RAID5 case that non-standard layout is
2068 required before the change can be accomplished. So while the level
2069 change is instant, the accompanying layout change can take quite a long
2070 time. A --backup-file is required. If the array is not simultaneously
2071 being grown or shrunk, so that the array size will remain the same -
2072 for example, reshaping a 3-drive RAID5 into a 4-drive RAID6 - the
2073 backup file will be used not just for a "cricital section" but through‐
2074 out the reshape operation, as described below under LAYOUT CHANGES.
2075 CHUNK-SIZE AND LAYOUT CHANGES
2078 Changing the chunk-size of layout without also changing the number of
2079 devices as the same time will involve re-writing all blocks in-place.
2080 To ensure against data loss in the case of a crash, a --backup-file
2081 must be provided for these changes. Small sections of the array will
2082 be copied to the backup file while they are being rearranged. This
2083 means that all the data is copied twice, once to the backup and once to
2084 the new layout on the array, so this type of reshape will go very
2085 slowly.
2086 If the reshape is interrupted for any reason, this backup file must be
2088 made available to mdadm --assemble so the array can be reassembled.
2089 Consequently the file cannot be stored on the device being reshaped.
2090 BITMAP CHANGES
2094 A write-intent bitmap can be added to, or removed from, an active
2095 array. Either internal bitmaps, or bitmaps stored in a separate file,
2096 can be added. Note that if you add a bitmap stored in a file which is
2097 in a filesystem that is on the RAID array being affected, the system
2098 will deadlock. The bitmap must be on a separate filesystem.
2099 CONSISTENCY POLICY CHANGES
2102 The consistency policy of an active array can be changed by using the
2103 --consistency-policy option in Grow mode. Currently this works only for
2104 the ppl and resync policies and allows to enable or disable the RAID5
2105 Partial Parity Log (PPL).
2106
2109 Usage: mdadm --incremental [--run] [--quiet] component-device
2110 [optional-aliases-for-device]
2111 Usage: mdadm --incremental --fail component-device
2113 Usage: mdadm --incremental --rebuild-map
2115 Usage: mdadm --incremental --run --scan
2117 This mode is designed to be used in conjunction with a device discovery
2120 system. As devices are found in a system, they can be passed to mdadm
2121 --incremental to be conditionally added to an appropriate array.
2122 Conversely, it can also be used with the --fail flag to do just the
2124 opposite and find whatever array a particular device is part of and
2125 remove the device from that array.
2126 If the device passed is a CONTAINER device created by a previous call
2128 to mdadm, then rather than trying to add that device to an array, all
2129 the arrays described by the metadata of the container will be started.
2130 mdadm performs a number of tests to determine if the device is part of
2132 an array, and which array it should be part of. If an appropriate
2133 array is found, or can be created, mdadm adds the device to the array
2134 and conditionally starts the array.
2135 Note that mdadm will normally only add devices to an array which were
2137 previously working (active or spare) parts of that array. The support
2138 for automatic inclusion of a new drive as a spare in some array
2139 requires a configuration through POLICY in config file.
2140 The tests that mdadm makes are as follow:
2142 + Is the device permitted by mdadm.conf? That is, is it listed in
2144 a DEVICES line in that file. If DEVICES is absent then the
2145 default it to allow any device. Similarly if DEVICES contains
2146 the special word partitions then any device is allowed. Other‐
2147 wise the device name given to mdadm, or one of the aliases
2148 given, or an alias found in the filesystem, must match one of
2149 the names or patterns in a DEVICES line.
2150 This is the only context where the aliases are used. They are
2152 usually provided by a udev rules mentioning $env{DEVLINKS}.
2153 + Does the device have a valid md superblock? If a specific meta‐
2156 data version is requested with --metadata or -e then only that
2157 style of metadata is accepted, otherwise mdadm finds any known
2158 version of metadata. If no md metadata is found, the device may
2159 be still added to an array as a spare if POLICY allows.
2160 mdadm keeps a list of arrays that it has partially assembled in
2164 /run/mdadm/map. If no array exists which matches the metadata on the
2165 new device, mdadm must choose a device name and unit number. It does
2166 this based on any name given in mdadm.conf or any name information
2167 stored in the metadata. If this name suggests a unit number, that num‐
2168 ber will be used, otherwise a free unit number will be chosen. Nor‐
2169 mally mdadm will prefer to create a partitionable array, however if the
2170 CREATE line in mdadm.conf suggests that a non-partitionable array is
2171 preferred, that will be honoured.
2172 If the array is not found in the config file and its metadata does not
2174 identify it as belonging to the "homehost", then mdadm will choose a
2175 name for the array which is certain not to conflict with any array
2176 which does belong to this host. It does this be adding an underscore
2177 and a small number to the name preferred by the metadata.
2178 Once an appropriate array is found or created and the device is added,
2180 mdadm must decide if the array is ready to be started. It will nor‐
2181 mally compare the number of available (non-spare) devices to the number
2182 of devices that the metadata suggests need to be active. If there are
2183 at least that many, the array will be started. This means that if any
2184 devices are missing the array will not be restarted.
2185 As an alternative, --run may be passed to mdadm in which case the array
2187 will be run as soon as there are enough devices present for the data to
2188 be accessible. For a RAID1, that means one device will start the
2189 array. For a clean RAID5, the array will be started as soon as all but
2190 one drive is present.
2191 Note that neither of these approaches is really ideal. If it can be
2193 known that all device discovery has completed, then
2194 mdadm -IRs
2195 can be run which will try to start all arrays that are being incremen‐
2196 tally assembled. They are started in "read-auto" mode in which they
2197 are read-only until the first write request. This means that no meta‐
2198 data updates are made and no attempt at resync or recovery happens.
2199 Further devices that are found before the first write can still be
2200 added safely.
2201
2204 This section describes environment variables that affect how mdadm
2205 operates.
2206 MDADM_NO_MDMON
2209 Setting this value to 1 will prevent mdadm from automatically
2210 launching mdmon. This variable is intended primarily for debug‐
2211 ging mdadm/mdmon.
2212 MDADM_NO_UDEV
2215 Normally, mdadm does not create any device nodes in /dev, but
2216 leaves that task to udev. If udev appears not to be configured,
2217 or if this environment variable is set to '1', the mdadm will
2218 create and devices that are needed.
2219 MDADM_NO_SYSTEMCTL
2222 If mdadm detects that systemd is in use it will normally request
2223 systemd to start various background tasks (particularly mdmon)
2224 rather than forking and running them in the background. This
2225 can be suppressed by setting MDADM_NO_SYSTEMCTL=1.
2226 IMSM_NO_PLATFORM
2229 A key value of IMSM metadata is that it allows interoperability
2230 with boot ROMs on Intel platforms, and with other major operat‐
2231 ing systems. Consequently, mdadm will only allow an IMSM array
2232 to be created or modified if detects that it is running on an
2233 Intel platform which supports IMSM, and supports the particular
2234 configuration of IMSM that is being requested (some functional‐
2235 ity requires newer OROM support).
2236 These checks can be suppressed by setting IMSM_NO_PLATFORM=1 in
2238 the environment. This can be useful for testing or for disaster
2239 recovery. You should be aware that interoperability may be com‐
2240 promised by setting this value.
2241 MDADM_GROW_ALLOW_OLD
2244 If an array is stopped while it is performing a reshape and that
2245 reshape was making use of a backup file, then when the array is
2246 re-assembled mdadm will sometimes complain that the backup file
2247 is too old. If this happens and you are certain it is the right
2248 backup file, you can over-ride this check by setting
2249 MDADM_GROW_ALLOW_OLD=1 in the environment.
2250 MDADM_CONF_AUTO
2253 Any string given in this variable is added to the start of the
2254 AUTO line in the config file, or treated as the whole AUTO line
2255 if none is given. It can be used to disable certain metadata
2256 types when mdadm is called from a boot script. For example
2257 export MDADM_CONF_AUTO='-ddf -imsm'
2258 will make sure that mdadm does not automatically assemble any
2259 DDF or IMSM arrays that are found. This can be useful on sys‐
2260 tems configured to manage such arrays with dmraid.
2261
2265 mdadm --query /dev/name-of-device
2266 This will find out if a given device is a RAID array, or is part of
2267 one, and will provide brief information about the device.
2268 mdadm --assemble --scan
2270 This will assemble and start all arrays listed in the standard config
2271 file. This command will typically go in a system startup file.
2272 mdadm --stop --scan
2274 This will shut down all arrays that can be shut down (i.e. are not cur‐
2275 rently in use). This will typically go in a system shutdown script.
2276 mdadm --follow --scan --delay=120
2278 If (and only if) there is an Email address or program given in the
2279 standard config file, then monitor the status of all arrays listed in
2280 that file by polling them ever 2 minutes.
2281 mdadm --create /dev/md0 --level=1 --raid-devices=2 /dev/hd[ac]1
2283 Create /dev/md0 as a RAID1 array consisting of /dev/hda1 and /dev/hdc1.
2284 echo 'DEVICE /dev/hd*[0-9] /dev/sd*[0-9]' > mdadm.conf
2286 mdadm --detail --scan >> mdadm.conf
2287 This will create a prototype config file that describes currently
2288 active arrays that are known to be made from partitions of IDE or SCSI
2289 drives. This file should be reviewed before being used as it may con‐
2290 tain unwanted detail.
2291 echo 'DEVICE /dev/hd[a-z] /dev/sd*[a-z]' > mdadm.conf
2293 mdadm --examine --scan --config=mdadm.conf >> mdadm.conf
2294 This will find arrays which could be assembled from existing IDE and
2295 SCSI whole drives (not partitions), and store the information in the
2296 format of a config file. This file is very likely to contain unwanted
2297 detail, particularly the devices= entries. It should be reviewed and
2298 edited before being used as an actual config file.
2299 mdadm --examine --brief --scan --config=partitions
2301 mdadm -Ebsc partitions
2302 Create a list of devices by reading /proc/partitions, scan these for
2303 RAID superblocks, and printout a brief listing of all that were found.
2304 mdadm -Ac partitions -m 0 /dev/md0
2306 Scan all partitions and devices listed in /proc/partitions and assemble
2307 /dev/md0 out of all such devices with a RAID superblock with a minor
2308 number of 0.
2309 mdadm --monitor --scan --daemonise > /run/mdadm/mon.pid
2311 If config file contains a mail address or alert program, run mdadm in
2312 the background in monitor mode monitoring all md devices. Also write
2313 pid of mdadm daemon to /run/mdadm/mon.pid.
2314 mdadm -Iq /dev/somedevice
2316 Try to incorporate newly discovered device into some array as appropri‐
2317 ate.
2318 mdadm --incremental --rebuild-map --run --scan
2320 Rebuild the array map from any current arrays, and then start any that
2321 can be started.
2322 mdadm /dev/md4 --fail detached --remove detached
2324 Any devices which are components of /dev/md4 will be marked as faulty
2325 and then remove from the array.
2326 mdadm --grow /dev/md4 --level=6 --backup-file=/root/backup-md4
2328 The array /dev/md4 which is currently a RAID5 array will be converted
2329 to RAID6. There should normally already be a spare drive attached to
2330 the array as a RAID6 needs one more drive than a matching RAID5.
2331 mdadm --create /dev/md/ddf --metadata=ddf --raid-disks 6 /dev/sd[a-f]
2333 Create a DDF array over 6 devices.
2334 mdadm --create /dev/md/home -n3 -l5 -z 30000000 /dev/md/ddf
2336 Create a RAID5 array over any 3 devices in the given DDF set. Use only
2337 30 gigabytes of each device.
2338 mdadm -A /dev/md/ddf1 /dev/sd[a-f]
2340 Assemble a pre-exist ddf array.
2341 mdadm -I /dev/md/ddf1
2343 Assemble all arrays contained in the ddf array, assigning names as
2344 appropriate.
2345 mdadm --create --help
2347 Provide help about the Create mode.
2348 mdadm --config --help
2350 Provide help about the format of the config file.
2351 mdadm --help
2353 Provide general help.
2354
2357 /proc/mdstat
2358 If you're using the /proc filesystem, /proc/mdstat lists all active md
2359 devices with information about them. mdadm uses this to find arrays
2360 when --scan is given in Misc mode, and to monitor array reconstruction
2361 on Monitor mode.
2362 /etc/mdadm.conf
2365 The config file lists which devices may be scanned to see if they con‐
2366 tain MD super block, and gives identifying information (e.g. UUID)
2367 about known MD arrays. See mdadm.conf(5) for more details.
2368 /etc/mdadm.conf.d
2371 A directory containing configuration files which are read in lexical
2372 order.
2373 /run/mdadm/map
2376 When --incremental mode is used, this file gets a list of arrays cur‐
2377 rently being created.
2378
2381 mdadm understand two sorts of names for array devices.
2382 The first is the so-called 'standard' format name, which matches the
2384 names used by the kernel and which appear in /proc/mdstat.
2385 The second sort can be freely chosen, but must reside in /dev/md/.
2387 When giving a device name to mdadm to create or assemble an array,
2388 either full path name such as /dev/md0 or /dev/md/home can be given, or
2389 just the suffix of the second sort of name, such as home can be given.
2390 When mdadm chooses device names during auto-assembly or incremental
2392 assembly, it will sometimes add a small sequence number to the end of
2393 the name to avoid conflicted between multiple arrays that have the same
2394 name. If mdadm can reasonably determine that the array really is meant
2395 for this host, either by a hostname in the metadata, or by the presence
2396 of the array in mdadm.conf, then it will leave off the suffix if possi‐
2397 ble. Also if the homehost is specified as <ignore> mdadm will only use
2398 a suffix if a different array of the same name already exists or is
2399 listed in the config file.
2400 The standard names for non-partitioned arrays (the only sort of md
2402 array available in 2.4 and earlier) are of the form
2403 /dev/mdNN
2405 where NN is a number. The standard names for partitionable arrays (as
2407 available from 2.6 onwards) are of the form:
2408 /dev/md_dNN
2410 Partition numbers should be indicated by adding "pMM" to these, thus
2412 "/dev/md/d1p2".
2413 From kernel version 2.6.28 the "non-partitioned array" can actually be
2415 partitioned. So the "md_dNN" names are no longer needed, and parti‐
2416 tions such as "/dev/mdNNpXX" are possible.
2417 From kernel version 2.6.29 standard names can be non-numeric following
2419 the form:
2420 /dev/md_XXX
2422 where XXX is any string. These names are supported by mdadm since ver‐
2424 sion 3.3 provided they are enabled in mdadm.conf.
2425
2428 mdadm was previously known as mdctl.
2429
2432 For further information on mdadm usage, MD and the various levels of
2433 RAID, see:
2434 http://raid.wiki.kernel.org/
2436 (based upon Jakob Østergaard's Software-RAID.HOWTO)
2438 The latest version of mdadm should always be available from
2440 http://www.kernel.org/pub/linux/utils/raid/mdadm/
2442 Related man pages:
2444 mdmon(8), mdadm.conf(5), md(4).
2446v4.1-rc2 MDADM(8)