release/src/router/mdadm/mdadm.conf.5

   1 ''' Copyright Neil Brown and others.
   2 '''   This program is free software; you can redistribute it and/or modify
   3 '''   it under the terms of the GNU General Public License as published by
   4 '''   the Free Software Foundation; either version 2 of the License, or
   5 '''   (at your option) any later version.
   6 ''' See file COPYING in distribution for details.
   7 .TH MDADM.CONF 5
   8 .SH NAME
   9 mdadm.conf \- configuration for management of Software Raid with mdadm
  10 .SH SYNOPSIS
  11 /etc/mdadm.conf
  12 .SH DESCRIPTION
  13 .PP
  14 .B mdadm
  15 is a tool for creating, managing, and monitoring RAID devices using the
  16 .B md
  17 driver in Linux.
  18 .PP
  19 Some common tasks, such as assembling all arrays, can be simplified
  20 by describing the devices and arrays in this configuration file.
  21
  22 .SS SYNTAX
  23 The file should be seen as a collection of words separated by white
  24 space (space, tab, or newline).
  25 Any word that beings with a hash sign (#) starts a comment and that
  26 word together with the remainder of the line is ignored.
  27
  28 Any line that starts with white space (space or tab) is treated as
  29 though it were a continuation of the previous line.
  30
  31 Empty lines are ignored, but otherwise each (non continuation) line
  32 must start with a keyword as listed below.  The keywords are case
  33 insensitive and can be abbreviated to 3 characters.
  34
  35 The keywords are:
  36 .TP
  37 .B DEVICE
  38 A
  39 .B device
  40 line lists the devices (whole devices or partitions) that might contain
  41 a component of an MD array.  When looking for the components of an
  42 array,
  43 .B mdadm
  44 will scan these devices (or any devices listed on the command line).
  45
  46 The
  47 .B device
  48 line may contain a number of different devices (separated by spaces)
  49 and each device name can contain wild cards as defined by
  50 .BR glob (7).
  51
  52 Also, there may be several device lines present in the file.
  53
  54 Alternatively, a
  55 .B device
  56 line can contain the word
  57 .BR partitions .
  58 This will cause
  59 .I mdadm
  60 to read
  61 .I /proc/partitions
  62 and include all devices and partitions found there-in.
  63 .I mdadm
  64 does not use the names from
  65 .I /proc/partitions
  66 but only the major and minor device numbers.  It scans
  67 .I /dev
  68 to find the name that matches the numbers.
  69
  70 If no DEVICE line is present, then "DEVICE partitions" is assumed.
  71
  72 For example:
  73 .IP
  74 DEVICE /dev/hda* /dev/hdc*
  75 .br
  76 DEV    /dev/sd*
  77 .br
  78 DEVICE /dev/discs/disc*/disc
  79 .br
  80 DEVICE partitions
  81
  82 .TP
  83 .B ARRAY
  84 The ARRAY lines identify actual arrays.  The second word on the line
  85 should be the name of the device where the array is normally
  86 assembled, such as
  87 .BR  /dev/md1 .
  88 Subsequent words identify the array, or identify the array as a member
  89 of a group. If multiple identities are given,
  90 then a component device must match ALL identities to be considered a
  91 match.  Each identity word has a tag, and equals sign, and some value.
  92 The tags are:
  93
  94 .RS 4
  95 .TP
  96 .B uuid=
  97 The value should be a 128 bit uuid in hexadecimal, with punctuation
  98 interspersed if desired.  This must match the uuid stored in the
  99 superblock.
 100 .TP
 101 .B name=
 102 The value should be a simple textual name as was given to
 103 .I mdadm
 104 when the array was created.  This must match the name stored in the
 105 superblock on a device for that device to be included in the array.
 106 Not all superblock-formats support names.
 107 .TP
 108 .B super-minor=
 109 The value is an integer which indicates the minor number that was
 110 stored in the superblock when the array was created. When an array is
 111 created as /dev/mdX, then the minor number X is stored.
 112 .TP
 113 .B devices=
 114 The value is a comma separated list of device names or device name
 115 patterns.
 116 Only devices with names which match one entry in the list will be used
 117 to assemble the array.  Note that the devices
 118 listed there must also be listed on a DEVICE line.
 119 .TP
 120 .B level=
 121 The value is a raid level.  This is not normally used to
 122 identify an array, but is supported so that the output of
 123
 124 .B "mdadm --examine --scan"
 125
 126 can be use directly in the configuration file.
 127 .TP
 128 .B num-devices=
 129 The value is the number of devices in a complete active array.  As with
 130 .B level=
 131 this is mainly for compatibility with the output of
 132
 133 .BR "mdadm --examine --scan" .
 134
 135 .TP
 136 .B spares=
 137 The value is a number of spare devices to expect the array to have.
 138 .I mdadm --monitor
 139 will report an array if it is found to have fewer than this number of
 140 spares when
 141 .B --monitor
 142 starts or when
 143 .B --oneshot
 144 is used.
 145
 146 .TP
 147 .B spare-group=
 148 The value is a textual name for a group of arrays.  All arrays with
 149 the same
 150 .B spare-group
 151 name are considered to be part of the same group.  The significance of
 152 a group of arrays is that
 153 .B mdadm
 154 will, when monitoring the arrays, move a spare drive from one array in
 155 a group to another array in that group if the first array had a failed
 156 or missing drive but no spare.
 157
 158 .TP
 159 .B auto=
 160 This option declares to
 161 .B mdadm
 162 that it should try to create the device file of the array if it
 163 doesn't already exist, or exists but with the wrong device number.
 164
 165 The value of this option can be "yes" or "md" to indicate that a
 166 traditional, non-partitionable md array should be created, or "mdp",
 167 "part" or "partition" to indicate that a partitionable md array (only
 168 available in linux 2.6 and later) should be used.  This later set can
 169 also have a number appended to indicate how many partitions to create
 170 device files for, e.g.
 171 .BR auto=mdp5 .
 172 The default is 4.
 173
 174 .TP
 175 .B bitmap=
 176 The option specifies a file in which a write-intent bitmap should be
 177 found.  When assembling the array,
 178 .I mdadm
 179 will provide this file to the
 180 .B md
 181 driver as the bitmap file.  This has the same function as the
 182 .B --bitmap-file
 183 option to
 184 .BR --assemble .
 185
 186 .TP
 187 .B metadata=
 188 Specify the metadata format that the array has.  This is mainly
 189 recognised for comparability with the output of
 190 .IR "mdadm -Es" .
 191
 192 .RE
 193
 194 .TP
 195 .B MAILADDR
 196 The
 197 .B mailaddr
 198 line gives an E-mail address that alerts should be
 199 sent to when
 200 .M mdadm
 201 is running in
 202 .B --monitor
 203 mode (and was given the
 204 .B --scan
 205 option).  There should only be one
 206 .B MAILADDR
 207 line and it should have only one address.
 208
 209
 210 .TP
 211 .B MAILFROM
 212 The
 213 .B mailfrom
 214 line (which can only be abbreviate at leat 5 characters) gives an
 215 address to appear in the "From" address for alert mails.  This can be
 216 useful if you want to explicitly set a domain, as the default from
 217 address is "root" with no domain.  All words on this line are
 218 catenated with spaces to form the address.
 219
 220 Note that this value cannot be set via the
 221 .I mdadm
 222 commandline.  It is only settable via the config file.
 223
 224 .TP
 225 .B PROGRAM
 226 The
 227 .B program
 228 line gives the name of a program to be run when
 229 .B "mdadm --monitor"
 230 detects potentially interesting events on any of the arrays that it
 231 is monitoring.  This program gets run with two or three arguments, they
 232 being the Event, the md device, and possibly the related component
 233 device.
 234
 235 There should only be one
 236 .B program
 237 line and it should be give only one program.
 238
 239
 240 .TP
 241 .B CREATE
 242 The
 243 .B create
 244 line gives default values to be used when creating arrays and device entries for
 245 arrays.
 246 These include:
 247
 248 .RS 4
 249 .TP
 250 .B owner=
 251 .TP
 252 .B group=
 253 These can give user/group ids or names to use instead of system
 254 defaults (root/wheel or root/disk).
 255 .TP
 256 .B mode=
 257 An octal file mode such as 0660 can be given to override the default
 258 of 0600.
 259 .TP
 260 .B auto=
 261 This corresponds to the
 262 .B --auto
 263 flag to mdadm.  Give
 264 .BR yes ,
 265 .BR md ,
 266 .BR mdp ,
 267 .B part
 268 - possibly followed by a number of partitions - to indicate how
 269 missing device entries should be created.
 270
 271 .TP
 272 .B metadata=
 273 The name of the metadata format to use if none is explicitly given.
 274 This can be useful to impose a system-wide default of version-1 superblocks.
 275
 276 .TP
 277 .B symlinks=no
 278 Normally when creating devices in
 279 .B /dev/md/
 280 .I mdadm
 281 will create a matching symlink from
 282 .B /dev/
 283 with a name starting
 284 .B md
 285 or
 286 .BR md_ .
 287 Give
 288 .B symlinked=no
 289 to suppress this symlink creation.
 290 .RE
 291
 292
 293 .SH EXAMPLE
 294 DEVICE /dev/sd[bcdjkl]1
 295 .br
 296 DEVICE /dev/hda1 /dev/hdb1
 297
 298 # /dev/md0 is known by it's UID.
 299 .br
 300 ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371
 301 .br
 302 # /dev/md1 contains all devices with a minor number of
 303 .br
 304 #   1 in the superblock.
 305 .br
 306 ARRAY /dev/md1 superminor=1
 307 .br
 308 # /dev/md2 is made from precisey these two devices
 309 .br
 310 ARRAY /dev/md2 devices=/dev/hda1,/dev/hdb1
 311
 312 # /dev/md4 and /dev/md5 are a spare-group and spares
 313 .br
 314 #  can be moved between them
 315 .br
 316 ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df
 317 .br
 318            spare-group=group1
 319 .br
 320 ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977
 321 .br
 322            spare-group=group1
 323 .br
 324 # /dev/md/home is created if need to be a partitionable md array
 325 .br
 326 # any spare device number is allocated.
 327 .br
 328 ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b
 329 .br
 330            auto=part
 331
 332 MAILADDR root@mydomain.tld
 333 .br
 334 PROGRAM /usr/sbin/handle-mdadm-events
 335 .br
 336 CREATE group=system mode=0640 auto=part-8
 337 .br
 338 HOMEHOST <system>
 339
 340 .SH SEE ALSO
 341 .BR mdadm (8),
 342 .BR md (4).
 343