Discrepancy between mkfs.ext4 man page and code on lazy_journal_init default

Discrepancy between mkfs.ext4 man page and code on lazy_journal_init default

[Julian Sun]

Hi,

Recently, I observed a significant difference in the number of
blk_mq_get_tag() calls when executing mkfs.ext4 -F -q /dev/$nvme
versus mkfs.ext4 -F -q -E lazy_itable_init=1,lazy_journal_init=1
/dev/$nvme. The former has over 2,000 more calls than the latter,
which is confusing because the mkfs.ext4 man page states both features
should be enabled by default. This implies the commands should be
equivalent, with no I/O difference.

       lazy_journal_init[= <0 to disable, 1 to enable>]
             If  enabled, the journal inode will not be
fully zeroed out by 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.  If the option
value is omitted, it defaults to 1 to enable lazy journal inode
                              ^^^^^^^^^^^
zeroing.

After examining the mkfs.ext4 source code, I found lazy_journal_init
is not enabled by default. The relevant snippet is:
       journal_flags |= get_bool_from_profile(fs_types,
                                     "lazy_journal_init", 0) ?
                                      EXT2_MKJOURNAL_LAZYINIT : 0;

Here, the default value passed to get_bool_from_profile is 0  , and
/etc/mke2fs.conf lacks lazy_journal_init configuration.
         root:~/e2fsprogs/build# grep lazy_journal_init /etc/mke2fs.conf
         root:~/e2fsprogs/build#

This behavior dates back to a 14-year-old commit 6c54689fadc3,
"mke2fs: skip zeroing journal blocks", contradicting the man page
explicitly.

Am I missing a configuration detail, or is this a genuine
documentation-code discrepancy? If the latter, I'm happy to submit a
patch to resolve it.

Any insights are much appreciated. Looking forward to your response.

ps:
root:~/e2fsprogs/build# mkfs.ext4 -V
mke2fs 1.47.3-rc1 (28-May-2025)
           Using EXT2FS Library version 1.47.3-rc1

Thanks,
-- 
Julian Sun <sunjunchao2870@gmail.com>

Re: Discrepancy between mkfs.ext4 man page and code on lazy_journal_init default

[Theodore Ts'o]

On Thu, Jun 12, 2025 at 08:54:59PM +0800, Julian Sun wrote:
> Hi,
> 
> Recently, I observed a significant difference in the number of
> blk_mq_get_tag() calls when executing mkfs.ext4 -F -q /dev/$nvme
> versus mkfs.ext4 -F -q -E lazy_itable_init=1,lazy_journal_init=1
> /dev/$nvme. The former has over 2,000 more calls than the latter,
> which is confusing because the mkfs.ext4 man page states both features
> should be enabled by default. This implies the commands should be
> equivalent, with no I/O difference.
> 
>        lazy_journal_init[= <0 to disable, 1 to enable>]
>              If  enabled, the journal inode will not be
> fully zeroed out by 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.  If the option
> value is omitted, it defaults to 1 to enable lazy journal inode
>                               ^^^^^^^^^^^
> zeroing.

I agree that this might be a bit misleading, but what was meant was
that:

	mke2fs -E lazy_journal_init

and

	mke2fs -E lazy_journal_init=1

are identical.  The key words here is "If the option value is
omitted".


Note that there is a distinct difference between the extended option
using -E command-line option and specifying the default in
mke2fs.conf.  That is documented in the mke2fs.conf(5) man page.

So the bottom line is that it is possible to change the default of
lazy_journal_init (and lazy_itable_init, etc.) in /etc/mke2fs.conf.
So specifying exactly what the default should be is tricky, because
the system administrator could have changed what is in
/etc/mke2fs.conf.

So there is the default if there is no mention of the option in
/etc/mke2fs.conf; the default that is used if the extended option -E
lazy_itable_init=N is not specified (which is the value in
/etc/mke2fs.conf, or the default if it is not mentioned in
/etc/mke2fs.conf); and then there is the default value if "=N" is not
specified.

'm not sure what's the best way of making this more explicit, short
of doubling or tripling the paragraphs in man pages for mke2fs(8) and
mke2fs.conf(5).  Which would not be ideal....  I'm happy to receive
any suggestions for how to make things a bit more clear but hopefully
in a succint way.

Fortunately, it's super rare that users would ever need to change the
default, and most of the time, it's best not to mess with these knobs
at all....

Cheers,

						- Ted

Re: Discrepancy between mkfs.ext4 man page and code on lazy_journal_init default

[Julian Sun]

On Fri, Jun 13, 2025 at 5:50 AM Theodore Ts'o <tytso@mit.edu> wrote:
>
> On Thu, Jun 12, 2025 at 08:54:59PM +0800, Julian Sun wrote:
> > Hi,
> >
> > Recently, I observed a significant difference in the number of
> > blk_mq_get_tag() calls when executing mkfs.ext4 -F -q /dev/$nvme
> > versus mkfs.ext4 -F -q -E lazy_itable_init=1,lazy_journal_init=1
> > /dev/$nvme. The former has over 2,000 more calls than the latter,
> > which is confusing because the mkfs.ext4 man page states both features
> > should be enabled by default. This implies the commands should be
> > equivalent, with no I/O difference.
> >
> >        lazy_journal_init[= <0 to disable, 1 to enable>]
> >              If  enabled, the journal inode will not be
> > fully zeroed out by 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.  If the option
> > value is omitted, it defaults to 1 to enable lazy journal inode
> >                               ^^^^^^^^^^^
> > zeroing.
>
> I agree that this might be a bit misleading, but what was meant was
> that:
>
>         mke2fs -E lazy_journal_init
>
> and
>
>         mke2fs -E lazy_journal_init=1
>
> are identical.  The key words here is "If the option value is
> omitted".
>

That's a bit surprising... Because for readers searching for the
default value in the man page, they actually want to know the value
when the configuration is completely unspecified, including in
/etc/mke2fs.conf and when not specified via mke2fs -E. It feels like
the current man page description avoids the majority of scenarios and
only describes a rare case.

What do you think about changing the man page description to: "If the
value is not specified in /etc/mke2fs.conf or via mke2fs, it defaults
to disabled."?
This also implicitly conveys that the default value can be overridden
by configurations in /etc/mke2fs.conf or via the mkfs.ext4 -E option.
>
> Note that there is a distinct difference between the extended option
> using -E command-line option and specifying the default in
> mke2fs.conf.  That is documented in the mke2fs.conf(5) man page.
>
> So the bottom line is that it is possible to change the default of
> lazy_journal_init (and lazy_itable_init, etc.) in /etc/mke2fs.conf.
> So specifying exactly what the default should be is tricky, because
> the system administrator could have changed what is in
> /etc/mke2fs.conf.
>
> So there is the default if there is no mention of the option in
> /etc/mke2fs.conf; the default that is used if the extended option -E
> lazy_itable_init=N is not specified (which is the value in
> /etc/mke2fs.conf, or the default if it is not mentioned in
> /etc/mke2fs.conf); and then there is the default value if "=N" is not
> specified.
>
> 'm not sure what's the best way of making this more explicit, short
> of doubling or tripling the paragraphs in man pages for mke2fs(8) and
> mke2fs.conf(5).  Which would not be ideal....  I'm happy to receive
> any suggestions for how to make things a bit more clear but hopefully
> in a succint way.
>
> Fortunately, it's super rare that users would ever need to change the
> default, and most of the time, it's best not to mess with these knobs
> at all....
>
> Cheers,
>
>                                                 - Ted


Thanks,
-- 
Julian Sun <sunjunchao2870@gmail.com>