summaryrefslogtreecommitdiffstats
path: root/misc/mke2fs.conf.5.in
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--misc/mke2fs.conf.5.in566
1 files changed, 566 insertions, 0 deletions
diff --git a/misc/mke2fs.conf.5.in b/misc/mke2fs.conf.5.in
new file mode 100644
index 0000000..96dbfcb
--- /dev/null
+++ b/misc/mke2fs.conf.5.in
@@ -0,0 +1,566 @@
+.\" -*- nroff -*-
+.\" Copyright 2006 by Theodore Ts'o. All Rights Reserved.
+.\" This file may be copied under the terms of the GNU Public License.
+.\"
+.TH mke2fs.conf 5 "@E2FSPROGS_MONTH@ @E2FSPROGS_YEAR@" "E2fsprogs version @E2FSPROGS_VERSION@"
+.SH NAME
+mke2fs.conf \- Configuration file for mke2fs
+.SH DESCRIPTION
+.I mke2fs.conf
+is the configuration file for
+.BR mke2fs (8).
+It controls the default parameters used by
+.BR mke2fs (8)
+when it is creating ext2, ext3, or ext4 file systems.
+.PP
+The
+.I mke2fs.conf
+file uses an INI-style format. Stanzas, or top-level sections, are
+delimited by square braces: [ ]. Within each section, each line
+defines a relation, which assigns tags to values, or to a subsection,
+which contains further relations or subsections.
+.\" Tags can be assigned multiple values
+An example of the INI-style format used by this configuration file
+follows below:
+.P
+ [section1]
+.br
+ tag1 = value_a
+.br
+ tag1 = value_b
+.br
+ tag2 = value_c
+.P
+ [section 2]
+.br
+ tag3 = {
+.br
+ subtag1 = subtag_value_a
+.br
+ subtag1 = subtag_value_b
+.br
+ subtag2 = subtag_value_c
+.br
+ }
+.br
+ tag1 = value_d
+.br
+ tag2 = value_e
+.br
+ }
+.P
+Comments are delimited by a semicolon (';') or a hash ('#') character
+at the beginning of the comment, and are terminated by the end of
+line character.
+.P
+Tags and values must be quoted using double quotes if they contain
+spaces. Within a quoted string, the standard backslash interpretations
+apply: "\en" (for the newline character),
+"\et" (for the tab character), "\eb" (for the backspace character),
+and "\e\e" (for the backslash character).
+.P
+Some relations expect a boolean value. The parser is quite liberal on
+recognizing ``yes'', '`y'', ``true'', ``t'', ``1'', ``on'', etc. as a
+boolean true value, and ``no'', ``n'', ``false'', ``nil'', ``0'',
+``off'' as a boolean false value.
+.P
+The following stanzas are used in the
+.I mke2fs.conf
+file. They will be described in more detail in future sections of this
+document.
+.TP
+.I [options]
+Contains relations which influence how mke2fs behaves.
+.TP
+.I [defaults]
+Contains relations which define the default parameters
+used by
+.BR mke2fs (8).
+In general, these defaults may be overridden by a definition in the
+.B fs_types
+stanza, or by a command-line option provided by the user.
+.TP
+.I [fs_types]
+Contains relations which define defaults that should be used for specific
+file system and usage types. The file system type and usage type can be
+specified explicitly using
+the
+.BR \-t and \-T
+options to
+.BR mke2fs (8),
+respectively.
+.TP
+.I [devices]
+Contains relations which define defaults for specific devices.
+.SH THE [options] STANZA
+The following relations are defined in the
+.I [options]
+stanza.
+.TP
+.I proceed_delay
+If this relation is set to a positive integer, then mke2fs will
+wait
+.I proceed_delay
+seconds after asking the user for permission to proceed and
+then continue, even if the
+user has not answered the question. Defaults to 0, which means to wait
+until the user answers the question one way or another.
+.TP
+.I sync_kludge
+If this relation is set to a positive integer, then while writing the
+inode table, mke2fs will request the operating system flush out pending
+writes to initialize the inode table every
+.I sync_kludge
+block groups. This is needed to work around buggy kernels that don't
+handle writeback throttling correctly.
+.SH THE [defaults] STANZA
+The following relations are defined in the
+.I [defaults]
+stanza.
+.TP
+.I creator_os
+This relation specifies the "creator operating system" for the
+file system unless it is overridden on the command line.
+The default value is the OS for which the
+.B mke2fs
+executable was compiled.
+.TP
+.I fs_type
+This relation specifies the default file system type if the user does not
+specify it via the
+.B \-t
+option, or if
+.B mke2fs
+is not started using a program name of the form
+.BI mkfs. fs-type\fR.
+If both the user and the
+.B mke2fs.conf
+file do not specify a default file system type, mke2fs will use a
+default file system type of
+.I ext3
+if a journal was requested via a command-line option, or
+.I ext2
+if not.
+.TP
+.I undo_dir
+This relation specifies the directory where the undo file should be
+stored. It can be overridden via the
+.B E2FSPROGS_UNDO_DIR
+environment variable. If the directory location is set to the value
+.IR none ,
+.B mke2fs
+will not create an undo file.
+.PP
+In addition, any tags that can be specified in a per-file system tags
+subsection as defined below (e.g.,
+.IR blocksize ,
+.IR hash_alg ,
+.IR inode_ratio ,
+.IR inode_size ,
+.IR reserved_ratio ,
+etc.) can also be specified in the
+.I defaults
+stanza to specify the default value to be used if the user does not
+specify one on the command line, and the file system-type
+specific section of the configuration file does not specify a default value.
+.SH THE [fs_types] STANZA
+Each tag in the
+.I [fs_types]
+stanza names a file system type or usage type which can be specified via the
+.B \-t
+or
+.B \-T
+options to
+.BR mke2fs (8),
+respectively.
+.P
+The
+.B mke2fs
+program constructs a list of fs_types by concatenating the file system
+type (i.e., ext2, ext3, etc.) with the usage type list. For most
+configuration options,
+.B mke2fs
+will look for a subsection in the
+.I [fs_types]
+stanza corresponding with each entry in the constructed list, with later
+entries overriding earlier file system or usage types.
+For
+example, consider the following
+.B mke2fs.conf
+fragment:
+.P
+[defaults]
+.br
+ base_features = sparse_super,filetype,resize_inode,dir_index
+.br
+ blocksize = 4096
+.br
+ inode_size = 256
+.br
+ inode_ratio = 16384
+.br
+
+.br
+[fs_types]
+.br
+ ext3 = {
+.br
+ features = has_journal
+.br
+ }
+.br
+ ext4 = {
+.br
+ features = extents,flex_bg
+.br
+ inode_size = 256
+.br
+ }
+.br
+ small = {
+.br
+ blocksize = 1024
+.br
+ inode_ratio = 4096
+.br
+ }
+.br
+ floppy = {
+.br
+ features = ^resize_inode
+.br
+ blocksize = 1024
+.br
+ inode_size = 128
+.br
+ }
+.P
+If mke2fs started with a program name of
+.BR mke2fs.ext4 ,
+then the file system type of ext4 will be used. If the file system is
+smaller than 3 megabytes, and no usage type is specified, then
+.B mke2fs
+will use a default
+usage type of
+.IR floppy .
+This results in an fs_types list of "ext4, floppy". Both the ext4
+subsection and the floppy subsection define an
+.I inode_size
+relation, but since the later entries in the fs_types list supersede
+earlier ones, the configuration parameter for fs_types.floppy.inode_size
+will be used, so the file system will have an inode size of 128.
+.P
+The exception to this resolution is the
+.I features
+tag, which specifies a set of changes to the features used by the
+file system, and which is cumulative. So in the above example, first
+the configuration relation defaults.base_features would enable an
+initial feature set with the sparse_super, filetype, resize_inode, and
+dir_index features enabled. Then configuration relation
+fs_types.ext4.features would enable the extents and flex_bg
+features, and finally the configuration relation
+fs_types.floppy.features would remove
+the resize_inode feature, resulting in a file system feature set
+consisting of the sparse_super, filetype, dir_index,
+extents_and flex_bg features.
+.P
+For each file system type, the following tags may be used in that
+fs_type's subsection. These tags may also be used in the
+.I default
+section:
+.TP
+.I base_features
+This relation specifies the features which are initially enabled for this
+file system type. Only one
+.I base_features
+will be used, so if there are multiple entries in the fs_types list
+whose subsections define the
+.I base_features
+relation, only the last will be used by
+.BR mke2fs (8).
+.TP
+.I enable_periodic_fsck
+This boolean relation specifies whether periodic file system checks should be
+enforced at boot time. If set to true, checks will be forced every
+180 days, or after a random number of mounts. These values may
+be changed later via the
+.B -i
+and
+.B -c
+command-line options to
+.BR tune2fs (8).
+.TP
+.I errors
+Change the behavior of the kernel code when errors are detected.
+In all cases, a file system error will cause
+.BR e2fsck (8)
+to check the file system on the next boot.
+.I errors
+can be one of the following:
+.RS 1.2i
+.TP 1.2i
+.B continue
+Continue normal execution.
+.TP
+.B remount-ro
+Remount file system read-only.
+.TP
+.B panic
+Cause a kernel panic.
+.RE
+.TP
+.I features
+This relation specifies a comma-separated list of features edit
+requests which modify the feature set
+used by the newly constructed file system. The syntax is the same as the
+.B -O
+command-line option to
+.BR mke2fs (8);
+that is, a feature can be prefixed by a caret ('^') symbol to disable
+a named feature. Each
+.I feature
+relation specified in the fs_types list will be applied in the order
+found in the fs_types list.
+.TP
+.I force_undo
+This boolean relation, if set to a value of true, forces
+.B mke2fs
+to always try to create an undo file, even if the undo file might be
+huge and it might extend the time to create the file system image
+because the inode table isn't being initialized lazily.
+.TP
+.I default_features
+This relation specifies set of features which should be enabled or
+disabled after applying the features listed in the
+.I base_features
+and
+.I features
+relations. It may be overridden by the
+.B -O
+command-line option to
+.BR mke2fs (8).
+.TP
+.I auto_64-bit_support
+This relation is a boolean which specifies whether
+.BR mke2fs (8)
+should automatically add the 64bit feature if the number of blocks for
+the file system requires this feature to be enabled. The resize_inode
+feature is also automatically disabled since it doesn't support 64-bit
+block numbers.
+.TP
+.I default_mntopts
+This relation specifies the set of mount options which should be enabled
+by default. These may be changed at a later time with the
+.B -o
+command-line option to
+.BR tune2fs (8).
+.TP
+.I blocksize
+This relation specifies the default blocksize if the user does not
+specify a blocksize on the command line.
+.TP
+.I lazy_itable_init
+This boolean relation specifies whether the inode table should
+be lazily initialized. It only has meaning if the uninit_bg feature is
+enabled. If lazy_itable_init is true and the uninit_bg feature is
+enabled, the inode table will
+not be fully initialized by
+.BR mke2fs (8).
+This speeds up file system
+initialization noticeably, but it requires the kernel to finish
+initializing the file system in the background when the file system is
+first mounted.
+.TP
+.I lazy_journal_init
+This boolean relation specifies whether the journal inode should be
+lazily initialized. It only has meaning if the has_journal feature is
+enabled. If lazy_journal_init is true, the journal inode will not be
+fully zeroed out by
+.BR mke2fs .
+This speeds up file system initialization noticeably, but carries some
+small risk if the system crashes before the journal has been overwritten
+entirely one time.
+.TP
+.I journal_location
+This relation specifies the location of the journal.
+.TP
+.I num_backup_sb
+This relation indicates whether file systems with the
+.B sparse_super2
+feature enabled should be created with 0, 1, or 2 backup superblocks.
+.TP
+.I packed_meta_blocks
+This boolean relation specifies whether the allocation bitmaps, inode
+table, and journal should be located at the beginning of the file system.
+.TP
+.I inode_ratio
+This relation specifies the default inode ratio if the user does not
+specify one on the command line.
+.TP
+.I inode_size
+This relation specifies the default inode size if the user does not
+specify one on the command line.
+.TP
+.I reserved_ratio
+This relation specifies the default percentage of file system blocks
+reserved for the super-user, if the user does not specify one on the command
+line.
+.TP
+.I hash_alg
+This relation specifies the default hash algorithm used for the
+new file systems with hashed b-tree directories. Valid algorithms
+accepted are:
+.IR legacy ,
+.IR half_md4 ,
+and
+.IR tea .
+.TP
+.I flex_bg_size
+This relation specifies the number of block groups that will be packed
+together to create one large virtual block group on an ext4 file system.
+This improves meta-data locality and performance on meta-data heavy
+workloads. The number of groups must be a power of 2 and may only be
+specified if the flex_bg file system feature is enabled.
+.TP
+.I options
+This relation specifies additional extended options which should be
+treated by
+.BR mke2fs (8)
+as if they were prepended to the argument of the
+.B -E
+option. This can be used to configure the default extended options used
+by
+.BR mke2fs (8)
+on a per-file system type basis.
+.TP
+.I discard
+This boolean relation specifies whether the
+.BR mke2fs (8)
+should attempt to discard device prior to file system creation.
+.TP
+.I cluster_size
+This relation specifies the default cluster size if the bigalloc file
+system feature is enabled. It can be overridden via the
+.B \-C
+command line option to
+.BR mke2fs (8)
+.TP
+.I make_hugefiles
+This boolean relation enables the creation of pre-allocated files as
+part of formatting the file system. The extent tree blocks for these
+pre-allocated files will be placed near the beginning of the file
+system, so that if all of the other metadata blocks are also configured
+to be placed near the beginning of the file system (by disabling the
+backup superblocks, using the packed_meta_blocks option, etc.), the data
+blocks of the pre-allocated files will be contiguous.
+.TP
+.I hugefiles_dir
+This relation specifies the directory where huge files are created,
+relative to the file system root.
+.TP
+.I hugefiles_uid
+This relation controls the user ownership for all of the files and
+directories created by the
+.I make_hugefiles
+feature.
+.TP
+.I hugefiles_gid
+This relation controls the group ownership for all of the files and
+directories created by the
+.I make_hugefiles
+feature.
+.TP
+.I hugefiles_umask
+This relation specifies the umask used when creating the files and
+directories by the
+.I make_hugefiles
+feature.
+.TP
+.I num_hugefiles
+This relation specifies the number of huge files to be created. If this
+relation is not specified, or is set to zero, and the
+.I hugefiles_size
+relation is non-zero, then
+.I make_hugefiles
+will create as many huge files as can fit to fill the entire file system.
+.TP
+.I hugefiles_slack
+This relation specifies how much space should be reserved for other
+files.
+.TP
+.I hugefiles_size
+This relation specifies the size of the huge files. If this relation is
+not specified, the default is to fill the entire file system.
+.TP
+.I hugefiles_align
+This relation specifies the alignment for the start block of the huge
+files. It also forces the size of huge files to be a multiple of the
+requested alignment. If this relation is not specified, no alignment
+requirement will be imposed on the huge files.
+.TP
+.I hugefiles_align_disk
+This relations specifies whether the alignment should be relative to the
+beginning of the hard drive (assuming that the starting offset of the
+partition is available to mke2fs). The default value is false, which
+will cause hugefile alignment to be relative to the beginning of the
+file system.
+.TP
+.I hugefiles_name
+This relation specifies the base file name for the huge files.
+.TP
+.I hugefiles_digits
+This relation specifies the (zero-padded) width of the field for the
+huge file number.
+.TP
+.I warn_y2038_dates
+This boolean relation specifies whether mke2fs will issue a warning
+when creating a file system with 128 byte inodes (and so therefore will
+not support dates after January 19th, 2038). The default value is true,
+except for file systems created for the GNU Hurd since it only supports
+128-byte inodes.
+.TP
+.I zero_hugefiles
+This boolean relation specifies whether or not zero blocks will be
+written to the hugefiles while
+.BR mke2fs (8)
+is creating them. By default, zero blocks will be written to the huge
+files to avoid stale data from being made available to potentially
+untrusted user programs, unless the device supports a discard/trim
+operation which will take care of zeroing the device blocks. By setting
+.I zero_hugefiles
+to false, this step will always be skipped, which can be useful if it is
+known that the disk has been previously erased, or if the user programs
+that will have access to the huge files are trusted to not reveal stale
+data.
+.TP
+.I encoding
+This relation defines the file name encoding to be used if the casefold
+feature is enabled. Currently the only valid encoding is utf8-12.1 or
+utf8, which requests the most recent Unicode version; since 12.1 is the only
+available Unicode version, utf8 and utf8-12.1 have the same result.
+.I encoding_flags
+This relation defines encoding-specific flags. For utf8 encodings, the
+only available flag is strict, which will cause attempts to create file
+names containing invalid Unicode characters to be rejected by the
+kernel. Strict mode is not enabled by default.
+.SH THE [devices] STANZA
+Each tag in the
+.I [devices]
+stanza names device name so that per-device defaults can be specified.
+.TP
+.I fs_type
+This relation specifies the default parameter for the
+.B \-t
+option, if this option isn't specified on the command line.
+.TP
+.I usage_types
+This relation specifies the default parameter for the
+.B \-T
+option, if this option isn't specified on the command line.
+.SH FILES
+.TP
+.I /etc/mke2fs.conf
+The configuration file for
+.BR mke2fs (8).
+.SH SEE ALSO
+.BR mke2fs (8)