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