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, ext3, or ext4 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 Some relations expect a boolean value.  The parser is quite liberal on
  63 recognizing ``yes'', '`y'', ``true'', ``t'', ``1'', ``on'', etc. as a
  64 boolean true value, and ``no'', ``n'', ``false'', ``nil'', ``0'',
  65 ``off'' as a boolean false value.
  66 .P
  67 The following stanzas are used in the
  68 .I mke2fs.conf
  69 file.  They will be described in more detail in future sections of this
  70 document.
  71 .TP
  72 .I [options]
  73 Contains relations which influence how mke2fs behaves.
  74 .TP
  75 .I [defaults]
  76 Contains relations which define the default parameters
  77 used by
  78 .BR mke2fs (8).
  79 In general, these defaults may be overridden by a definition in the
  80 .B fs_types
  81 stanza, or by an command-line option provided by the user.
  82 .TP
  83 .I [fs_types]
  84 Contains relations which define defaults that should be used for specific
  85 file system and usage types.  The file system type and usage type can be
  86 specified explicitly using
  87 the
  88 .BR \-t and \-T
  89 options to
  90 .BR mke2fs (8),
  91 respectively.
  92 .SH THE [options] STANZA
  93 The following relations are defined in the
  94 .I [options]
  95 stanza.
  96 .TP
  97 .I proceed_delay
  98 If this relation is set to a positive integer, then if mke2fs will
  99 proceed after waiting
 100 .I proceed_delay
 101 seconds, after asking the user for permission to proceed, even if the
 102 user has not answered the question.  Defaults to 0, which means to wait
 103 until the user answers the question one way or another.
 104 .SH THE [defaults] STANZA
 105 The following relations are defined in the
 106 .I [defaults]
 107 stanza.
 108 .TP
 109 .I base_features
 110 This relation specifies the filesystems features which are enabled in
 111 newly created filesystems.  It may be overridden by the
 112 .I base_features
 113 relation found in the filesystem or usage type subsection of
 114 the
 115 .I [fs_types]
 116 stanza.
 117 .TP
 118 .I default_features
 119 This relation specifies a set of features that should be added or
 120 removed to the features listed in the
 121 .I base_features
 122 relation.  It may be overridden by the filesystem-specific
 123 .I default_features
 124 in the filesystem or usage type subsection of
 125 .IR [fs_types] ,
 126 and by the
 127 .B -O
 128 command-line option
 129 to
 130 .BR mke2fs (8).
 131 .TP
 132 .I enable_periodic_fsck
 133 This boolean relation specifies whether periodic filesystem checks should be
 134 enforced at boot time.  If set to true, checks will be forced every
 135 180 days, or after a random number of mounts.  These values may
 136 be changed later via the
 137 .B -i
 138 and
 139 .B -c
 140 command-line options to
 141 .BR tune2fs (8).
 142 .TP
 143 .I force_undo
 144 This boolean relation, if set to a value of true, forces
 145 .B mke2fs
 146 to always try to create an undo file, even if the undo file might be
 147 huge and it might extend the time to create the filesystem image
 148 because the inode table isn't being initialized lazily.
 149 .TP
 150 .I fs_type
 151 This relation specifies the default filesystem type if the user does not
 152 specify it via the
 153 .B \-t
 154 option, or if
 155 .B mke2fs
 156 is not started using a program name of the form
 157 .BI mkfs. fs-type\fR.
 158 If both the user and the
 159 .B mke2fs.conf
 160 file do not specify a default filesystem type, mke2fs will use a
 161 default filesystem type of
 162 .IR ext3
 163 if a journal was requested via a command-line option, or
 164 .I ext2
 165 if not.
 166 .TP
 167 .I undo_dir
 168 This relation specifies the directory where the undo file should be
 169 stored.  It can be overridden via the
 170 .B E2FSPROGS_UNDO_DIR
 171 environment variable.  If the directory location is set to the value
 172 .IR none ,
 173 .B mke2fs
 174 will not create an undo file.
 175 .PP
 176 In addition, any tags that can be specified in a per-file system tags
 177 subsection as defined below (e.g.,
 178 .IR blocksize ,
 179 .IR hash_alg ,
 180 .IR inode_ratio ,
 181 .IR inode_size ,
 182 .IR reserved_ratio ,
 183 etc.) can also be specified in the
 184 .I defaults
 185 stanza to specify the default value to be used if the user does not
 186 specify one on the command line, and the filesystem-type
 187 specific section of the configuration file does not specify a default value.
 188 .SH THE [fs_types] STANZA
 189 Each tag in the
 190 .I [fs_types]
 191 stanza names a filesystem type or usage type which can be specified via the
 192 .B \-t
 193 or
 194 .B \-T
 195 options to
 196 .BR mke2fs (8),
 197 respectively.
 198 .P
 199 The
 200 .B mke2fs
 201 program constructs a list of fs_types by concatenating the filesystem
 202 type (i.e., ext2, ext3, etc.) with the usage type list.  For most
 203 configuration options,
 204 .B mke2fs
 205 will look for a subsection in the
 206 .I [fs_types]
 207 stanza corresponding with each entry in the constructed list, with later
 208 entries overriding earlier filesystem or usage types.
 209 For
 210 example, consider the following
 211 .B mke2fs.conf
 212 fragment:
 213 .P
 214 [defaults]
 215 .br
 216         base_features = sparse_super,filetype,resize_inode,dir_index
 217 .br
 218         blocksize = 4096
 219 .br
 220         inode_size = 256
 221 .br
 222         inode_ratio = 16384
 223 .br
 224
 225 .br
 226 [fs_types]
 227 .br
 228         ext3 = {
 229 .br
 230                 features = has_journal
 231 .br
 232         }
 233 .br
 234         ext4 = {
 235 .br
 236                 features = extents,flex_bg
 237 .br
 238                 inode_size = 256
 239 .br
 240         }
 241 .br
 242         small = {
 243 .br
 244                 blocksize = 1024
 245 .br
 246                 inode_ratio = 4096
 247 .br
 248         }
 249 .br
 250         floppy = {
 251 .br
 252                 features = ^resize_inode
 253 .br
 254                 blocksize = 1024
 255 .br
 256                 inode_size = 128
 257 .br
 258         }
 259 .P
 260 If mke2fs started with a program name of
 261 .BR mke2fs.ext4 ,
 262 then the filesystem type of ext4 will be used.  If the filesystem is
 263 smaller than 3 megabytes, and no usage type is specified, then
 264 .B mke2fs
 265 will use a default
 266 usage type of
 267 .IR floppy .
 268 This results in an fs_types list of "ext4, floppy".   Both the ext4
 269 subsection and the floppy subsection define an
 270 .I inode_size
 271 relation, but since the later entries in the fs_types list supersede
 272 earlier ones, the configuration parameter for fs_types.floppy.inode_size
 273 will be used, so the filesystem  will have an inode size of 128.
 274 .P
 275 The exception to this resolution is the
 276 .I features
 277 tag, which specifies a set of changes to the features used by the
 278 filesystem, and which is cumulative.  So in the above example, first
 279 the configuration relation defaults.base_features would enable an
 280 initial feature set with the sparse_super, filetype, resize_inode, and
 281 dir_index features enabled.  Then configuration relation
 282 fs_types.ext4.features would enable the extents and flex_bg
 283 features, and finally the configuration relation
 284 fs_types.floppy.features would remove
 285 the resize_inode feature, resulting in a filesystem feature set
 286 consisting of the sparse_super, filetype, dir_index,
 287 extents_and flex_bg features.
 288 .P
 289 For each filesystem type, the following tags may be used in that
 290 fs_type's subsection.   These tags may also be used in the
 291 .I default
 292 section:
 293 .TP
 294 .I base_features
 295 This relation specifies the features which are initially enabled for this
 296 filesystem type.  Only one
 297 .I base_features
 298 will be used, so if there are multiple entries in the fs_types list
 299 whose subsections define the
 300 .I base_features
 301 relation, only the last will be used by
 302 .BR mke2fs (8).
 303 .TP
 304 .I errors
 305 Change the behavior of the kernel code when errors are detected.
 306 In all cases, a filesystem error will cause
 307 .BR e2fsck (8)
 308 to check the filesystem on the next boot.
 309 .I errors
 310 can be one of the following:
 311 .RS 1.2i
 312 .TP 1.2i
 313 .B continue
 314 Continue normal execution.
 315 .TP
 316 .B remount-ro
 317 Remount filesystem read-only.
 318 .TP
 319 .B panic
 320 Cause a kernel panic.
 321 .RE
 322 .TP
 323 .I features
 324 This relation specifies a comma-separated list of features edit
 325 requests which modify the feature set
 326 used by the newly constructed filesystem.  The syntax is the same as the
 327 .B -O
 328 command-line option to
 329 .BR mke2fs (8);
 330 that is, a feature can be prefixed by a caret ('^') symbol to disable
 331 a named feature.  Each
 332 .I feature
 333 relation specified in the fs_types list will be applied in the order
 334 found in the fs_types list.
 335 .TP
 336 .I default_features
 337 This relation specifies set of features which should be enabled or
 338 disabled after applying the features listed in the
 339 .I base_features
 340 and
 341 .I features
 342 relations.  It may be overridden by the
 343 .B -O
 344 command-line option to
 345 .BR mke2fs (8).
 346 .TP
 347 .I auto_64-bit_support
 348 This relation is a boolean which specifies whether
 349 .BR mke2fs (8)
 350 should automatically add the 64bit feature if the number of blocks for
 351 the file system requires this feature to be enabled.  The resize_inode
 352 feature is also automatically disabled since it doesn't support 64-bit
 353 block numbers.
 354 .TP
 355 .I default_mntopts
 356 This relation specifies the set of mount options which should be enabled
 357 by default.  These may be changed at a later time with the
 358 .B -o
 359 command-line option to
 360 .BR tune2fs (8).
 361 .TP
 362 .I blocksize
 363 This relation specifies the default blocksize if the user does not
 364 specify a blocksize on the command line.
 365 .TP
 366 .I lazy_itable_init
 367 This boolean relation specifies whether the inode table should
 368 be lazily initialized.  It only has meaning if the uninit_bg feature is
 369 enabled.  If lazy_itable_init is true and the uninit_bg feature is
 370 enabled,  the inode table will
 371 not be fully initialized by
 372 .BR mke2fs (8).
 373 This speeds up filesystem
 374 initialization noticeably, but it requires the kernel to finish
 375 initializing the filesystem in the background when the filesystem is
 376 first mounted.
 377 .TP
 378 .I journal_location
 379 This relation specifies the location of the journal.
 380 .TP
 381 .I num_backup_sb
 382 This relation indicates whether file systems with the
 383 .B sparse_super2
 384 feature enabled should be created with 0, 1, or 2 backup superblocks.
 385 .TP
 386 .I packed_meta_blocks
 387 This boolean relation specifes whether the allocation bitmaps, inode
 388 table, and journal should be located at the beginning of the file system.
 389 .TP
 390 .I inode_ratio
 391 This relation specifies the default inode ratio if the user does not
 392 specify one on the command line.
 393 .TP
 394 .I inode_size
 395 This relation specifies the default inode size if the user does not
 396 specify one on the command line.
 397 .TP
 398 .I reserved_ratio
 399 This relation specifies the default percentage of filesystem blocks
 400 reserved for the super-user, if the user does not specify one on the command
 401 line.
 402 .TP
 403 .I hash_alg
 404 This relation specifies the default hash algorithm used for the
 405 new filesystems with hashed b-tree directories.  Valid algorithms
 406 accepted are:
 407 .IR legacy ,
 408 .IR half_md4 ,
 409 and
 410 .IR tea .
 411 .TP
 412 .I flex_bg_size
 413 This relation specifies the number of block groups that will be packed
 414 together to create one large virtual block group on an ext4 filesystem.
 415 This improves meta-data locality and performance on meta-data heavy
 416 workloads.  The number of groups must be a power of 2 and may only be
 417 specified if the flex_bg filesystem feature is enabled.
 418 .TP
 419 .I options
 420 This relation specifies additional extended options which should be
 421 treated by
 422 .BR mke2fs (8)
 423 as if they were prepended to the argument of the
 424 .B -E
 425 option.  This can be used to configure the default extended options used
 426 by
 427 .BR mke2fs (8)
 428 on a per-filesystem type basis.
 429 .TP
 430 .I discard
 431 This boolean relation specifies whether the
 432 .BR mke2fs (8)
 433 should attempt to discard device prior to filesystem creation.
 434 .TP
 435 .I cluster_size
 436 This relation specifies the default cluster size if the bigalloc file
 437 system feature is enabled.  It can be overridden via the
 438 .B \-C
 439 command line option to
 440 .BR mke2fs (8)
 441 .TP
 442 .I make_hugefiles
 443 This boolean relation enables the creation of pre-allocated files as
 444 part of formatting the file system.  The extent tree blocks for these
 445 pre-allocated files will be placed near the beginning of the file
 446 system, so that if all of the other metadata blocks are also configured
 447 to be placed near the beginning of the file system (by disabling the
 448 backup superblocks, using the packed_meta_blocks option, etc.), the data
 449 blocks of the pre-allocated files will be contiguous.
 450 .TP
 451 .I hugefiles_uid
 452 This relation controls the user ownership for all of the files and
 453 directories created by the
 454 .I make_hugefiles
 455 feature.
 456 .TP
 457 .I hugefiles_gid
 458 This relation controls the group ownership for all of the files and
 459 directories created by the
 460 .I make_hugefiles
 461 feature.
 462 .TP
 463 .I hugefiles_umask
 464 This relation specifies the umask used when creating the files and
 465 directories by the
 466 .I make_hugefiles
 467 feature.
 468 .TP
 469 .I num_hugefiles
 470 This relation specifies the number of huge files to be created.  If this
 471 relation is not specified, or is set to zero, and the
 472 .I hugefiles_size
 473 relation is non-zero, then
 474 .I make_hugefiles
 475 will create as many huge files as can fit to fill the entire file system.
 476 .TP
 477 .I hugefiles_slack
 478 This relation specifies how much space should be reserved for other
 479 files.
 480 .TP
 481 .I hugefiles_size
 482 This relation specifies the size of the huge files.  If this relation is
 483 not specified, the default is to fill the entire file system.
 484 .TP
 485 .I hugefiles_align
 486 This relation specifies the alignment for the start block of the huge
 487 files.  It also forces the size of huge files to be a multiple of the
 488 requested alignment.  If this relation is not specified, no alignment
 489 requirement will be imposed on the huge files.
 490 .TP
 491 .I hugefiles_align_disk
 492 This relations specifies whether the alignment should be relative to the
 493 beginning of the hard drive (assuming that the starting offset of the
 494 partition is available to mke2fs).  The default value is false, which
 495 will cause hugefile alignment to be relative to the beginning of the
 496 file system.
 497 .TP
 498 .I hugefiles_name
 499 This relation specifies the base file name for the huge files.
 500 .TP
 501 .I hugefiles_digits
 502 This relation specifies the (zero-padded) width of the field for the
 503 huge file number.
 504 .TP
 505 .I zero_hugefiles
 506 This boolean relation specifies whether or not zero blocks will be
 507 written to the hugefiles while
 508 .BR mke2fs(8)
 509 is creating them.  By default, zero blocks will be written to the huge
 510 files to avoid stale data from being made available to potentially
 511 untrusted user programs, unless the device supports a discard/trim
 512 operation which will take care of zeroing the device blocks.  By setting
 513 .I zero_hugefiles
 514 to false, this step will always be skipped, which can be useful if it is
 515 known that the disk has been previously erased, or if the user programs
 516 that will have access to the huge files are trusted to not reveal stale
 517 data.
 518 .SH THE [devices] STANZA
 519 Each tag in the
 520 .I [devices]
 521 stanza names device name so that per-device defaults can be specified.
 522 .TP
 523 .I fs_type
 524 This relation specifies the default parameter for the
 525 .B \-t
 526 option, if this option isn't specified on the command line.
 527 .TP
 528 .I usage_types
 529 This relation specifies the default parameter for the
 530 .B \-T
 531 option, if this option isn't specified on the command line.
 532 .SH FILES
 533 .TP
 534 .I /etc/mke2fs.conf
 535 The configuration file for
 536 .BR mke2fs (8).
 537 .SH SEE ALSO
 538 .BR mke2fs (8)