mdadm.conf man page on Archlinux

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Archlinux logo
[printable version]


       mdadm.conf - configuration for management of Software RAID with mdadm


       mdadm  is  a  tool  for creating, managing, and monitoring RAID devices
       using the md driver in Linux.

       Some common tasks, such as assembling all arrays, can be simplified  by
       describing the devices and arrays in this configuration file.

       The  file  should  be  seen as a collection of words separated by white
       space (space, tab, or newline).	Any word that beings with a hash  sign
       (#)  starts  a comment and that word together with the remainder of the
       line is ignored.

       Spaces can be included in a word using  quotation  characters.	Either
       single quotes (') or double quotes (") may be used.  All the characters
       from one quotation character to next identical character are  protected
       and will not be used to separate words to start new quoted strings.  To
       include a single quote it must be between double quotes.	 To include  a
       double quote it must be between single quotes.

       Any  line  that	starts	with  white space (space or tab) is treated as
       though it were a continuation of the previous line.

       Empty lines are ignored, but otherwise  each  (non  continuation)  line
       must  start  with  a  keyword  as  listed below.	 The keywords are case
       insensitive and can be abbreviated to 3 characters.

       The keywords are:

       DEVICE A device line lists the devices (whole  devices  or  partitions)
	      that might contain a component of an MD array.  When looking for
	      the components of an array, mdadm will scan  these  devices  (or
	      any devices listed on the command line).

	      The device line may contain a number of different devices (sepa‐
	      rated by spaces) and each device name can contain wild cards  as
	      defined by glob(7).

	      Also, there may be several device lines present in the file.

	      Alternatively,  a	 device line can contain either or both of the
	      words containers and partitions.	The word containers will cause
	      mdadm  to	 look for assembled CONTAINER arrays and included them
	      as a source for assembling further arrays.

	      The word partitions will cause mdadm  to	read  /proc/partitions
	      and  include  all	 devices  and partitions found therein.	 mdadm
	      does not use the names from /proc/partitions but only the	 major
	      and  minor  device numbers.  It scans /dev to find the name that
	      matches the numbers.

	      If no DEVICE line is present, then "DEVICE  partitions  contain‐
	      ers" is assumed.

	      For example:

	      DEVICE /dev/hda* /dev/hdc*
	      DEV    /dev/sd*
	      DEVICE /dev/disk/by-path/pci*
	      DEVICE partitions

       ARRAY  The  ARRAY lines identify actual arrays.	The second word on the
	      line may be the name of the device where the array  is  normally
	      assembled, such as /dev/md1 or /dev/md/backup.  If the name does
	      not start with  a	 slash	('/'),	it  is	treated	 as  being  in
	      /dev/md/.	  Alternately  the  word <ignore> (complete with angle
	      brackets) can be given in which case any array which matches the
	      rest  of	the line will never be automatically assembled.	 If no
	      device name is given,  mdadm  will  use  various	heuristics  to
	      determine an appropriate name.

	      Subsequent  words identify the array, or identify the array as a
	      member of a group. If multiple identities are given, then a com‐
	      ponent  device  must  match  ALL	identities  to be considered a
	      match.  Each identity word has a tag, and equals sign, and  some
	      value.  The tags are:

	   uuid=  The  value  should  be  a  128 bit uuid in hexadecimal, with
		  punctuation interspersed if desired.	This  must  match  the
		  uuid stored in the superblock.

	   name=  The  value  should  be a simple textual name as was given to
		  mdadm when the array was created.  This must match the  name
		  stored  in  the superblock on a device for that device to be
		  included in the array.  Not all superblock  formats  support

		  The  value  is  an  integer which indicates the minor number
		  that was stored in the superblock when the  array  was  cre‐
		  ated.	 When  an array is created as /dev/mdX, then the minor
		  number X is stored.

		  The value is a comma	separated  list	 of  device  names  or
		  device  name	patterns.  Only devices with names which match
		  one entry in the list will be used to	 assemble  the	array.
		  Note	that the devices listed there must also be listed on a
		  DEVICE line.

	   level= The value is a RAID level.  This is  not  normally  used  to
		  identify an array, but is supported so that the output of

		  mdadm --examine --scan

		  can be use directly in the configuration file.

		  The  value  is  the  number  of devices in a complete active
		  array.  As with level= this is mainly for compatibility with
		  the output of

		  mdadm --examine --scan.

		  The  value  is a number of spare devices to expect the array
		  to have.  The sole use of this keyword and value is as  fol‐
		  lows: mdadm --monitor will report an array if it is found to
		  have fewer than this number of spares when --monitor	starts
		  or when --oneshot is used.

		  The  value  is  a  textual  name for a group of arrays.  All
		  arrays with the same spare-group name are considered	to  be
		  part	of  the	 same  group.	The significance of a group of
		  arrays is that mdadm will, when monitoring the arrays,  move
		  a  spare drive from one array in a group to another array in
		  that group if the first array had a failed or missing	 drive
		  but no spare.

	   auto=  This option is rarely needed with mdadm-3.0, particularly if
		  use with the Linux kernel v2.6.28 or later.  It tells	 mdadm
		  whether  to  use  partitionable  array  or non-partitionable
		  arrays and, in the  absence  of  udev,  how  many  partition
		  devices  to  create.	 From  2.6.28 all md array devices are
		  partitionable, hence this option is not needed.

		  The value of this option can be "yes" or  "md"  to  indicate
		  that	a  traditional,	 non-partitionable  md array should be
		  created, or "mdp", "part" or "partition" to indicate that  a
		  partitionable	 md  array  (only  available  in linux 2.6 and
		  later) should be used.  This later set can also have a  num‐
		  ber  appended	 to  indicate  how  many  partitions to create
		  device files for, e.g.  auto=mdp5.  The default is 4.

		  The option specifies a file in which a  write-intent	bitmap
		  should be found.  When assembling the array, mdadm will pro‐
		  vide this file to the md driver as the  bitmap  file.	  This
		  has  the  same  function  as	the  --bitmap-file  option  to

		  Specify the metadata format that the	array  has.   This  is
		  mainly recognised for comparability with the output of mdadm

		  Specify that this array is a member array of some container.
		  The value given can be either a path name in /dev, or a UUID
		  of the container array.

		  Specify that this array is a member array of some container.
		  Each	type  of  container  has  some way to enumerate member
		  arrays, often a simple sequence number.  The	value  identi‐
		  fies which member of a container the array is.  It will usu‐
		  ally accompany a "container=" word.

	      The mailaddr line gives an E-mail address that alerts should  be
	      sent  to	when mdadm is running in --monitor mode (and was given
	      the --scan option).  There should only be one MAILADDR line  and
	      it  should  have only one address.  Any subsequent addresses are
	      silently ignored.

	      The mailfrom line (which can only be abbreviated to at  least  5
	      characters) gives an address to appear in the "From" address for
	      alert mails.  This can be useful if you want to explicitly set a
	      domain,  as  the	default from address is "root" with no domain.
	      All words on this line are catenated with	 spaces	 to  form  the

	      Note  that  this	value cannot be set via the mdadm commandline.
	      It is only settable via the config file.

	      The program line gives the name of a  program  to	 be  run  when
	      mdadm --monitor detects potentially interesting events on any of
	      the arrays that it is monitoring.	 This program  gets  run  with
	      two or three arguments, they being the Event, the md device, and
	      possibly the related component device.

	      There should only be one program line and it should be give only
	      one program.

       CREATE The  create  line	 gives default values to be used when creating
	      arrays and device entries for arrays.  These include:


	   group= These can give user/group ids or names  to  use  instead  of
		  system defaults (root/wheel or root/disk).

	   mode=  An octal file mode such as 0660 can be given to override the
		  default of 0600.

	   auto=  This corresponds to the --auto flag to mdadm.	 Give yes, md,
		  mdp, part — possibly followed by a number of partitions — to
		  indicate how missing device entries should be created.

		  The name of the metadata format to use if none is explicitly
		  given.   This	 can be useful to impose a system-wide default
		  of version-1 superblocks.

		  Normally when creating devices in /dev/md/ mdadm will create
		  a  matching  symlink	from  /dev/ with a name starting md or
		  md_.	Give symlinks=no to suppress this symlink creation.

		  Since Linux 2.6.29 it has been possible to create md devices
		  with	a  name	 like  md_home rather than just a number, like
		  md3.	mdadm will use the numeric alternative by  default  as
		  other	 tools	that  interact	with md arrays may expect only
		  numbers.  If names=yes is given  in  mdadm.conf  then	 mdadm
		  will	use  a	name  when appropriate.	 If names=no is given,
		  then non-numeric md device names will not be	used  even  if
		  the default changes in a future release of mdadm.

	      The  homehost  line  gives  a  default value for the --homehost=
	      option to mdadm.	There should normally be only one  other  word
	      on  the  line.   It  should either be a host name, or one of the
	      special words <system>, <none> and  <ignore>.   If  <system>  is
	      given,  then  the	 gethostname(2)	 systemcall is used to get the
	      host name.  This is the default.

	      If <ignore> is given, then a flag is set so that when arrays are
	      being  auto-assembled  the  checking of the recorded homehost is
	      disabled.	 If <ignore> is given it is also possible to  give  an
	      explicit	name which will be used when creating arrays.  This is
	      the only case when there can be more that one other word on  the
	      HOMEHOST	line.	If  there  are	other words, or other HOMEHOST
	      lines, they are silently ignored.

	      If <none> is given, then the default of using gethostname(2)  is
	      over-ridden and no homehost name is assumed.

	      When  arrays  are	 created, this host name will be stored in the
	      metadata.	 When arrays are assembled using auto-assembly, arrays
	      which  do not record the correct homehost name in their metadata
	      will be assembled using a	 "foreign"  name.   A  "foreign"  name
	      alway ends with a digit string preceded by an underscore to dif‐
	      ferentiate it from any possible local name. e.g.	/dev/md/1_1 or

       AUTO   A	 list  of names of metadata format can be given, each preceded
	      by a plus or minus sign.	Also the word homehost is  allowed  as
	      is all preceded by plus or minus sign.  all is usually last.

	      When mdadm is auto-assembling an array, either via --assemble or
	      --incremental and it finds metadata of a given type,  it	checks
	      that metadata type against those listed in this line.  The first
	      match wins, where all matches anything.  If  a  match  is	 found
	      that  was preceded by a plus sign, the auto assembly is allowed.
	      If the match was preceded by a minus sign, the auto assembly  is
	      disallowed.  If no match is found, the auto assembly is allowed.

	      If  the  metadata	 indicates that the array was created for this
	      host, and the word homehost appears before any other match, then
	      the array is treated as a valid candidate for auto-assembly.

	      This  can	 be  used  to  disable all auto-assembly (so that only
	      arrays explicitly listed in mdadm.conf or on  the	 command  line
	      are assembled), or to disable assembly of certain metadata types
	      which might be handled by other software.	 It can also  be  used
	      to disable assembly of all foreign arrays - normally such arrays
	      are assembled but given a non-deterministic name in /dev/md/.

	      The known metadata types are 0.90, 1.x, ddf, imsm.

	      AUTO should  be  given  at  most	once.	Subsequent  lines  are
	      silently	ignored.   Thus	 an  earlier  config  file in a config
	      directory will over-ride the setting in a later config file.

       POLICY This is used to specify what automatic behavior  is  allowed  on
	      devices  newly  appearing	 in  the  system and provides a way of
	      marking spares that can be moved to other arrays as well as  the
	      migration domains.  Domain can be defined through policy line by
	      specifying  a  domain  name  for	a   number   of	  paths	  from
	      /dev/disk/by-path/.  A device may belong to several domains. The
	      domain of an array is a union of domains of all devices in  that
	      array.   A  spare	 can  be automatically moved from one array to
	      another if the set of the destination array's domains ppcontains
	      all  the domains of the new disk or if both arrays have the same

	      To update hot plug configuration	it  is	necessary  to  execute
	      mdadm --udev-rules command after changing the config file

	      Key words used in the POLICY line and supported values are:

		     any arbitrary string

		     0.9 1.x ddf or imsm

	      path=  file glob matching anything from /dev/disk/by-path

	      type=  either disk or part.

		     include,  re-add,	spare, spare-same-slot, or force-spare
		     auto= yes, no, or homehost.

	      The action item determines the automatic	behavior  allowed  for
	      devices  matching	 the  path  and	 type  in the same line.  If a
	      device matches several lines with	 different  actions  then  the
	      most  permissive	will  apply.  The  ordering of policy lines is
	      irrelevant to the end result.

		     allows adding a disk to an array if metadata on that disk
		     matches that array

	      re-add will  include the device in the array if it appears to be
		     a current member or a member that	was  recently  removed
		     and  the  array  has  a  write-intent-bitmap to allow the
		     re-add functionality.

	      spare  as above and additionally: if the device is bare  it  can
		     become  a spare if there is any array that it is a candi‐
		     date for based on domains and metadata.

		     as above and additionally if given slot was  used	by  an
		     array  that went degraded recently and the device plugged
		     in has no metadata then it will be automatically added to
		     that array (or it's container)

		     as	 above	and  the disk will become a spare in remaining

       DEVICE /dev/sd[bcdjkl]1
       DEVICE /dev/hda1 /dev/hdb1

       # /dev/md0 is known by its UUID.
       ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371
       # /dev/md1 contains all devices with a minor number of
       #   1 in the superblock.
       ARRAY /dev/md1 superminor=1
       # /dev/md2 is made from precisely these two devices
       ARRAY /dev/md2 devices=/dev/hda1,/dev/hdb1

       # /dev/md4 and /dev/md5 are a spare-group and spares
       #  can be moved between them
       ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df
       ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977
       # /dev/md/home is created if need to be a partitionable md array
       # any spare device number is allocated.
       ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b
       # The name of this array contains a space.
       ARRAY /dev/md9 name='Data Storage'

       POLICY domain=domain1 metadata=imsm path=pci-0000:00:1f.2-scsi-*
       POLICY domain=domain1 metadata=imsm path=pci-0000:04:00.0-scsi-[01]*
       # One domain comprising of  devices  attached  to  specified  paths  is
       #  Bare	device	matching  first path will be made an imsm spare on hot
       # If more than one array is created on devices belonging to domain1 and
       # one of them becomes degraded, then any imsm spare matching  any  path
       # given domain name can be migrated.
       MAILADDR root@mydomain.tld
       PROGRAM /usr/sbin/handle-mdadm-events
       CREATE group=system mode=0640 auto=part-8
       HOMEHOST <system>
       AUTO +1.x homehost -all

       mdadm(8), md(4).


List of man pages available for Archlinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net