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 <[email protected]>
---
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
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 <[email protected]>
> ---
> 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
>
On Dec 17, 2013, at 8:11 AM, Eric Sandeen <[email protected]> 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 <[email protected]>
>> ---
>> 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
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