[PATCH] mke2fs: further updates for mke2fs(8) man page

[PATCH] mke2fs: further updates for mke2fs(8) man page

[Andreas Dilger]

The mke2fs(8) man page was updated in 4727c67dc2, but needs some
more clear descriptions for extra_isize and metadta_csum features.
The uninit_bg feature is supported by all ext4-capable kernels,
and does have a slow e2fsck pass for newly-formatted filesystems,
so remove the caveat.

Signed-off-by: Andreas Dilger <adilger@dilger.ca>
---
 misc/mke2fs.8.in |   36 ++++++++++++++++++++++--------------
 1 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/misc/mke2fs.8.in b/misc/mke2fs.8.in
index df244de..4486014 100644
--- a/misc/mke2fs.8.in
+++ b/misc/mke2fs.8.in
@@ -210,8 +210,8 @@ in earlier versions of
 .BR mke2fs .
 The
 .B \-R
-option is still accepted for backwards compatibility.   The
-following extended options are supported:
+option is still accepted for backwards compatibility, but is deprecated.
+The following extended options are supported:
 .RS 1.2i
 .TP
 .BI mmp_update_interval= interval
@@ -548,7 +548,7 @@ of e2fsprogs will not support file systems with this feature enabled.
 .TP
 .B bigalloc
 .br
-This feature enables clustered allocation, so that the unit of
+This feature enables clustered block allocation, so that the unit of
 allocation is a power of two number of blocks.  That is, each bit in the
 what had traditionally been known as the block allocation bitmap now
 indicates whether a cluster is in use or not, where a cluster is by
@@ -570,7 +570,7 @@ features be enabled.
 .TP
 .B dir_index
 .br
-Use hashed b-trees to speed up lookups in large directories.
+Use hashed b-trees to speed up name lookups in large directories.
 .TP
 .B dir_nlink
 .br
@@ -590,8 +590,15 @@ historical/backwards compatibility reasons.)
 .TP
 .B extra_isize
 .br
-This feature enables storage of nanosecond timestamps and creation
-time, if the inode size is larger than 256 bytes or larger.
+This feature reserves a specific amount of space in each inode for
+extended metadata such as nanosecond timestamps and file creation time,
+even if the current kernel does not current need to reserve this much
+space.  Without this feature, the kernel will reserve the amount of
+space for features currently it currently needs, and the rest may be
+consumed by extended attributes.
+
+For this feature to be useful the inode size must be 256 bytes in size
+or larger.
 .TP
 .B ext_attr
 .br
@@ -649,10 +656,16 @@ set this feature automatically when a file > 2GiB is created.)
 .\" .TP
 .\" .B metadata_csum
 .\" .br
-.\" Filesystem supports metadata checksumming.  This feature enables a
-.\" superset of the functionality of the
+.\" Filesystem supports metadata checksumming.  This feature stores
+.\" checksums for all of the filesystem metadata (superblock, group
+.\" descriptor blocks, inode and block bitmaps, directories, and
+.\" extent tree blocks).  The checksum algorithm used for the metadata
+.\" blocks is different than the one used for group descriptors with the
 .\" .B uninit_bg
-.\" feature.
+.\" feature, these two features are incompatible and
+.\" .B metadata_csum
+.\" will be used preferentially instead of
+.\" .BR uninit_bg .
 .\" .br
 .\" .B Future feature, available in e2fsprogs 1.43-WIP
 .TP
@@ -719,11 +732,6 @@ and keep a high watermark for the unused inodes in a filesystem, to reduce
 .BR e2fsck (8)
 time.  The result is that it can speed up filesystem creation time noticeably
 (if lazy_itable_init is enabled).
-.IP
-This first e2fsck run after enabling this feature will take the
-full time, but subsequent e2fsck runs will take only a fraction of the
-original time, depending on how full the file system is.
-It is only supported by the ext4 filesystem in recent Linux kernels.
 .RE
 .TP
 .B \-q
-- 
1.7.3.4

Re: [PATCH] mke2fs: further updates for mke2fs(8) man page

[Eric Sandeen]

On 12/17/13, 2:17 AM, Andreas Dilger wrote:
> The mke2fs(8) man page was updated in 4727c67dc2, but needs some
> more clear descriptions for extra_isize and metadta_csum features.
> The uninit_bg feature is supported by all ext4-capable kernels,
> and does have a slow e2fsck pass for newly-formatted filesystems,
> so remove the caveat.

Looks ok to me, but I think there's still one thing missing;
it mentions metadata checksums but nothing in the manpage says
how to turn those on, AFAICT:

$ grep -i2 "checksum\|csum\|crc" misc/mke2fs.8
.B uninit_bg
Create a filesystem without initializing all of the block groups.  This
feature also enables checksums and highest-inode-used statistics in each
blockgroup.  This feature can
speed up filesystem creation time noticeably (if lazy_itable_init is


(maybe I'm dense & missing it?)

-Eric

> Signed-off-by: Andreas Dilger <adilger@dilger.ca>
> ---
>  misc/mke2fs.8.in |   36 ++++++++++++++++++++++--------------
>  1 files changed, 22 insertions(+), 14 deletions(-)
> 
> diff --git a/misc/mke2fs.8.in b/misc/mke2fs.8.in
> index df244de..4486014 100644
> --- a/misc/mke2fs.8.in
> +++ b/misc/mke2fs.8.in
> @@ -210,8 +210,8 @@ in earlier versions of
>  .BR mke2fs .
>  The
>  .B \-R
> -option is still accepted for backwards compatibility.   The
> -following extended options are supported:
> +option is still accepted for backwards compatibility, but is deprecated.
> +The following extended options are supported:
>  .RS 1.2i
>  .TP
>  .BI mmp_update_interval= interval
> @@ -548,7 +548,7 @@ of e2fsprogs will not support file systems with this feature enabled.
>  .TP
>  .B bigalloc
>  .br
> -This feature enables clustered allocation, so that the unit of
> +This feature enables clustered block allocation, so that the unit of
>  allocation is a power of two number of blocks.  That is, each bit in the
>  what had traditionally been known as the block allocation bitmap now
>  indicates whether a cluster is in use or not, where a cluster is by
> @@ -570,7 +570,7 @@ features be enabled.
>  .TP
>  .B dir_index
>  .br
> -Use hashed b-trees to speed up lookups in large directories.
> +Use hashed b-trees to speed up name lookups in large directories.
>  .TP
>  .B dir_nlink
>  .br
> @@ -590,8 +590,15 @@ historical/backwards compatibility reasons.)
>  .TP
>  .B extra_isize
>  .br
> -This feature enables storage of nanosecond timestamps and creation
> -time, if the inode size is larger than 256 bytes or larger.
> +This feature reserves a specific amount of space in each inode for
> +extended metadata such as nanosecond timestamps and file creation time,
> +even if the current kernel does not current need to reserve this much
> +space.  Without this feature, the kernel will reserve the amount of
> +space for features currently it currently needs, and the rest may be
> +consumed by extended attributes.
> +
> +For this feature to be useful the inode size must be 256 bytes in size
> +or larger.
>  .TP
>  .B ext_attr
>  .br
> @@ -649,10 +656,16 @@ set this feature automatically when a file > 2GiB is created.)
>  .\" .TP
>  .\" .B metadata_csum
>  .\" .br
> -.\" Filesystem supports metadata checksumming.  This feature enables a
> -.\" superset of the functionality of the
> +.\" Filesystem supports metadata checksumming.  This feature stores
> +.\" checksums for all of the filesystem metadata (superblock, group
> +.\" descriptor blocks, inode and block bitmaps, directories, and
> +.\" extent tree blocks).  The checksum algorithm used for the metadata
> +.\" blocks is different than the one used for group descriptors with the
>  .\" .B uninit_bg
> -.\" feature.
> +.\" feature, these two features are incompatible and
> +.\" .B metadata_csum
> +.\" will be used preferentially instead of
> +.\" .BR uninit_bg .
>  .\" .br
>  .\" .B Future feature, available in e2fsprogs 1.43-WIP
>  .TP
> @@ -719,11 +732,6 @@ and keep a high watermark for the unused inodes in a filesystem, to reduce
>  .BR e2fsck (8)
>  time.  The result is that it can speed up filesystem creation time noticeably
>  (if lazy_itable_init is enabled).
> -.IP
> -This first e2fsck run after enabling this feature will take the
> -full time, but subsequent e2fsck runs will take only a fraction of the
> -original time, depending on how full the file system is.
> -It is only supported by the ext4 filesystem in recent Linux kernels.
>  .RE
>  .TP
>  .B \-q
> 

Re: [PATCH] mke2fs: further updates for mke2fs(8) man page

[Andreas Dilger]

[-- Attachment #1: Type: text/plain, Size: 5205 bytes --]

On Dec 17, 2013, at 8:11 AM, Eric Sandeen <sandeen@redhat.com> wrote:
> On 12/17/13, 2:17 AM, Andreas Dilger wrote:
>> The mke2fs(8) man page was updated in 4727c67dc2, but needs some
>> more clear descriptions for extra_isize and metadta_csum features.
>> The uninit_bg feature is supported by all ext4-capable kernels,
>> and does have a slow e2fsck pass for newly-formatted filesystems,
>> so remove the caveat.
> 
> Looks ok to me, but I think there's still one thing missing;
> it mentions metadata checksums but nothing in the manpage says
> how to turn those on, AFAICT:

Actually, the comments about metadata checksums is commented out in
the man page.  That isn't obvious at first glance.  I had just seen
it in the previous page, and the old description "a superset of the
uninit_bg feature" wasn't very useful.

As with anything, no complaints about the previous patch - it definitely
improved the old content, and there is much more that needs to be done
to document the metadata checksum feature (tune2fs, e2fsck, etc).
Every bit helps.

Cheers, Andreas

> $ grep -i2 "checksum\|csum\|crc" misc/mke2fs.8
> .B uninit_bg
> Create a filesystem without initializing all of the block groups.  This
> feature also enables checksums and highest-inode-used statistics in each
> blockgroup.  This feature can
> speed up filesystem creation time noticeably (if lazy_itable_init is
> 
> 
> (maybe I'm dense & missing it?)
> 
> -Eric
> 
>> Signed-off-by: Andreas Dilger <adilger@dilger.ca>
>> ---
>> misc/mke2fs.8.in |   36 ++++++++++++++++++++++--------------
>> 1 files changed, 22 insertions(+), 14 deletions(-)
>> 
>> diff --git a/misc/mke2fs.8.in b/misc/mke2fs.8.in
>> index df244de..4486014 100644
>> --- a/misc/mke2fs.8.in
>> +++ b/misc/mke2fs.8.in
>> @@ -210,8 +210,8 @@ in earlier versions of
>> .BR mke2fs .
>> The
>> .B \-R
>> -option is still accepted for backwards compatibility.   The
>> -following extended options are supported:
>> +option is still accepted for backwards compatibility, but is deprecated.
>> +The following extended options are supported:
>> .RS 1.2i
>> .TP
>> .BI mmp_update_interval= interval
>> @@ -548,7 +548,7 @@ of e2fsprogs will not support file systems with this feature enabled.
>> .TP
>> .B bigalloc
>> .br
>> -This feature enables clustered allocation, so that the unit of
>> +This feature enables clustered block allocation, so that the unit of
>> allocation is a power of two number of blocks.  That is, each bit in the
>> what had traditionally been known as the block allocation bitmap now
>> indicates whether a cluster is in use or not, where a cluster is by
>> @@ -570,7 +570,7 @@ features be enabled.
>> .TP
>> .B dir_index
>> .br
>> -Use hashed b-trees to speed up lookups in large directories.
>> +Use hashed b-trees to speed up name lookups in large directories.
>> .TP
>> .B dir_nlink
>> .br
>> @@ -590,8 +590,15 @@ historical/backwards compatibility reasons.)
>> .TP
>> .B extra_isize
>> .br
>> -This feature enables storage of nanosecond timestamps and creation
>> -time, if the inode size is larger than 256 bytes or larger.
>> +This feature reserves a specific amount of space in each inode for
>> +extended metadata such as nanosecond timestamps and file creation time,
>> +even if the current kernel does not current need to reserve this much
>> +space.  Without this feature, the kernel will reserve the amount of
>> +space for features currently it currently needs, and the rest may be
>> +consumed by extended attributes.
>> +
>> +For this feature to be useful the inode size must be 256 bytes in size
>> +or larger.
>> .TP
>> .B ext_attr
>> .br
>> @@ -649,10 +656,16 @@ set this feature automatically when a file > 2GiB is created.)
>> .\" .TP
>> .\" .B metadata_csum
>> .\" .br
>> -.\" Filesystem supports metadata checksumming.  This feature enables a
>> -.\" superset of the functionality of the
>> +.\" Filesystem supports metadata checksumming.  This feature stores
>> +.\" checksums for all of the filesystem metadata (superblock, group
>> +.\" descriptor blocks, inode and block bitmaps, directories, and
>> +.\" extent tree blocks).  The checksum algorithm used for the metadata
>> +.\" blocks is different than the one used for group descriptors with the
>> .\" .B uninit_bg
>> -.\" feature.
>> +.\" feature, these two features are incompatible and
>> +.\" .B metadata_csum
>> +.\" will be used preferentially instead of
>> +.\" .BR uninit_bg .
>> .\" .br
>> .\" .B Future feature, available in e2fsprogs 1.43-WIP
>> .TP
>> @@ -719,11 +732,6 @@ and keep a high watermark for the unused inodes in a filesystem, to reduce
>> .BR e2fsck (8)
>> time.  The result is that it can speed up filesystem creation time noticeably
>> (if lazy_itable_init is enabled).
>> -.IP
>> -This first e2fsck run after enabling this feature will take the
>> -full time, but subsequent e2fsck runs will take only a fraction of the
>> -original time, depending on how full the file system is.
>> -It is only supported by the ext4 filesystem in recent Linux kernels.
>> .RE
>> .TP
>> .B \-q
>> 
> 


Cheers, Andreas






[-- Attachment #2: Message signed with OpenPGP using GPGMail --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] mke2fs: further updates for mke2fs(8) man page

[Theodore Ts'o]

On Tue, Dec 17, 2013 at 03:22:15PM -0700, Andreas Dilger wrote:
> 
> Actually, the comments about metadata checksums is commented out in
> the man page.  That isn't obvious at first glance.  I had just seen
> it in the previous page, and the old description "a superset of the
> uninit_bg feature" wasn't very useful.

It's commented out because the changes are going into the maint
branch, which does not yet have metadata_csum support.  Once things
settle down, I'll uncomment the text on the next/master branch, but I
didn't want to do that until we were done editing the man pages, to
avoid merge headaches.

I guess most people aren't as conversant with nroff macros any more
--- it was pretty obvious to me they were commented out.  TeX and
LibreOffice has ruined us all.  :-)

> As with anything, no complaints about the previous patch - it definitely
> improved the old content, and there is much more that needs to be done
> to document the metadata checksum feature (tune2fs, e2fsck, etc).

Yes, and many thanks Uri for working on improving the documentation.
It's something that has been badly needed for some time.

Cheers,

					- Ted