SGI Techpubs Library

Linux  »  Man Pages
find in page

mdadm



SYNOPSIS

       mdadm [mode] <raiddevice> [options] <component-devices>


DESCRIPTION

       RAID  devices  are  virtual devices created from two or more real block
       devices. This allows multiple devices (typically disk drives or  parti-
       tions  there-of) to be combined into a single device to hold (for exam-
       ple) a single filesystem.  Some RAID levels include redundancy  and  so
       can survive some degree of device failure.

       Linux  Software  RAID  devices are implemented through the md (Multiple
       Devices) device driver.

       Currently, Linux supports LINEAR md devices,  RAID0  (striping),  RAID1
       (mirroring), RAID4, RAID5, RAID6, and MULTIPATH.

       MULTIPATH  is  not a Software RAID mechanism, but does involve multiple
       devices.  For MULTIPATH each device is a path to  one  common  physical
       storage device.

       mdadm  is  a program that can be used to create, manage, and monitor MD
       devices.  As such it provides a similar set  of  functionality  to  the
       raidtools  packages.   The  key differences between mdadm and raidtools
       are:

       ·   mdadm is a single program and not a collection of programs.

       ·   mdadm can perform (almost) all of its functions  without  having  a
           configuration  file  and  does  not use one by default.  Also mdadm
           helps with management of the configuration file.

       ·   mdadm can provide information about  your  arrays  (through  Query,
           Detail, and Examine) that raidtools cannot.

       mdadm  does  not use /etc/raidtab, the raidtools configuration file, at
       all.  It has a different configuration file with a different format and
       an different purpose.


MODES

       mdadm has 6 major modes of operation:

       Assemble
              Assemble  the parts of a previously created array into an active
              array. Components can be explicitly given  or  can  be  searched
              for.   mdadm  checks  that  the  components  do form a bona fide
              array, and can, on request, fiddle superblock information so  as
              to assemble a faulty array.

       Build  Build a legacy array without per-device superblocks.


       Follow or Monitor
              Monitor one or more md devices and act  on  any  state  changes.
              This  is  only meaningful for raid1, 4, 5, 6 or multipath arrays
              as only these have interesting state.   raid0  or  linear  never
              have  missing,  spare,  or failed drives, so there is nothing to
              monitor.


OPTIONS

       Available options are:

       -A, --assemble
              Assemble a pre-existing array.

       -B, --build
              Build a legacy array without superblocks.

       -C, --create
              Create a new array.

       -Q, --query
              Examine a device to see (1) if it is an md device and (2) if  it
              is  a  component of an md array.  Information about what is dis-
              covered is presented.

       -D, --detail
              Print detail of one or more md devices.

       -E, --examine
              Print content of md superblock on device(s).

       -F, --follow, --monitor
              Select Monitor mode.

       -h, --help
              Display help message or, after above option, mode specific  help
              message.

       --help-options
              Display  more  detailed help about command line parsing and some
              commonly used options.

       -V, --version

       -f, --force
              Be more forceful about  certain  operations.   See  the  various
              modes of the exact meaning of this option in different contexts.

       -c, --config=
              Specify the config file.  Default is  /etc/mdadm.conf.   If  the
              config  file  given is partitions then nothing will be read, but
              mdadm will act as  though  the  config  file  contained  exactly
              DEVICE  partitions and will read /proc/partitions to find a list
              of devices to scan.  If the word none is given  for  the  config
              file,  then mdadm will act as though the config file were empty.

       -s, --scan
              scan config file or /proc/mdstat for  missing  information.   In
              general,  this  option gives mdadm permission to get any missing
              information, like component devices, array devices, array  iden-
              tities,  and  alert  destination  from  the  configuration file:
              /etc/mdadm.conf.  One exception is MISC mode when using --detail
              or  --stop  in  which  case  --scan  says to get a list of array
              devices from /proc/mdstat.


For create or build:

       -c, --chunk=
              Specify chunk size of kibibytes.  The default is 64.

       --rounding=
              Specify rounding factor for linear array (==chunk size)

       -l, --level=
              Set raid level.  When used with --create, options  are:  linear,
              raid0,  0,  stripe, raid1, 1, mirror, raid4, 4, raid5, 5, raid6,
              6, multipath, mp.  Obviously some of these are synonymous.

              When used with --build, only linear, raid0, 0, stripe are valid.

       -p, --parity=
              Set  raid5 parity algorithm. Options are: left-asymmetric, left-
              symmetric, right-asymmetric, right-symmetric, la,  ra,  ls,  rs.
              The default is left-symmetric.

       --layout=
              same as --parity

       -n, --raid-devices=
              Specify  the  number of active devices in the array.  This, plus
              the number of spare devices (see below) must equal the number of
              component-devices  (including "missing" devices) that are listed
              array.   Spares can also be added and removed later.  The number
              of component devices listed on the command line must  equal  the
              number of raid devices plus the number of spare devices.

       -z, --size=
              Amount  (in  Kibibytes)  of  space  to  use  from  each drive in
              RAID1/4/5/6.  This must be a multiple of  the  chunk  size,  and
              must  leave about 128Kb of space at the end of the drive for the
              RAID superblock.  If this is not specified (as  it  normally  is
              not)  the smallest drive (or partition) sets the size, though if
              there is a variance among the drives of greater than 1%, a warn-
              ing is issued.


For assemble:

       -u, --uuid=
              uuid  of  array  to assemble. Devices which don’t have this uuid
              are excluded

       -m, --super-minor=
              Minor number of device that  array  was  created  for.   Devices
              which  don’t have this minor number are excluded.  If you create
              an array as /dev/md1, then  all  superblocks  will  contain  the
              minor  number  1,  even  if  the  array  is  later  assembled as
              /dev/md2.

              Giving the literal word "dev" for --super-minor will cause mdadm
              to  use  the  minor number of the md device that is being assem-
              bled.  e.g. when assembling /dev/md0, will look for super blocks
              with a minor number of 0.

       -f, --force
              Assemble the array even if some superblocks appear out-of-date

       -R, --run
              Attempt  to start the array even if fewer drives were given than
              are needed for a full array. Normally  if  not  all  drives  are
              found  and  --scan is not used, then the array will be assembled
              but not started.  With --run an attempt will be made to start it
              anyway.

       -U, --update=
              Update the superblock on each device while assembling the array.
              The argument given to this flag can be  one  of  sparc2.2,  sum-
              maries, or super-minor.

              The sparc2.2 option will  adjust the superblock of an array what
              was created on a Sparc machine running a patched 2.2 Linux  ker-
              nel.   This  kernel  got the alignment of part of the superblock
              wrong.  You can use the --examine --sparc2.2 option to mdadm  to


For Manage mode:

       -a, --add
              hotadd listed devices.

       -r, --remove
              remove listed devices.  They must  not  be  active.   i.e.  they
              should be failed or spare devices.

       -f, --fail
              mark listed devices as faulty.

       --set-faulty
              same as --fail.


For Examine mode:

       --sparc2.2
              In  an array was created on a 2.2 Linux kernel patched with RAID
              support, the superblock will have been created  incorrectly,  or
              at  least  incompatibly  with  2.4 and later kernels.  Using the
              --sparc2.2 flag with --examine will fix  the  superblock  before
              displaying  it.  If this appears to do the right thing, then the
              array   can   be   successfully   assembled   using   --assemble
              --update=sparc2.2.


For Misc mode:

       -R, --run
              start a partially built array.

       -S, --stop
              deactivate array, releasing all resources.

       -o, --readonly
              mark array as readonly.

       -w, --readwrite
              mark array as readwrite.

       --zero-superblock
              If the device contains a valid md superblock, the block is over-
              written with zeros.  With --force the block where the superblock
              would  be is over-written even if it doesn’t appear to be valid.

       -t, --test
              When used with --detail, the exit status  of  mdadm  is  set  to

       -d, --delay
              Give  a  delay  in  seconds.  mdadm polls the md arrays and then
              waits this many seconds before polling again.  The default is 60
              seconds.

       -f, --daemonise
              Tell  mdadm to run as a background daemon if it decides to moni-
              tor anything.  This causes it to fork and run in the child,  and
              to disconnect form the terminal.  The process id of the child is
              written to stdout.  This is useful with --scan which  will  only
              continue  monitoring if a mail address or alert program is found
              in the config file.

       -1, --oneshot
              Check arrays only once.  This will generate NewArray events  and
              more significantly DegradedArray events.  Running
                      mdadm --monitor --scan -1
              from  a  cron  script  will  ensure  regular notification of any
              degraded arrays.

       -t, --test
              Generate a TestMessage alert for every array found  at  startup.
              This  alert  gets  mailed and passed to the alert program.  This
              can be used for testing that alert message to get  through  suc-
              cessfully.


ASSEMBLE MODE

       Usage: mdadm --assemble md-device options-and-component-devices...

       Usage: mdadm --assemble --scan md-devices-and-options...

       Usage: mdadm --assemble --scan options...

       This  usage  assembles one or more raid arrays from pre-existing compo-
       nents.  For each array, mdadm needs to know the md device, the identity
       of  the array, and a number of component-devices. These can be found in
       a number of ways.

       In the first usage example (without the --scan) the first device  given
       is  the md device.  In the second usage example, all devices listed are
       treated as md devices and assembly is attempted.  In the  third  (where
       no devices are listed) all md devices that are listed in the configura-
       tion file are assembled.

       If precisely one device is listed, but --scan is not given, that  mdadm
       acts  as  though --scan was given and identify information is extracted
       from the configuration file.

       The identity can be given with the --uuid  option,  with  the  --super-
       /etc/mdadm.conf is used.

       If  --scan is not given, then the config file will only be used to find
       the identity of md arrays.

       Normally the array will be started after it is assembled.   However  if
       --scan is not given and insufficient drives were listed to start a com-
       plete (non-degraded) array, then the array is  not  started  (to  guard
       against  usage  errors).   To  insist that the array be started in this
       case (as may work for RAID1, 4, 5 or 6), give the --run flag.


BUILD MODE

       Usage:  mdadm  --build  device  --chunk=X  --level=Y   --raid-devices=Z
                   devices

       This usage is similar to --create.  The difference is that it creates a
       legacy array without a superblock. With these arrays there is  no  dif-
       ference  between  initially  creating the array and subsequently assem-
       bling the array, except that hopefully there is useful  data  there  in
       the second case.

       The  level  may only be 0, raid0, or linear. All devices must be listed
       and the array will be started once complete.


CREATE MODE

       Usage: mdadm --create device --chunk=X --level=Y
                   --raid-devices=Z devices

       This usage will initialise a new md array, associate some devices  with
       it, and activate the array.

       As  devices  are  added,  they  are checked to see if they contain raid
       superblocks or filesystems. They are also checked to see if  the  vari-
       ance in device size exceeds 1%.

       If  any  discrepancy is found, the array will not automatically be run,
       though the presence of a --run can override this caution.

       To create a "degraded" array in which some devices are missing,  simply
       give  the  word  "missing"  in place of a device name.  This will cause
       mdadm to leave the corresponding slot in the array empty.  For a  RAID4
       or  RAID5 array at most one slot can be "missing"; for a RAID6 array at
       most two slots.  For a RAID1 array, only one real device  needs  to  be
       given.  All of the others can be "missing".

       When creating a RAID5 array, mdadm will automatically create a degraded
       array with an extra spare drive.  This is because  building  the  spare
       into a degraded array is in general faster than resyncing the parity on
       a non-degraded, but not clean, array.  This feature can be  over-ridden
       with the -I --force option.



MANAGE MODE

       Usage: mdadm device options... devices...

       This usage will allow individual devices in  an  array  to  be  failed,
       removed  or  added.  It is possible to perform multiple operations with
       on command. For example:
         mdadm /dev/md0 -f /dev/hda1 -r /dev/hda1 -a /dev/hda1
       will firstly mark /dev/hda1 as faulty in /dev/md0 and will then  remove
       it  from the array and finally add it back in as a spare.  However only
       one md array can be affected by a single command.


MISC MODE

       Usage: mdadm options ...  devices ...

       MISC mode includes a number if distinct operations that operate on dis-
       tinct devices.  The operations are:

       --query
              The  device  is examined to see if it is (1) an active md array,
              or (2) a component of an md array.  The  information  discovered
              is reported.

       --detail
              The  device should be an active md device.  mdadm will display a
              detailed description of the array.  --brief or --scan will cause
              the output to be less detailed and the format to be suitable for
              inclusion in /etc/mdadm.conf.  The exit  status  of  mdadm  will
              normally  be  0  unless  mdadm  failed to get useful information
              about the device(s).  However if the  --test  option  is  given,
              then the exit status will be:

              0      The array is functioning normally.

              1      The array has at least one failed device.

              2      The  array has multiple failed devices and hence is unus-
                     able (raid4 or raid5).

              4      There was an error while trying to get information  about
                     the device.

       --examine
              The  device  should  be  a component of an md array.  mdadm will
              read the md superblock of the device and display  the  contents.
              If  --brief  is  given, or --scan then multiple devices that are
              components of the one array are grouped together and reported in
              a single entry suitable for inclusion in /etc/mdadm.conf.

              Having --scan without listing any devices will cause all devices
              listed in the config file to be examined.
              This  will  mark an active array as read-only, providing that it
              is not currently being used.

       --readwrite
              This will change a readonly array back to being read/write.

       --scan For all operations except --examine, --scan will cause the oper-
              ation  to  be applied to all arrays listed in /proc/mdstat.  For
              --examine, --scan causes all devices listed in the  config  file
              to be examined.


MONITOR MODE

       Usage: mdadm --monitor options... devices...

       This  usage causes mdadm to periodically poll a number of md arrays and
       to report on any events noticed.  mdadm will never exit once it decides
       that  there  are  arrays to be checked, so it should normally be run in
       the background.

       As well as reporting events, mdadm may move  a  spare  drive  from  one
       array  to another if they are in the same spare-group and if the desti-
       nation array has a failed drive but not spares.

       If any devices are listed on the command line, mdadm will only  monitor
       those  devices.  Otherwise  all arrays listed in the configuration file
       will be monitored.  Further, if --scan is  given,  then  any  other  md
       devices that appear in /proc/mdstat will also be monitored.

       The result of monitoring the arrays is the generation of events.  These
       events are passed to a separate  program  (if  specified)  and  may  be
       mailed to a given E-mail address.

       When  passing  event to program, the program is run once for each event
       and is given 2 or 3 command-line arguements.  The first is the name  of
       the  event  (see below).  The second is the name of the md device which
       is affected, and the third is the name of a related device if relevant,
       such as a component device that has failed.

       If  --scan is given, then a program or an E-mail address must be speci-
       fied on the command line or in the config file.  If neither are  avail-
       able,  then mdadm will not monitor anything.  Without --scan mdadm will
       continue monitoring as long as something was found to monitor.   If  no
       program or email is given, then each event is reported to stdout.

       The different events are:

           DeviceDisappeared
                  An  md  array  which previously was configured appears to no
                  longer be configured.

           RebuildFinished
                  An  md  array  that  was  rebuilding, isn’t any more, either
                  because it finished normally or was aborted.

           Fail   An active component device of an array has  been  marked  as
                  faulty.

           FailSpare
                  A  spare component device which was being rebuilt to replace
                  a faulty device has failed.

           SpareActive
                  A spare component device which was being rebuilt to  replace
                  a  faulty  device  as been successfully rebuild and has been
                  made active.

           NewArray
                  A new md array has been detected in the /proc/mdstat file.

           DegradedArray
                  A newly noticed array appears to be degraded.  This  message
                  is  not  generated  when mdadm notices a drive failure which
                  causes degradation, but only  when  mdadm  notices  that  an
                  array is degraded when it first sees the array.

           MoveSpare
                  A spare drive has been moved from one array in a spare-group
                  to another to allow a failed drive to be replaced.

           TestMessage
                  An array was found at  startup,  and  the  --test  flag  was
                  given.

       Only  Fail , FailSpare , DegradedArray , and TestMessage cause Email to
       be sent.  All events cause the program to be run.  The program  is  run
       with  two  or  three  arguments,  they  being the event name, the array
       device and possibly a second device.

       Each event has an associated array device (e.g.  /dev/md1) and possibly
       a  second  device.   For  Fail,  FailSpare,  and SpareActive the second
       device is the relevant component  device.   For  MoveSpare  the  second
       device is the array that the spare was moved from.

       For  mdadm  to  move  spares  from  one array to another, the different
       arrays need to be labelled with the same spare-group in the  configura-
       tion  file.   The spare-group name can be any string. It is only neces-
       sary that different spare groups use different names.

       When mdadm detects that an array which is in a spare  group  has  fewer
       This will find out if a given device is a raid array,  or  is  part  of
       one, and will provide brief information about the device.

         mdadm --assemble --scan
       This  will assemble and start all arrays listed in the standard confile
       file.  This command will typically go in a system startup file.

         mdadm --stop --scan
       This will shut down all array that can be shut down (i.e. are not  cur-
       rently  in  used).   This  will  typically  going  in a system shutdown
       script.

         mdadm --follow --scan --delay=120
       If (and only if) there is an Email address  or  program  given  in  the
       standard  config  file, then monitor the status of all arrays listed in
       that file by polling them ever 2 minutes.

         mdadm --create /dev/md0 --level=1 --raid-devices=2 /dev/hd[ac]1
       Create /dev/md0 as a RAID1 array consisting of /dev/hda1 and /dev/hdc1.

         echo ’DEVICE /dev/hd*[0-9] /dev/sd*[0-9]’ > mdadm.conf
         mdadm --detail --scan >> mdadm.conf
       This  will  create  a  prototype  config  file that describes currently
       active arrays that are known to be made from partitions of IDE or  SCSI
       drives.   This file should be reviewed before being used as it may con-
       tain unwanted detail.

         echo ’DEVICE /dev/hd[a-z] /dev/sd*[a-z]’ > mdadm.conf
         mdadm --examine --scan --config=mdadm.conf >>  mdadm.conf  This  will
       find  what  arrays  could be assembled from existign IDE and SCSI whole
       drives (not partitions) and store the information is the  format  of  a
       config file.  This file is very likely to contain unwanted detail, par-
       ticularly the devices= entries.   It  should  be  reviewed  and  edited
       before being used as an actual config file.

         mdadm --examine --brief --scan --config=partitions
         mdadm -Ebsc partitions
       Create  a  list  of devices by reading /proc/partitions, scan these for
       RAID superblocks, and printout a brief listing of all that was found.

         mdadm -Ac partitions -m 0 /dev/md0
       Scan all partitions and devices listed in /proc/partitions and assemble
       /dev/md0  out  of  all such devices with a RAID superblock with a minor
       number of 0.

         mdadm --monitor --scan --daemonise > /var/run/mdadm
       If config file contains a mail address or alert program, run  mdadm  in
       the  background  in monitor mode monitoring all md devices.  Also write
       pid of mdadm daemon to /var/run/mdadm.

         mdadm --create --help
       Providew help about the Create mode.

         mdadm --config --help
       Provide help about the format of the config file.

       on Monitor mode.

   /etc/mdadm.conf
       The  config file lists which devices may be scanned to see if they con-
       tain MD super block, and  gives  identifying  information  (e.g.  UUID)
       about known MD arrays.  See mdadm.conf(5) for more details.


NOTE

       mdadm was previously known as mdctl.


SEE ALSO

       For information on the various levels of RAID, check out:

              http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/

       for new releases of the RAID driver check out:

              ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches

       or

              http://www.cse.unsw.edu.au/~neilb/patches/linux-stable/

       mdadm.conf(5), md(4).

       raidtab(5), raid0run(8), raidstop(8), mkraid(8)

v1.5.0                                                                MDADM(8)

Output converted with man2html


home/search | what's new | help