X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=mdadm.conf.5;h=27dbab18455d145790e502e101b1a02947ef7d13;hb=b4a5ad4958cb3ad87c3c5fa993e7572c38596d09;hp=0cea47cf9f35fcb8b5d84eee1c11469b126f05b4;hpb=8844e291492b82f4bae6129673fb383a309514c0;p=thirdparty%2Fmdadm.git diff --git a/mdadm.conf.5 b/mdadm.conf.5 index 0cea47cf..27dbab18 100644 --- a/mdadm.conf.5 +++ b/mdadm.conf.5 @@ -25,6 +25,16 @@ 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 +.RB ( ' ) +or double quotes (\fB"\fP) +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. @@ -53,7 +63,7 @@ Also, there may be several device lines present in the file. Alternatively, a .B device -line can contain either of both of the words +line can contain either or both of the words .B containers and .BR partitions . @@ -63,7 +73,7 @@ will cause .I mdadm to look for assembled CONTAINER arrays and included them as a source for assembling further arrays. -.PP + The word .I partitions will cause @@ -86,7 +96,7 @@ DEVICE /dev/hda* /dev/hdc* .br DEV /dev/sd* .br -DEVICE /dev/discs/disc*/disc +DEVICE /dev/disk/by-path/pci* .br DEVICE partitions @@ -95,17 +105,26 @@ DEVICE partitions 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 -.BR /dev/md1 . +.B /dev/md1 +or +.BR /dev/md/backup . +If the name does not start with a slash +.RB (' / '), +it is treated as being in +.BR /dev/md/ . +Alternately the word +.B +(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, .I mdadm -will use various heuristic to determine an appropriate name. -.PP +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 component 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: - .RS 4 .TP .B uuid= @@ -129,11 +148,11 @@ 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 +to assemble the array. Note that the devices listed there must also be listed on a DEVICE line. .TP .B level= -The value is a raid level. This is not normally used to +The value is a RAID level. This is not normally used to identify an array, but is supported so that the output of .B "mdadm \-\-examine \-\-scan" @@ -150,6 +169,7 @@ this is mainly for compatibility with the output of .TP .B spares= The value is a number of spare devices to expect the array to have. +The sole use of this keyword and value is as follows: .B mdadm \-\-monitor will report an array if it is found to have fewer than this number of spares when @@ -172,10 +192,15 @@ or missing drive but no spare. .TP .B auto= -This option declares to +This option is rarely needed with mdadm-3.0, particularly if use with +the Linux kernel v2.6.28 or later. +It tells .I mdadm -that it should try to create the device file of the array if it -doesn't already exist, or exists but with the wrong device number. +whether to use partitionable array or non-partitionable arrays and, +in the absence of +.IR 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", @@ -210,12 +235,12 @@ 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. -.IP +.TP .B member= 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 identifies which member of a -container the array is. It will usually accompany a 'container=' word. +container the array is. It will usually accompany a "container=" word. .RE .TP @@ -231,8 +256,8 @@ mode (and was given the .B \-\-scan option). There should only be one .B MAILADDR -line and it should have only one address. - +line and it should have only one address. Any subsequent addresses +are silently ignored. .TP .B MAILFROM @@ -268,8 +293,8 @@ line and it should be give only one program. .B CREATE The .B create -line gives default values to be used when creating arrays and device entries for -arrays. +line gives default values to be used when creating arrays, new members +of arrays, and device entries for arrays. These include: .RS 4 @@ -314,6 +339,42 @@ or Give .B symlinks=no to suppress this symlink creation. + +.TP +.B names=yes +Since Linux 2.6.29 it has been possible to create +.B md +devices with a name like +.B md_home +rather than just a number, like +.BR md3 . +.I mdadm +will use the numeric alternative by default as other tools that interact +with md arrays may expect only numbers. +If +.B names=yes +is given in +.I mdadm.conf +then +.I mdadm +will use a name when appropriate. +If +.B names=no +is given, then non-numeric +.I md +device names will not be used even if the default changes in a future +release of +.IR mdadm . + +.TP +.B bbl=no +By default, +.I mdadm +will reserve space for a bad block list (bbl) on all devices +included in or added to any array that supports them. Setting +.B bbl=no +will prevent this, so newly added devices will not have a bad +block log. .RE .TP @@ -321,19 +382,230 @@ to suppress this symlink creation. The .B homehost line gives a default value for the -.B --homehost= -option to mdadm. There should be exactly one other word on the line. -It should either exactly -.B -or a host name. +.B \-\-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 +.BR , +.B +and +.BR . If .B is given, then the .BR gethostname ( 2 ) -systemcall is used to get the host name. +systemcall is used to get the host name. This is the default. + +If +.B +is given, then a flag is set so that when arrays are being +auto-assembled the checking of the recorded +.I homehost +is disabled. +If +.B +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 +.B HOMEHOST +line. If there are other words, or other +.B HOMEHOST +lines, they are silently ignored. + +If +.B +is given, then the default of using +.BR 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, only arrays -with this host name stored in the metadata will be considered. +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 differentiate it +from any possible local name. e.g. +.B /dev/md/1_1 +or +.BR /dev/md/home_0 . +.TP +.B AUTO +A list of names of metadata format can be given, each preceded by a +plus or minus sign. Also the word +.I homehost +is allowed as is +.I all +preceded by plus or minus sign. +.I all +is usually last. + +When +.I mdadm +is auto-assembling an array, either via +.I \-\-assemble +or +.I \-\-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 +.I 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 +.I this +host, and the word +.I 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 +.BR /dev/md/ . + +The known metadata types are +.BR 0.90 , +.BR 1.x , +.BR ddf , +.BR imsm . + +.B 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. + +.TP +.B 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. +.I Domain +can be defined through +.I policy +line by specifying a domain name for a number of paths from +.BR /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 +.I domains +contains all the +.I domains +of the new disk or if both arrays have the same +.IR spare-group . + +To update hot plug configuration it is necessary to execute +.B mdadm \-\-udev\-rules +command after changing the config file + +Keywords used in the +.I POLICY +line and supported values are: + +.RS 7 +.TP +.B domain= +any arbitrary string +.TP +.B metadata= +0.9 1.x ddf or imsm +.TP +.B path= +file glob matching anything from +.B /dev/disk/by-path +.TP +.B type= +either +.B disk +or +.BR part . +.TP +.B action= +include, re-add, spare, spare-same-slot, or force-spare +.TP +.B auto= +yes, no, or homehost. + +.P +The +.I action +item determines the automatic behavior allowed for devices matching the +.I path +and +.I type +in the same line. If a device matches several lines with different +.I actions +then the most permissive will apply. The ordering of policy lines +is irrelevant to the end result. +.TP +.B include +allows adding a disk to an array if metadata on that disk matches that array +.TP +.B 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 +.B re\-add +functionality. +.TP +.B spare +as above and additionally: if the device is bare it can +become a spare if there is any array that it is a candidate for based +on domains and metadata. +.TP +.B spare\-same\-slot +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) +.TP +.B force\-spare +as above and the disk will become a spare in remaining cases +.RE + +.TP +.B PART-POLICY +This is similar to +.B POLICY +and accepts the same keyword assignments. It allows a consistent set +of policies to applied to each of the partitions of a device. + +A +.B PART-POLICY +line should set +.I type=disk +and identify the path to one or more disk devices. Each partition on +these disks will be treated according to the +.I action= +setting from this line. If a +.I domain +is set in the line, then the domain associated with each patition will +be based on the domain, but with +.RB \(dq -part N\(dq +appended, when N is the partition number for the partition that was +found. + +.TP +.B SYSFS +The SYSFS line lists custom values of MD device's sysfs attributes which will be +stored in sysfs after the array is assembled. Multiple lines are allowed and each +line has to contain the uuid or the name of the device to which it relates. +.RS 4 +.TP +.B uuid= +hexadecimal identifier of MD device. This has to match the uuid stored in the +superblock. +.TP +.B name= +name of the MD device as was given to +.I mdadm +when the array was created. It will be ignored if +.B uuid +is not empty. +.TP +.RS 7 .SH EXAMPLE DEVICE /dev/sd[bcdjkl]1 @@ -373,7 +645,29 @@ ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977 ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b .br auto=part - +.br +# The name of this array contains a space. +.br +ARRAY /dev/md9 name='Data Storage' +.sp +POLICY domain=domain1 metadata=imsm path=pci-0000:00:1f.2-scsi-* +.br + action=spare +.br +POLICY domain=domain1 metadata=imsm path=pci-0000:04:00.0-scsi-[01]* +.br + action=include +.br +# One domain comprising of devices attached to specified paths is defined. +.br +# Bare device matching first path will be made an imsm spare on hot plug. +.br +# If more than one array is created on devices belonging to domain1 and +.br +# one of them becomes degraded, then any imsm spare matching any path for +.br +# given domain name can be migrated. +.br MAILADDR root@mydomain.tld .br PROGRAM /usr/sbin/handle\-mdadm\-events @@ -381,8 +675,14 @@ PROGRAM /usr/sbin/handle\-mdadm\-events CREATE group=system mode=0640 auto=part\-8 .br HOMEHOST +.br +AUTO +1.x homehost \-all +.br +SYSFS name=/dev/md/raid5 group_thread_cnt=4 sync_speed_max=1000000 +.br +SYSFS uuid=bead5eb6:31c17a27:da120ba2:7dfda40d group_thread_cnt=4 +sync_speed_max=1000000 .SH SEE ALSO .BR mdadm (8), .BR md (4). -