Debian Codegraph @

upstream/debian-unstable/man5/mke2fs.conf.5

raw
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 "March 2025" "E2fsprogs version 1.47.4"
6 .SH NAME
7 mke2fs.conf \- Configuration file for mke2fs
8 .SH DESCRIPTION
9 \fImke2fs.conf\fR is the configuration file for \fBmke2fs\fR(8).
10 It controls the default parameters used by \fBmke2fs\fR(8)
11 when it is creating ext2, ext3, or ext4 file systems.
12 .PP
13 The \fImke2fs.conf\fR
14 file uses an INI-style format. Stanzas, or top-level sections, are
15 delimited by square braces: [ ]. Within each section, each line
16 defines a relation, which assigns tags to values, or to a subsection,
17 which contains further relations or subsections.
18 .\" Tags can be assigned multiple values
19 An example of the INI-style format used by this configuration file
20 follows below:
21 .P
22 [section1]
23 .br
24 tag1 = value_a
25 .br
26 tag1 = value_b
27 .br
28 tag2 = value_c
29 .P
30 [section 2]
31 .br
32 tag3 = {
33 .br
34 subtag1 = subtag_value_a
35 .br
36 subtag1 = subtag_value_b
37 .br
38 subtag2 = subtag_value_c
39 .br
40 }
41 .br
42 tag1 = value_d
43 .br
44 tag2 = value_e
45 .br
46 }
47 .P
48 Comments are delimited by a semicolon (';') or a hash ('#') character
49 at the beginning of the comment, and are terminated by the end of
50 line character.
51 .P
52 Tags and values must be quoted using double quotes if they contain
53 spaces. Within a quoted string, the standard backslash interpretations
54 apply: "\en" (for the newline character),
55 "\et" (for the tab character), "\eb" (for the backspace character),
56 and "\e\e" (for the backslash character).
57 .P
58 Some relations expect a boolean value. The parser is quite liberal on
59 recognizing ``yes'', '`y'', ``true'', ``t'', ``1'', ``on'', etc. as a
60 boolean true value, and ``no'', ``n'', ``false'', ``nil'', ``0'',
61 ``off'' as a boolean false value.
62 .P
63 The following stanzas are used in the \fImke2fs.conf\fR
64 file. They will be described in more detail in future sections of this
65 document.
66 .TP
67 .I [options]
68 Contains relations which influence how \fBmke2fs\fR(8) behaves.
69 .TP
70 .I [defaults]
71 Contains relations which define the default parameters used by \fBmke2fs\fR(8).
72 In general, these defaults may be overridden by a definition in the
73 \fI[fs_types]\fR stanza, or by a 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 file system and usage types. The file system type and usage type can be
78 specified explicitly using the \fB\-t\fR and \fB\-T\fR options to
79 \fBmke2fs\fR(8), respectively.
80 .TP
81 .I [devices]
82 Contains relations which define defaults for specific devices.
83 .SH THE [options] STANZA
84 The following relations are defined in the \fI[options]\fR stanza.
85 .TP
86 .I proceed_delay
87 If this relation is set to a positive integer, then \fBmke2fs\fR(8) will wait
88 \fIproceed_delay\fR seconds after asking the user for permission to proceed and
89 then continue, even if the
90 user has not answered the question. Defaults to 0, which means to wait
91 until the user answers the question one way or another.
92 .TP
93 .I sync_kludge
94 If this relation is set to a positive integer, then while writing the
95 inode table, \fBmke2fs\fR(8) will request the operating system flush out pending
96 writes to initialize the inode table every
97 \fIsync_kludge\fR
98 block groups. This is needed to work around buggy kernels that don't
99 handle writeback throttling correctly.
100 .SH THE [defaults] STANZA
101 The following relations are defined in the \fI[defaults]\fR stanza.
102 .TP
103 .I creator_os
104 This relation specifies the "creator operating system" for the
105 file system unless it is overridden on the command line.
106 The default value is the OS for which the \fBmke2fs\fR(8) executable was compiled.
107 .TP
108 .I fs_type
109 This relation specifies the default file system type if the user does not
110 specify it via the \fB\-t\fR option, or if \fBmke2fs\fR(8)
111 is not started using a program name of the form \fBmkfs.\fIfs-type\fR.
112 If both the user and the \fImke2fs.conf\fR
113 file do not specify a default file system type, \fBmke2fs\fR will use a
114 default file system type of \fIext3\fR
115 if a journal was requested via a command-line option, or \fIext2\fR if not.
116 .TP
117 .I undo_dir
118 This relation specifies the directory where the undo file should be
119 stored. It can be overridden via the \fBE2FSPROGS_UNDO_DIR\fR
120 environment variable. If the directory location is set to the value
121 \fInone\fR, \fBmke2fs\fR(8) will not create an undo file.
122 .PP
123 In addition, any tags that can be specified in a per-file system tags
124 subsection as defined below (e.g.,
125 .IR blocksize ,
126 .IR hash_alg ,
127 .IR inode_ratio ,
128 .IR inode_size ,
129 .IR reserved_ratio ,
130 etc.) can also be specified in the \fIdefaults\fR
131 stanza to specify the default value to be used if the user does not
132 specify one on the command line, and the file system-type
133 specific section of the configuration file does not specify a default value.
134 .SH THE [fs_types] STANZA
135 Each tag in the \fI[fs_types]\fR
136 stanza names a file system type or usage type which can be specified via the
137 \fB\-t\fR or \fB\-T\fR options to \fBmke2fs\fR(8), respectively.
138 .P
139 The \fBmke2fs\fR(8)
140 program constructs a list of fs_types by concatenating the file system
141 type (i.e., ext2, ext3, etc.) with the usage type list. For most
142 configuration options, \fBmke2fs\fR(8) will look for a subsection in the
143 \fI[fs_types]\fR
144 stanza corresponding with each entry in the constructed list, with later
145 entries overriding earlier file system or usage types.
146 For example, consider the following \fImke2fs.conf\fR fragment:
147 .P
148 [defaults]
149 .br
150 base_features = sparse_super,filetype,resize_inode,dir_index
151 .br
152 blocksize = 4096
153 .br
154 inode_size = 256
155 .br
156 inode_ratio = 16384
157 .br
158
159 .br
160 [fs_types]
161 .br
162 ext3 = {
163 .br
164 features = has_journal
165 .br
166 }
167 .br
168 ext4 = {
169 .br
170 features = extents,flex_bg
171 .br
172 inode_size = 256
173 .br
174 }
175 .br
176 small = {
177 .br
178 blocksize = 1024
179 .br
180 inode_ratio = 4096
181 .br
182 }
183 .br
184 floppy = {
185 .br
186 features = ^resize_inode
187 .br
188 blocksize = 1024
189 .br
190 inode_size = 128
191 .br
192 }
193 .P
194 If \fBmke2fs\fR started with a program name of \fBmke2fs.ext4\fR,
195 then the file system type of ext4 will be used. If the file system is
196 smaller than 3 megabytes, and no usage type is specified, then
197 \fBmke2fs\fR will use a default usage type of \fIfloppy\fR.
198 This results in an fs_types list of "ext4, floppy". Both the ext4
199 subsection and the floppy subsection define an \fIinode_size\fR
200 relation, but since the later entries in the \fI[fs_types]\fR list supersede
201 earlier ones, the configuration parameter for \fIfs_types.floppy.inode_size\fR
202 will be used, so the file system will have an inode size of 128.
203 .P
204 The exception to this resolution is the \fIfeatures\fR
205 tag, which specifies a set of changes to the features used by the
206 file system, and which is cumulative. So in the above example, first
207 the configuration relation \fIdefaults.base_features\fR would enable an
208 initial feature set with the
209 .BR sparse_super ,
210 .BR filetype ,
211 .BR resize_inode ", and"
212 .B dir_index
213 features enabled. Then configuration relation
214 \fIfs_types.ext4.features\fR would enable the \fBextents\fR and \fBflex_bg\fR
215 features, and finally the configuration relation
216 \fIfs_types.floppy.features\fR would remove
217 the \fBresize_inode\fR feature, resulting in a file system feature set
218 consisting of the
219 .BR sparse_super ,
220 .BR filetype ,
221 .BR dir_index ,
222 .BR extents " and"
223 .B flex_bg
224 features.
225 .P
226 For each file system type, the following tags may be used in that
227 fs_type's subsection. These tags may also be used in the \fIdefault\fR section:
228 .TP
229 .I base_features
230 This relation specifies the features which are initially enabled for this
231 file system type. Only one \fIbase_features\fR
232 will be used, so if there are multiple entries in the fs_types list
233 whose subsections define the \fIbase_features\fR
234 relation, only the last will be used by
235 .BR mke2fs (8).
236 .TP
237 .I enable_periodic_fsck
238 This boolean relation specifies whether periodic file system checks should be
239 enforced at boot time. If set to true, checks will be forced every
240 180 days, or after a random number of mounts. These values may
241 be changed later via the \fB-i\fR and \fB-c\fR command-line options to
242 .BR tune2fs (8).
243 .TP
244 .I errors
245 Change the behavior of the kernel code when errors are detected.
246 In all cases, a file system error will cause \fBe2fsck\fR(8)
247 to check the file system on the next boot.
248 \fIerrors\fR can be one of the following:
249 .RS 1.2i
250 .TP 1.2i
251 .B continue
252 Continue normal execution.
253 .TP
254 .B remount-ro
255 Remount file system read-only.
256 .TP
257 .B panic
258 Cause a kernel panic.
259 .RE
260 .TP
261 .I features
262 This relation specifies a comma-separated list of features edit
263 requests which modify the feature set
264 used by the newly constructed file system. The syntax is the same as the
265 \fB-O\fR command-line option to \fBmke2fs\fR(8);
266 that is, a feature can be prefixed by a caret ('^') symbol to disable
267 a named feature. Each \fIfeatures\fR
268 relation specified in the \fI[fs_types]\fR list will be applied in the order
269 found in the \fI[fs_types]\fR list.
270 .TP
271 .I force_undo
272 This boolean relation, if set to a value of true, forces \fBmke2fs\fR
273 to always try to create an undo file, even if the undo file might be
274 huge and it might extend the time to create the file system image
275 because the inode table isn't being initialized lazily.
276 .TP
277 .I default_features
278 This relation specifies set of features which should be enabled or
279 disabled after applying the features listed in the
280 \fIbase_features\fR and \fIfeatures\fR relations. It may be overridden by the
281 \fB-O\fR command-line option to \fBmke2fs\fR(8).
282 .TP
283 .I auto_64-bit_support
284 This relation is a boolean which specifies whether \fBmke2fs\fR(8)
285 should automatically add the \fB64bit\fR feature if the number of blocks for
286 the file system requires this feature to be enabled. \fBThe resize_inode\fR
287 feature is also automatically disabled since it doesn't support 64-bit
288 block numbers.
289 .TP
290 .I default_mntopts
291 This relation specifies the set of mount options which should be enabled
292 by default. These may be changed at a later time with the
293 \fB-o\fR command-line option to \fBtune2fs\fR(8).
294 .TP
295 .I blocksize
296 This relation specifies the default block size if the user does not
297 specify a block size on the command line.
298 .TP
299 .I lazy_itable_init
300 This boolean relation specifies whether the inode table should
301 be lazily initialized. It only has meaning if the uninit_bg feature is
302 enabled. If \fIlazy_itable_init\fR is true and the \fBuninit_bg\fR feature is
303 enabled, the inode table will not be fully initialized by \fBmke2fs\fR(8).
304 This speeds up file system
305 initialization noticeably, but it requires the kernel to finish
306 initializing the file system in the background when the file system is
307 first mounted.
308 .TP
309 .I lazy_journal_init
310 This boolean relation specifies whether the journal inode should be
311 lazily initialized. It only has meaning if the \fBhas_journal\fR feature is
312 enabled. If \fIlazy_journal_init\fR is true, the journal inode will not be
313 fully zeroed out by \fBmke2fs\fR.
314 This speeds up file system initialization noticeably, but carries some
315 small risk if the system crashes before the journal has been overwritten
316 entirely one time.
317 .TP
318 .I journal_location
319 This relation specifies the location of the journal.
320 .TP
321 .I num_backup_sb
322 This relation indicates whether file systems with the \fBsparse_super2\fR
323 feature enabled should be created with 0, 1, or 2 backup superblocks.
324 .TP
325 .I packed_meta_blocks
326 This boolean relation specifies whether the allocation bitmaps, inode
327 table, and journal should be located at the beginning of the file system.
328 .TP
329 .I inode_ratio
330 This relation specifies the default inode ratio if the user does not
331 specify one on the command line.
332 .TP
333 .I inode_size
334 This relation specifies the default inode size if the user does not
335 specify one on the command line.
336 .TP
337 .I reserved_ratio
338 This relation specifies the default percentage of file system blocks
339 reserved for the super-user, if the user does not specify one on the command
340 line.
341 .TP
342 .I hash_alg
343 This relation specifies the default hash algorithm used for the
344 new file systems with hashed b-tree directories. Valid algorithms
345 accepted are:
346 .IR legacy ,
347 .IR half_md4 ,
348 and
349 .IR tea .
350 .TP
351 .I flex_bg_size
352 This relation specifies the number of block groups that will be packed
353 together to create one large virtual block group on an ext4 file system.
354 This improves meta-data locality and performance on meta-data heavy
355 workloads. The number of groups must be a power of 2 and may only be
356 specified if the \fBflex_bg\fR file system feature is enabled.
357 .TP
358 .I options
359 This relation specifies additional extended options which should be
360 treated by \fBmke2fs\fR(8) as if they were prepended to the argument of the
361 \fB-E\fR option. This can be used to configure the default extended options used
362 by \fBmke2fs\fR(8) on a per-file system type basis.
363 .TP
364 .I discard
365 This boolean relation specifies whether the \fBmke2fs\fR(8)
366 should attempt to discard device prior to file system creation.
367 .TP
368 .I set_raid_stride
369 This relation specifies whether the file sytem's RAID stride size is set
370 from the block device if available. Valid values are:
371 .IR always ,
372 .IR disk ,
373 .IR never .
374 The default value is
375 .IR always .
376 .TP
377 .I set_raid_stripe
378 This relation specifies whether the file sytem's RAID stripe size is set
379 from the block device if available. Valid values are:
380 .IR always ,
381 .IR disk ,
382 .IR never .
383 The default value is
384 .IR disk .
385 .TP
386 .I cluster_size
387 This relation specifies the default cluster size if the \fBbigalloc\fR file
388 system feature is enabled. It can be overridden via the
389 \fB\-C\fR command line option to \fBmke2fs\fR(8)
390 .TP
391 .I make_hugefiles
392 This boolean relation enables the creation of pre-allocated files as
393 part of formatting the file system. The extent tree blocks for these
394 pre-allocated files will be placed near the beginning of the file
395 system, so that if all of the other metadata blocks are also configured
396 to be placed near the beginning of the file system (by disabling the
397 backup superblocks, using the packed_meta_blocks option, etc.), the data
398 blocks of the pre-allocated files will be contiguous.
399 .TP
400 .I hugefiles_dir
401 This relation specifies the directory where huge files are created,
402 relative to the file system root.
403 .TP
404 .I hugefiles_uid
405 This relation controls the user ownership for all of the files and
406 directories created by the \fImake_hugefiles\fR feature.
407 .TP
408 .I hugefiles_gid
409 This relation controls the group ownership for all of the files and
410 directories created by the \fImake_hugefiles\fR feature.
411 .TP
412 .I hugefiles_umask
413 This relation specifies the umask used when creating the files and
414 directories by the \fImake_hugefiles\fR feature.
415 .TP
416 .I num_hugefiles
417 This relation specifies the number of huge files to be created. If this
418 relation is not specified, or is set to zero, and the \fIhugefiles_size\fR
419 relation is non-zero, then \fImake_hugefiles\fR
420 will create as many huge files as can fit to fill the entire file system.
421 .TP
422 .I hugefiles_slack
423 This relation specifies how much space should be reserved for other
424 files.
425 .TP
426 .I hugefiles_size
427 This relation specifies the size of the huge files. If this relation is
428 not specified, the default is to fill the entire file system.
429 .TP
430 .I hugefiles_align
431 This relation specifies the alignment for the start block of the huge
432 files. It also forces the size of huge files to be a multiple of the
433 requested alignment. If this relation is not specified, no alignment
434 requirement will be imposed on the huge files.
435 .TP
436 .I hugefiles_align_disk
437 This relations specifies whether the alignment should be relative to the
438 beginning of the hard drive (assuming that the starting offset of the
439 partition is available to \fBmke2fs\fR(8)). The default value is false, which
440 will cause hugefile alignment to be relative to the beginning of the
441 file system.
442 .TP
443 .I hugefiles_name
444 This relation specifies the base file name for the huge files.
445 .TP
446 .I hugefiles_digits
447 This relation specifies the (zero-padded) width of the field for the
448 huge file number.
449 .TP
450 .I warn_y2038_dates
451 This boolean relation specifies whether \fBmke2fs\fR(8) will issue a warning
452 when creating a file system with 128 byte inodes (and so therefore will
453 not support dates after January 19th, 2038). The default value is true,
454 except for file systems created for the GNU Hurd since it only supports
455 128-byte inodes.
456 .TP
457 .I zero_hugefiles
458 This boolean relation specifies whether or not zero blocks will be
459 written to the hugefiles while \fBmke2fs\fR(8)
460 is creating them. By default, zero blocks will be written to the huge
461 files to avoid stale data from being made available to potentially
462 untrusted user programs, unless the device supports a discard/trim
463 operation which will take care of zeroing the device blocks. By setting
464 .I zero_hugefiles
465 to false, this step will always be skipped, which can be useful if it is
466 known that the disk has been previously erased, or if the user programs
467 that will have access to the huge files are trusted to not reveal stale
468 data.
469 .TP
470 .I encoding
471 This relation defines the file name encoding to be used if the casefold
472 feature is enabled. Currently the only valid encoding is utf8-12.1 or
473 utf8, which requests the most recent Unicode version; since 12.1 is the only
474 available Unicode version, utf8 and utf8-12.1 have the same result.
475 .I encoding_flags
476 This relation defines encoding-specific flags. For utf8 encodings, the
477 only available flag is strict, which will cause attempts to create file
478 names containing invalid Unicode characters to be rejected by the
479 kernel. Strict mode is not enabled by default.
480 .SH THE [devices] STANZA
481 Each tag in the \fI[devices]\fR
482 stanza names device name so that per-device defaults can be specified.
483 .TP
484 .I fs_type
485 This relation specifies the default parameter for the \fB\-t\fR
486 option, if this option isn't specified on the command line.
487 .TP
488 .I usage_types
489 This relation specifies the default parameter for the \fB\-T\fR
490 option, if this option isn't specified on the command line.
491 .SH FILES
492 .TP
493 .I /etc/mke2fs.conf
494 The configuration file for
495 .BR mke2fs (8).
496 .SH SEE ALSO
497 .BR mke2fs (8)