[thirdparty/mdadm.git] / mdadm.man

mdadm(8)                                                 mdadm(8)



N\bNA\bAM\bME\bE
       mdadm - manage MD devices _\ba_\bk_\ba Linux Software Raid.


S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
       m\bmd\bda\bad\bdm\bm _\b[_\bm_\bo_\bd_\be_\b] _\b<_\br_\ba_\bi_\bd_\bd_\be_\bv_\bi_\bc_\be_\b> _\b[_\bo_\bp_\bt_\bi_\bo_\bn_\bs_\b] _\b<_\bs_\bu_\bb_\bd_\be_\bv_\bi_\bc_\be_\bs_\b>


D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
       RAID  devices are virtual devices created from two or more
       real block devices. This allows  multiple  devices  (typi-
       cally  disk  drives or partitions there-of) to be combined
       into a single  device  to  hold  (for  example)  a  single
       filesystem.   Some  RAID levels included 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 L\bLI\bIN\bNE\bEA\bAR\bR md devices, R\bRA\bAI\bID\bD0\b0 (strip-
       ing), R\bRA\bAI\bID\bD1\b1 (mirroring), R\bRA\bAI\bID\bD4\b4 and R\bRA\bAI\bID\bD5\b5.\b.

       Recent kernels (2002) also support a mode known as  M\bMU\bUL\bLT\bTI\bI-\b-
       P\bPA\bAT\bTH\bH.  m\bmd\bda\bad\bdm\bm does not support MULTIPATH as yet.

       m\bmd\bda\bad\bdm\bm  is  a program that can be used to create and manage
       MD devices.  As such it provides a similar  set  of  func-
       tionality  to the r\bra\bai\bid\bdt\bto\boo\bol\bls\bs packages.  The key differences
       between m\bmd\bda\bad\bdm\bm and r\bra\bai\bid\bdt\bto\boo\bol\bls\bs are:

       +\bo   m\bmd\bda\bad\bdm\bm is a single program and not a collection of pro-
           grams.

       +\bo   m\bmd\bda\bad\bdm\bm  can perform (almost) all of its functions with-
           out having a configuration  file.   Also  mdadm  helps
           with management of the configuration file.

       +\bo   m\bmd\bda\bad\bdm\bm   can  provide  information  about  your  arrays
           (through Detail and Examine) that r\bra\bai\bid\bdt\bto\boo\bol\bls\bs cannot.

       +\bo   r\bra\bai\bid\bdt\bto\boo\bol\bls\bs can manage  MULTIPATH  devices  which  m\bmd\bda\bad\bdm\bm
           cannot yet manage.


M\bMO\bOD\bDE\bES\bS
       mdadm has 7 major modes of operation:

       A\bAs\bss\bse\bem\bmb\bbl\ble\be
              Assemble  the  parts  of a previously created array
              into an active array. Components can be  explicitly
              given  or  can  be searched for.  m\bmd\bda\bad\bdm\bm checks that
              the components do form a bona fide array, and  can,
              on  request, fiddle superblock information so as to
              assemble a faulty array.


       B\bBu\bui\bil\bld\bd  Build   a   legacy   array    without    per-device
              superblocks.


       C\bCr\bre\bea\bat\bte\be Create a new array with per-device superblocks.


       D\bDe\bet\bta\bai\bil\bl Display  the details of a given md device.  Details
              include the RAID  level,  the  number  of  devices,
              which ones are faulty (if any), and the array UUID.


       E\bEx\bxa\bam\bmi\bin\bne\be
              Examine a device to see if it  is  part  of  an  md
              array,  and  print  out  the details of that array.
              This mode can also be used to examine a large  num-
              ber  of  devices  and to print out a summary of the
              arrays  found  in  a  format   suitable   for   the
              m\bmd\bda\bad\bdm\bm.\b.c\bco\bon\bnf\bf configuration file.


       F\bFo\bol\bll\blo\bow\bw o\bor\br M\bMo\bon\bni\bit\bto\bor\br
              Monitor one or more md devices and act on any state
              changes.


       M\bMa\ban\bna\bag\bge\be This  is  for  odd  bits  an  pieces  like  hotadd,
              hotremove, setfaulty, stop, readonly, readwrite.


O\bOP\bPT\bTI\bIO\bON\bNS\bS
       Available options are:


       -\b-A\bA, -\b--\b-a\bas\bss\bse\bem\bmb\bbl\ble\be
              Assemble an existing array.


       -\b-B\bB, -\b--\b-b\bbu\bui\bil\bld\bd
              Build a legacy array without superblocks.


       -\b-C\bC, -\b--\b-c\bcr\bre\bea\bat\bte\be
              Create a new array.


       -\b-D\bD, -\b--\b-d\bde\bet\bta\bai\bil\bl
              Print detail of one or more md devices.


       -\b-E\bE, -\b--\b-e\bex\bxa\bam\bmi\bin\bne\be
              Print content of md superblock on device(s).


       -\b-F\bF, -\b--\b-f\bfo\bol\bll\blo\bow\bw, -\b--\b-m\bmo\bon\bni\bit\bto\bor\br
              Select M\bMo\bon\bni\bit\bto\bor\br mode.


       -\b-h\bh, -\b--\b-h\bhe\bel\blp\bp
              Display  help  message or, after above option, mode
              specific help message.


       -\b-V\bV, -\b--\b-v\bve\ber\brs\bsi\bio\bon\bn
              Print version information for mdadm.


       -\b-v\bv, -\b--\b-v\bve\ber\brb\bbo\bos\bse\be
              Be more verbose about what is happening.


       -\b-b\bb, -\b--\b-b\bbr\bri\bie\bef\bf
              Be less verbose.  This is used  with  -\b--\b-d\bde\bet\bta\bai\bil\bl  and
              -\b--\b-e\bex\bxa\bam\bmi\bin\bne\be.


F\bFo\bor\br c\bcr\bre\bea\bat\bte\be o\bor\br b\bbu\bui\bil\bld\bd:\b:
       -\b-c\bc, -\b--\b-c\bch\bhu\bun\bnk\bk=\b=
              Specify  chunk  size  of kibibytes.  The default is
              64.


       -\b--\b-r\bro\bou\bun\bnd\bdi\bin\bng\bg=\b=
              Specify rounding factor for linear  array  (==chunk
              size)


       -\b-l\bl, -\b--\b-l\ble\bev\bve\bel\bl=\b=
              Set  raid  level.   Options  are: linear, raid0, 0,
              stripe, raid1,  1,  mirror,  raid5,  4,  raid5,  5.
              Obviously  some  of these are synonymous.  Only the
              first 4 are valid when Building.


       -\b-p\bp, -\b--\b-p\bpa\bar\bri\bit\bty\by=\b=
              Set   raid5   parity   algorithm.   Options    are:
              {left,right}-{,a}symmetric,  la,  ra,  ls, rs.  The
              default is left-symmetric.


       -\b--\b-l\bla\bay\byo\bou\but\bt=\b=
              same as --parity


       -\b-n\bn, -\b--\b-r\bra\bai\bid\bd-\b-d\bdi\bis\bsk\bks\bs=\b=
              number of active devices in array.


       -\b-x\bx, -\b--\b-s\bsp\bpa\bar\bre\be-\b-d\bdi\bis\bsk\bks\bs=\b=
              number of spare (eXtra)  disks  in  initial  array.
              Spares can be added and removed later.


       -\b-z\bz, -\b--\b-s\bsi\biz\bze\be=\b=
              Amount  (in  Kibibytes)  of  space to use from each
              drive in RAID1/4/5.  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 warning is issued.


F\bFo\bor\br a\bas\bss\bse\bem\bmb\bbl\ble\be:\b:
       -\b-u\bu, -\b--\b-u\buu\bui\bid\bd=\b=
              uuid of array to assemble. Devices which don't have
              this uuid are excluded


       -\b-m\bm, -\b--\b-s\bsu\bup\bpe\ber\br-\b-m\bmi\bin\bno\bor\br=\b=
              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 superblock will contain  the  minor  number  1,
              even if the array is later assembled as /dev/md2.


       -\b-c\bc, -\b--\b-c\bco\bon\bnf\bfi\big\bg=\b=
              config file.  Default is /\b/e\bet\btc\bc/\b/m\bmd\bda\bad\bdm\bm.\b.c\bco\bon\bnf\bf.


       -\b-s\bs, -\b--\b-s\bsc\bca\ban\bn
              scan config file for missing information


       -\b-f\bf, -\b--\b-f\bfo\bor\brc\bce\be
              Assemble  the array even if some superblocks appear
              out-of-date


       -\b-R\bR, -\b--\b-r\bru\bun\bn
              Attempt to start the array  even  if  fewer  drives
              were  given  than are needed for a full array. Nor-
              mally if not all drives are found and -\b--\b-s\bsc\bca\ban\bn is not
              used,  then  the  array  will  be assembled but not
              started.  With -\b--\b-r\bru\bun\bn an attempt  will  be  made  to
              start it anyway.


G\bGe\ben\bne\ber\bra\bal\bl m\bma\ban\bna\bag\bge\bem\bme\ben\bnt\bt
       -\b-a\ba, -\b--\b-a\bad\bdd\bd
              hotadd listed devices.


       -\b-r\br, -\b--\b-r\bre\bem\bmo\bov\bve\be
              remove  listed  devices.   The  must not be active.
              i.e. they should be failed or spare devices.


       -\b-f\bf, -\b--\b-f\bfa\bai\bil\bl
              mark listed devices as faulty.


       -\b--\b-s\bse\bet\bt-\b-f\bfa\bau\bul\blt\bty\by
              same as --fail.


       -\b-R\bR, -\b--\b-r\bru\bun\bn
              start a partially built array.


       -\b-S\bS, -\b--\b-s\bst\bto\bop\bp
              deactivate array, releasing all resources.


       -\b-o\bo, -\b--\b-r\bre\bea\bad\bdo\bon\bnl\bly\by
              mark array as readonly.


       -\b-w\bw, -\b--\b-r\bre\bea\bad\bdw\bwr\bri\bit\bte\be
              mark array as readwrite.



A\bAS\bSS\bSE\bEM\bMB\bBL\bLY\bY M\bMO\bOD\bDE\bE
       Usage: m\bmd\bda\bad\bdm\bm -\b--\b-a\bas\bss\bse\bem\bmb\bbl\ble\be _\bd_\be_\bv_\bi_\bc_\be _\bo_\bp_\bt_\bi_\bo_\bn_\bs_\b._\b._\b.

       Usage: m\bmd\bda\bad\bdm\bm -\b--\b-a\bas\bss\bse\bem\bmb\bbl\ble\be -\b--\b-s\bsc\bca\ban\bn _\bo_\bp_\bt_\bi_\bo_\bn_\bs_\b._\b._\b.


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

       The  md  device  is either given before -\b--\b-s\bsc\bca\ban\bn or is found
       from the config file. In  the  latter  case,  multiple  md
       devices can be started with a single mdadm command.

       The identity can be given with the -\b--\b-u\buu\bui\bid\bd option, with the
       -\b--\b-s\bsu\bup\bpe\ber\br-\b-m\bmi\bin\bno\bor\br option, can be found in in the config  file,
       or  will be taken from the super block on the first subde-
       vice listed on the command line.

       Devices can be given on the  -\b--\b-a\bas\bss\bse\bem\bmb\bbl\ble\be  command  line  or
       from  the  config  file.  Only  devices  which  have an md
       superblock which contains the right identity will be  con-
       sidered for any device.

       The  config  file  is  only  used if explicitly named with
       -\b--\b-c\bco\bon\bnf\bfi\big\bg or requested with -\b--\b-s\bsc\bca\ban\bn.\b.   In  the  later  case,
       /\b/e\bet\btc\bc/\b/m\bmd\bda\bad\bdm\bm.\b.c\bco\bon\bnf\bf is used.

       If  -\b--\b-s\bsc\bca\ban\bn 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  is  -\b--\b-s\bsc\bca\ban\bn  is  not given and insufficient drives
       were lists to start a complete (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 or RAID5), give the -\b--\b-r\bru\bun\bn flag.



B\bBU\bUI\bIL\bLD\bD M\bMO\bOD\bDE\bE
       Usage:  m\bmd\bda\bad\bdm\bm  -\b--\b-b\bbu\bui\bil\bld\bd  _\bd_\be_\bv_\bi_\bc_\be -\b--\b-c\bch\bhu\bun\bnk\bk=\b=_\bX -\b--\b-l\ble\bev\bve\bel\bl=\b=_\bY -\b--\b-r\bra\bai\bid\bd-\b-
                   d\bdi\bis\bsk\bks\bs=\b=_\bZ _\bd_\be_\bv_\bi_\bc_\be_\bs


       This usage is similar to -\b--\b-c\bcr\bre\bea\bat\bte\be.  The difference is that
       it creates a legacy array without a superblock. With these
       arrays there is no difference between  initially  creating
       the  array  and  subsequently assembling 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  com-
       plete.


C\bCR\bRE\bEA\bAT\bTE\bE M\bMO\bOD\bDE\bE
       Usage: m\bmd\bda\bad\bdm\bm -\b--\b-c\bcr\bre\bea\bat\bte\be _\bd_\be_\bv_\bi_\bc_\be -\b--\b-c\bch\bhu\bun\bnk\bk=\b=_\bX -\b--\b-l\ble\bev\bve\bel\bl=\b=_\bY
                   -\b--\b-r\bra\bai\bid\bd-\b-d\bdi\bis\bsk\bks\bs=\b=_\bZ _\bd_\be_\bv_\bi_\bc_\be_\bs


       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 con-
       tain  raid superblocks or filesystems. They are also check
       to see if the variance in device size exceeds 1%.

       If any discrepancy is found, the array will not  automati-
       cally  be run, though the presence of a -\b--\b-r\bru\bun\bn can override
       this caution.


       The General Management options that are valid with  --cre-
       ate are:

       -\b--\b-r\bru\bun\bn  insist  of  running  the array even if some devices
              look like they might be in use.


       -\b--\b-r\bre\bea\bad\bdo\bon\bnl\bly\by
              start the array readonly - not supported yet.


D\bDE\bET\bTA\bAI\bIL\bL M\bMO\bOD\bDE\bE
       Usage: m\bmd\bda\bad\bdm\bm -\b--\b-d\bde\bet\bta\bai\bil\bl [-\b--\b-b\bbr\bri\bie\bef\bf] _\bd_\be_\bv_\bi_\bc_\be _\b._\b._\b.


       This usage sill print out the details of the  given  array
       including a list of component devices.  To determine names
       for the devices, m\bmd\bda\bad\bdm\bm searches /\b/d\bde\bev\bv for device files with
       the right major and minor numbers.

       With  -\b--\b-b\bbr\bri\bie\bef\bf  m\bmd\bda\bad\bdm\bm  prints a single line that identifies
       the level, number of disks, and UUID of the  array.   This
       line is suitable for inclusion in /\b/e\bet\btc\bc/\b/m\bmd\bda\bad\bdm\bm.\b.c\bco\bon\bnf\bf.


E\bEX\bXA\bAM\bMI\bIN\bNE\bE M\bMO\bOD\bDE\bE
       Usage: m\bmd\bda\bad\bdm\bm -\b--\b-e\bex\bxa\bam\bmi\bin\bne\be [-\b--\b-s\bsc\bca\ban\bn] [-\b--\b-b\bbr\bri\bie\bef\bf] _\bd_\be_\bv_\bi_\bc_\be _\b._\b._\b.

       This  usage will examine some block devices to see if that
       have a valid RAID superblock on them.  The information  in
       each valid raid superblock will be printed.

       If  -\b--\b-s\bsc\bca\ban\bn  is  used, the no devices should be listed, and
       the complete set of devices identified in  the  configura-
       tion  file  are  checked.  -\b--\b-s\bsc\bca\ban\bn implies -\b--\b-b\bbr\bri\bie\bef\bf but this
       implication can be countered by specifying -\b--\b-v\bve\ber\brb\bbo\bos\bse\be.

       With -\b--\b-b\bbr\bri\bie\bef\bf m\bmd\bda\bad\bdm\bm will output an  config  file  entry  of
       each  distinct array that was found.  This entry will list
       the UUID, the raid level, and a  list  of  the  individual
       devices  on  which  a superblock for that array was found.
       This output will by syntactically suitable  for  inclusion
       in the configuration file, but should N\bNO\bOT\bT be used blindly.
       Often the array description that you want in the  configu-
       ration file is much less specific than that given by m\bmd\bda\bad\bdm\bm
       -\b-B\bBs\bs.  For example, you normally do not want  to  list  the
       devices, particularly if they are SCSI devices.



F\bFI\bIL\bLE\bES\bS
   /\b/p\bpr\bro\boc\bc/\b/m\bmd\bds\bst\bta\bat\bt
       If  you're  using the /\b/p\bpr\bro\boc\bc filesystem, /\b/p\bpr\bro\boc\bc/\b/m\bmd\bds\bst\bta\bat\bt gives
       you informations about md devices status.   This  file  is
       not currently used by m\bmd\bda\bad\bdm\bm.


   /\b/e\bet\btc\bc/\b/m\bmd\bda\bad\bdm\bm.\b.c\bco\bon\bnf\bf
       The  config  file  is  line oriented with, as usual, blank
       lines and lines beginning with a hash (or  pound  sign  or
       sharp  or  number  sign,  whichever  you  like to call it)
       ignored.  Lines that start with a  blank  are  treated  as
       continuations  of the previous line (I don't like trailing
       slashes).

       Each line contains a sequence  of  space-separated  words,
       the  first  of which identified the type of line. Keywords
       are case-insensitive, and the first work on a line can  be
       abbreviated to 3 letters.

       There are two types of lines. ARRAY and DEVICE.

       The  DEVICE  lines usually come first. All remaining words
       on the line are treated as names of devices, possibly con-
       taining  wild  cards  (see  _\bg_\bl_\bo_\bb(7)).   These list all the
       devices that m\bmd\bda\bad\bdm\bm is allowed to  scan  when  looking  for
       devices with RAID superblocks.  Each line can contain mul-
       tiple device names,  and  there  can  be  multiple  DEVICE
       lines.  For example:

              DEVICE /dev/hda* /dev/hdc*
              DEV    /dev/sd*
              DEVICE /dev/discs/disc*/disc

       The  ARRAY  lines identify actual arrays.  The second word
       on the line should be the name of  the  device  where  the
       array is normally assembled, such as /dev/md1.  Subsequent
       words identify  the  array.  If  multiple  identities  are
       given, then the array much match ALL identities to be con-
       sidered a match.  Each identity word has a tag, and equals
       sign, and some value.  The options are:


       u\buu\bui\bid\bd=\b=  The  value should be a 128 bit uuid in hexadecimal,
              with punctuation  interspersed  if  desired.   This
              must match the uuid stored in the superblock.

       s\bsu\bup\bpe\ber\br-\b-m\bmi\bin\bno\bor\br=\b=
              The  value  is an integer which indicates the minor
              number that was stored in the superblock  when  the
              array  was  created.  When  an  array is created as
              /dev/mdX, then the minor number X is stored.

       d\bde\bev\bvi\bic\bce\bes\bs=\b=
              The value is  a  comma  separated  list  of  device
              names.  Precisely  these  devices  will  be used to
              assemble the array.  Note that the  devices  listed
              there must also be listed on a DEVICE line.

       l\ble\bev\bve\bel\bl=\b= The  value  is a raid level.  This is normally used
              to identify an array, but is supported so that  the
              output   of  m\bmd\bda\bad\bdm\bm  -\b--\b-e\bex\bxa\bam\bmi\bin\bne\be  -\b--\b-s\bsc\bca\ban\bn  can  be  use
              directly in the configuration file.

       d\bdi\bis\bsk\bks\bs=\b= The value is the number  of  disks  in  a  complete
              active  array.   As  with l\ble\bev\bve\bel\bl=\b= this is mainly for
              compatibility with the output  of  m\bmd\bda\bad\bdm\bm  -\b--\b-e\bex\bxa\bam\bmi\bin\bne\be
              -\b--\b-s\bsc\bca\ban\bn.


T\bTO\bOD\bDO\bO
       Finish and document Follow mode.


S\bSE\bEE\bE A\bAL\bLS\bSO\bO
       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/peo-
              ple/mingo/raid-patches

       or

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

       _\br_\ba_\bi_\bd_\bt_\ba_\bb(5), _\br_\ba_\bi_\bd_\b0_\br_\bu_\bn(8), _\br_\ba_\bi_\bd_\bs_\bt_\bo_\bp(8), _\bm_\bk_\br_\ba_\bi_\bd(8)



                                                         mdadm(8)