misc/mke2fs.conf.5.in

   1 .\" -*- nroff -*-
   2 .\" Copyright 2006 by Theodore Ts'o.  All Rights Reserved.
   3 .\" This file may be copied under the terms of the GNU Public License.
   4 .\"
   5 .TH mke2fs.conf 5 "@E2FSPROGS_MONTH@ @E2FSPROGS_YEAR@" "E2fsprogs version @E2FSPROGS_VERSION@"
   6 .SH NAME
   7 mke2fs.conf \- Configuration file for mke2fs
   8 .SH DESCRIPTION
   9 .I mke2fs.conf
  10 is the configuration file for
  11 .BR mke2fs (8).
  12 It controls the default parameters used by
  13 .BR mke2fs (8)
  14 when it is creating ext2 or ext3 filesystems.
  15 .PP
  16 The
  17 .I mke2fs.conf
  18 file uses an INI-style format.  Stanzas, or top-level sections, are
  19 delimited by square braces: [ ].  Within each section, each line
  20 defines a relation, which assigns tags to values, or to a subsection,
  21 which contains further relations or subsections.
  22 .\" Tags can be assigned multiple values
  23 An example of the INI-style format used by this configuration file
  24 follows below:
  25 .P
  26         [section1]
  27 .br
  28                 tag1 = value_a
  29 .br
  30                 tag1 = value_b
  31 .br
  32                 tag2 = value_c
  33 .P
  34         [section 2]
  35 .br
  36                 tag3 = {
  37 .br
  38                         subtag1 = subtag_value_a
  39 .br
  40                         subtag1 = subtag_value_b
  41 .br
  42                         subtag2 = subtag_value_c
  43 .br
  44                 }
  45 .br
  46                 tag1 = value_d
  47 .br
  48                 tag2 = value_e
  49 .br
  50         }
  51 .P
  52 Comments are delimited by a semicolon (';') or a hash ('#') character
  53 at the beginning of the comment, and are terminated by the end of
  54 line character.
  55 .P
  56 Tags and values must be quoted using double quotes if they contain
  57 spaces.  Within a quoted string, the standard backslash interpretations
  58 apply: "\en" (for the newline character),
  59 "\et" (for the tab character), "\eb" (for the backspace character),
  60 and "\e\e" (for the backslash character).
  61 .P
  62 The following stanzas are used in the
  63 .I mke2fs.conf
  64 file.  They will be described in more detail in future sections of this
  65 document.
  66 .TP
  67 .I [defaults]
  68 Contains relations which define the default parameters
  69 used by
  70 .BR mke2fs (8).
  71 In general, these defaults may be overridden by a definition in the
  72 .B fs_types
  73 stanza, or by an command-line option provided by the user.
  74 .TP
  75 .I [fs_types]
  76 Contains relations which define defaults that should be used for specific
  77 filesystem types.  The filesystem type can be specified explicitly using
  78 the
  79 .B -T
  80 option to
  81 .BR mke2fs (8).
  82 .SH THE [defaults] STANZA
  83 The following relations are defined in the
  84 .I [defaults]
  85 stanza.
  86 .TP
  87 .I base_features
  88 This relation specifies the filesystems features which are enabled in
  89 newly created filesystems.  It may be overridden by the
  90 .I base_features
  91 relation found in the filesystem or usage type subsection of
  92 the
  93 .I [fs_types]
  94 stanza.
  95 .TP
  96 .I default_features
  97 This relation specifies a set of features that should be added or
  98 removed to the features listed in the
  99 .I base_features
 100 relation.  It may be overridden by the filesystem-specific
 101 .I default_features
 102 in the filesystem or usage type subsection of
 103 .IR [fs_types] ,
 104 and by the
 105 .B -O
 106 command-line option
 107 to
 108 .BR mke2fs (8).
 109 .TP
 110 .I force_undo
 111 This relation, if set to a boolean value of true, forces
 112 .B mke2fs
 113 to always try to create an undo file, even if the undo file might be
 114 huge and it might extend the time to create the filesystem image
 115 because the inode table isn't being initialized lazily.
 116 .TP
 117 .I fs_type
 118 This relation specifies the default filesystem type if the user does not
 119 specify it via the
 120 .B \-t
 121 option, or if
 122 .B mke2fs
 123 is not started using a program name of the form
 124 .BI mkfs. fs-type\fR.
 125 If both the user and the
 126 .B mke2fs.conf
 127 file does not specify a default filesystem type, mke2fs will use a
 128 default filesystem type of
 129 .IR ext3
 130 if a journal was requested via a command-line option, or
 131 .I ext2
 132 if not.
 133 .TP
 134 .I blocksize
 135 This relation specifies the default blocksize if the user does not
 136 specify a blocksize on the command line, and the filesystem-type
 137 specific section of the configuration file does not specify a blocksize.
 138 .TP
 139 .I hash_alg
 140 This relation specifies the default hash algorithm used for the
 141 new filesystems with hashed b-tree directories.  Valid algorithms
 142 accepted are:
 143 .IR legacy ,
 144 .IR half_md4 ,
 145 and
 146 .IR tea .
 147 .TP
 148 .I inode_ratio
 149 This relation specifies the default inode ratio if the user does not
 150 specify one on the command line, and the filesystem-type
 151 specific section of the configuration file does not specify a default
 152 inode ratio.
 153 .TP
 154 .I inode_size
 155 This relation specifies the default inode size if the user does not
 156 specify one on the command line, and the filesystem-type
 157 specific section of the configuration file does not specify a default
 158 inode size.
 159 .TP
 160 .I undo_dir
 161 This relation specifies the directory where the undo file should be
 162 stored.  It can be overridden via the
 163 .B E2FSPROGS_UNDO_DIR
 164 environment variable.  If the directory location is set to the value
 165 .IR none ,
 166 .B mke2fs
 167 will not create an undo file.
 168 .SH THE [fs_types] STANZA
 169 Each tag in the
 170 .I [fs_types]
 171 stanza names a filesystem type or usage type which can be specified via the
 172 .B \-t
 173 or
 174 .B \-T
 175 options to
 176 .BR mke2fs (8),
 177 respectively.
 178 .P
 179 The
 180 .B mke2fs
 181 program constructs a list of fs_types by concatenating the filesystem
 182 type (i.e., ext2, ext3, etc.) with the usage type list.  For most
 183 configuration options,
 184 .B mke2fs
 185 will look for a subsection in the
 186 .I [fs_types]
 187 stanza corresponding with each entry in the constructed list, with later
 188 entries overriding earlier filesystem or usage types.
 189 For
 190 example, consider the following
 191 .B mke2fs.conf
 192 fragment:
 193 .P
 194 [defaults]
 195 .br
 196         base_features = sparse_super,filetype,resize_inode,dir_index
 197 .br
 198         blocksize = 4096
 199 .br
 200         inode_size = 256
 201 .br
 202         inode_ratio = 16384
 203 .br
 204
 205 .br
 206 [fs_types]
 207 .br
 208         ext3 = {
 209 .br
 210                 features = has_journal
 211 .br
 212         }
 213 .br
 214         ext4 = {
 215 .br
 216                 features = extents,flex_bg
 217 .br
 218                 inode_size = 256
 219 .br
 220         }
 221 .br
 222         small = {
 223 .br
 224                 blocksize = 1024
 225 .br
 226                 inode_ratio = 4096
 227 .br
 228         }
 229 .br
 230         floppy = {
 231 .br
 232                 features = ^resize_inode
 233 .br
 234                 blocksize = 1024
 235 .br
 236                 inode_size = 128
 237 .br
 238         }
 239 .P
 240 If mke2fs started with a program name of
 241 .BR mke2fs.ext4 ,
 242 then the filesystem type of ext4 will be used.  If the filesystem is
 243 smaller than 3 megabytes, and no usage type is specified, then
 244 .B mke2fs
 245 will use a default
 246 usage type of
 247 .IR floppy .
 248 This results in an fs_types list of "ext4, floppy".   Both the ext4
 249 subsection and the floppy subsection define an
 250 .I inode_size
 251 relation, but since the later entries in the fs_types list supersede
 252 earlier ones, the configuration parameter for fs_types.floppy.inode_size
 253 will be used, so the filesystem  will have an inode size of 128.
 254 .P
 255 The exception to this resolution is the
 256 .I features
 257 tag, which is specifies a set of changes to the features used by the
 258 filesystem, and which is cumulative.  So in the above example, first
 259 the configuration relation defaults.base_features would enable an
 260 initial feature set with the sparse_super, filetype, resize_inode, and
 261 dir_index features enabled.  Then configuration relation
 262 fs_types.ext4.features would enable the extents and flex_bg
 263 features, and finally the configuration relation
 264 fs_types.floppy.features would remove
 265 the resize_inode feature, resulting in a filesystem feature set
 266 consisting of the sparse_super, filetype, resize_inode, dir_index,
 267 extents_and flex_bg features.
 268 .P
 269 For each filesystem type, the following tags may be used in that
 270 fs_type's subsection:
 271 .TP
 272 .I base_features
 273 This relation specifies the features which are initially enabled for this
 274 filesystem type.  Only one
 275 .I base_features
 276 will be used, so if there are multiple entries in the fs_types list
 277 whose subsections define the
 278 .I base_features
 279 relation, only the last will be used by
 280 .BR mke2fs (8).
 281 .TP
 282 .I features
 283 This relation specifies a comma-separated list of features edit
 284 requests which modify the feature set
 285 used by the newly constructed filesystem.  The syntax is the same as the
 286 .B -O
 287 command-line option to
 288 .BR mke2fs (8);
 289 that is, a feature can be prefixed by a caret ('^') symbol to disable
 290 a named feature.  Each
 291 .I feature
 292 relation specified in the fs_types list will be applied in the order
 293 found in the fs_types list.
 294 .TP
 295 .I default_features
 296 This relation specifies set of features which should be enabled or
 297 disabled after applying the features listed in the
 298 .I base_features
 299 and
 300 .I features
 301 relations.  It may be overridden by the
 302 .B -O
 303 command-line option to
 304 .BR mke2fs (8).
 305 .TP
 306 .I blocksize
 307 This relation specifies the default blocksize if the user does not
 308 specify a blocksize on the command line.
 309 .TP
 310 .I lazy_itable_init
 311 This relation is a boolean which specifies whether the inode table should
 312 be lazily initialized.  It only has meaning if the uninit_bg feature is
 313 enabled.  If lazy_itable_init is true and the uninit_bg feature is
 314 enabled,  the inode table will
 315 not fully initialized by
 316 .BR mke2fs (8).
 317 This speeds up filesystem
 318 initialization noticeably, but it requires the kernel to finish
 319 initializing the filesystem in the background when the filesystem is
 320 first mounted.
 321 .TP
 322 .I inode_ratio
 323 This relation specifies the default inode ratio if the user does not
 324 specify one on the command line.
 325 .TP
 326 .I inode_size
 327 This relation specifies the default inode size if the user does not
 328 specify one on the command line.
 329 .TP
 330 .I hash_alg
 331 This relation specifies the default hash algorithm used for the
 332 new filesystems with hashed b-tree directories.  Valid algorithms
 333 accepted are:
 334 .IR legacy ,
 335 .IR half_md4 ,
 336 and
 337 .IR tea .
 338 .TP
 339 .I flex_bg_size
 340 This relation specifies the number of block goups that will be packed
 341 together to create one large virtual block group on an ext4 filesystem.
 342 This improves meta-data locality and performance on meta-data heavy
 343 workloads.  The number of goups must be a power of 2 and may only be
 344 specified if the flex_bg filesystem feature is enabled.
 345 .I options
 346 This relation specifies additional extended options which should be
 347 treated by
 348 .BR mke2fs (8)
 349 as if they were prepended to the argument of the
 350 .B -E
 351 option.  This can be used to configure the default extended options used
 352 by
 353 .BR mke2fs (8)
 354 on a per-filesystem type basis.
 355 .TP
 356 .I discard
 357 This relation is a boolean which specifies whether the
 358 .BR mke2fs (8)
 359 should attempt to discard device prior to filesystem creation.
 360 .SH FILES
 361 .TP
 362 .I /etc/mke2fs.conf
 363 The configuration file for
 364 .BR mke2fs (8).
 365 .SH SEE ALSO
 366 .BR mke2fs (8)