[REVIEW] mkfs.xfs man page needs the default settings updated.

[REVIEW] mkfs.xfs man page needs the default settings updated.

[Niv Sardi]

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


Manpages update for the new defaults, please review, I believe I got'em all.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Update-mkfs-manpage-for-new-defaults.patch --]
[-- Type: text/x-diff, Size: 3481 bytes --]

>From 71011d480d52aaefe99ef252dfff513bf77f209e Mon Sep 17 00:00:00 2001
From: Niv Sardi <xaiki@sgi.com>
Date: Fri, 22 Feb 2008 16:48:32 +1100
Subject: [PATCH] Update mkfs manpage for new defaults:

log, attr and inodes v2,
Drop the ability to turn unwritten extents off completly,
reduce imaxpct for big filesystems, less AGs for single disks configs.
---
 xfsprogs/man/man8/mkfs.xfs.8 |   44 +++++------------------------------------
 1 files changed, 6 insertions(+), 38 deletions(-)

diff --git a/xfsprogs/man/man8/mkfs.xfs.8 b/xfsprogs/man/man8/mkfs.xfs.8
index b6024c3..f9a89af 100644
--- a/xfsprogs/man/man8/mkfs.xfs.8
+++ b/xfsprogs/man/man8/mkfs.xfs.8
@@ -304,7 +304,8 @@ bits.
 This specifies the maximum percentage of space in the filesystem that
 can be allocated to inodes. The default
 .I value
-is 25%. Setting the
+is 25% for filesystems under 1TB, 5% for filesystems under 50TB and 1%
+for filesystems over 50TB. Setting the
 .I value
 to 0 means that essentially all of the filesystem can
 become inode blocks.
@@ -327,16 +328,10 @@ that does not have the inode alignment feature
 .BI attr[= value ]
 This is used to specify the version of extended attribute inline allocation
 policy to be used.
-By default, this is zero.  Once extended attributes are used for the
+By default, this is 2.  Once extended attributes are used for the
 first time, the version will be set to either one or two.
 The current version (two) uses a more efficient algorithm for managing
-the available inline inode space than version one does, however, for
-backward compatibility reasons (and in the absence of the
-.B attr=2
-mkfs option, or the
-.B attr2
-mount option), version one will be selected
-by default when attributes are first used on a filesystem.
+the available inline inode space than version one does.
 .RE
 .TP
 .BI \-l " log_section_options"
@@ -389,15 +384,9 @@ and directory block size, the minimum log size is larger than 512 blocks.
 .BI version= value
 This specifies the version of the log. The
 .I value
-is either 1 or 2. Specifying
+is either 1 or 2 (the default is 2).
 .B version=2
-enables the
-.B sunit
-suboption, and allows the logbsize to be increased beyond 32K.
-Version 2 logs are automatically selected if a log stripe unit
-is specified.  See
-.BR sunit " and " su
-suboptions, below.
+allows the logbsize to be increased beyond 32K.
 .TP
 .BI sunit= value
 This specifies the alignment to be used for log writes. The
@@ -430,27 +419,6 @@ suffixes). This value must be a multiple of the filesystem block size.
 Version 2 logs are automatically selected if the log
 .B su
 suboption is specified.
-.TP
-.BI lazy-count= value
-This changes the method of logging various persistent counters
-in the superblock.  Under metadata intensive workloads, these
-counters are updated and logged frequently enough that the superblock
-updates become a serialisation point in the filesystem. The
-.I value
-can be either 0 or 1.
-.IP
-With
-.BR lazy-count=1 ,
-the superblock is not modified or logged on every change of the
-persistent counters. Instead, enough information is kept in
-other parts of the filesystem to be able to maintain the persistent
-counter values without needed to keep them in the superblock.
-This gives significant improvements in performance on some configurations.
-The default
-.I value
-is 0 (off) so you must specify
-.B lazy-count=1
-if you want to make use of this feature.
 .RE
 .TP
 .BI \-n " naming_options"
-- 
1.5.4.1


[-- Attachment #3: Type: text/plain, Size: 15 bytes --]


-- 
Niv Sardi

Re: [REVIEW] mkfs.xfs man page needs the default settings updated.

[Eric Sandeen]

Niv Sardi wrote:
> Manpages update for the new defaults, please review, I believe I got'em all.

(hmm attachments make it slightly trickier to reply inline...)

>>From 71011d480d52aaefe99ef252dfff513bf77f209e Mon Sep 17 00:00:00 2001
> From: Niv Sardi <xaiki@sgi.com>
> Date: Fri, 22 Feb 2008 16:48:32 +1100
> Subject: [PATCH] Update mkfs manpage for new defaults:
> 
> log, attr and inodes v2,
> Drop the ability to turn unwritten extents off completly,
> reduce imaxpct for big filesystems, less AGs for single disks configs.
> ---
>  xfsprogs/man/man8/mkfs.xfs.8 |   44 +++++------------------------------------
>  1 files changed, 6 insertions(+), 38 deletions(-)
> 
> diff --git a/xfsprogs/man/man8/mkfs.xfs.8 b/xfsprogs/man/man8/mkfs.xfs.8
> index b6024c3..f9a89af 100644
> --- a/xfsprogs/man/man8/mkfs.xfs.8
> +++ b/xfsprogs/man/man8/mkfs.xfs.8
> @@ -304,7 +304,8 @@ bits.
>  This specifies the maximum percentage of space in the filesystem that
>  can be allocated to inodes. The default
>  .I value
> -is 25%. Setting the
> +is 25% for filesystems under 1TB, 5% for filesystems under 50TB and 1%
> +for filesystems over 50TB. Setting the
>  .I value
>  to 0 means that essentially all of the filesystem can
>  become inode blocks.

Is it worth saying why you might want to override this?  (i.e. why was
it reduced for large filesystems, what was detrimental about having 25%
at 50T?)

> @@ -327,16 +328,10 @@ that does not have the inode alignment feature
>  .BI attr[= value ]
>  This is used to specify the version of extended attribute inline allocation
>  policy to be used.
> -By default, this is zero.  Once extended attributes are used for the
> +By default, this is 2.  Once extended attributes are used for the
>  first time, the version will be set to either one or two.

well, it will be set to what is specified, or the default, right?
Again, why would I choose one over the other?

>  The current version (two) uses a more efficient algorithm for managing
> -the available inline inode space than version one does, however, for
> -backward compatibility reasons (and in the absence of the
> -.B attr=2
> -mkfs option, or the
> -.B attr2
> -mount option), version one will be selected
> -by default when attributes are first used on a filesystem.
> +the available inline inode space than version one does.

ah so I would never want to use 1?  Or might I want to use it for
backwards compatibility?  or?

>  .RE
>  .TP
>  .BI \-l " log_section_options"
> @@ -389,15 +384,9 @@ and directory block size, the minimum log size is larger than 512 blocks.
>  .BI version= value
>  This specifies the version of the log. The
>  .I value
> -is either 1 or 2. Specifying
> +is either 1 or 2 (the default is 2).
>  .B version=2
> -enables the
> -.B sunit
> -suboption, and allows the logbsize to be increased beyond 32K.
> -Version 2 logs are automatically selected if a log stripe unit
> -is specified.  See
> -.BR sunit " and " su
> -suboptions, below.
> +allows the logbsize to be increased beyond 32K.

and it allows the sunit/su suboptions?  And what's this 32K thing, and
what's logbsize?  The first-time reader may wonder what's special about
32K.  Why would one want to use logv1 at this point, any reason?
Perhaps it would be better to document limitations of v1 rather than the
non-limitations of v2?  Or just drop v1 altogether?

>  .TP
>  .BI sunit= value
>  This specifies the alignment to be used for log writes. The
> @@ -430,27 +419,6 @@ suffixes). This value must be a multiple of the filesystem block size.
>  Version 2 logs are automatically selected if the log
>  .B su
>  suboption is specified.
> -.TP
> -.BI lazy-count= value
> -This changes the method of logging various persistent counters
> -in the superblock.  Under metadata intensive workloads, these
> -counters are updated and logged frequently enough that the superblock
> -updates become a serialisation point in the filesystem. The
> -.I value
> -can be either 0 or 1.
> -.IP
> -With
> -.BR lazy-count=1 ,
> -the superblock is not modified or logged on every change of the
> -persistent counters. Instead, enough information is kept in
> -other parts of the filesystem to be able to maintain the persistent
> -counter values without needed to keep them in the superblock.
> -This gives significant improvements in performance on some configurations.
> -The default
> -.I value
> -is 0 (off) so you must specify
> -.B lazy-count=1
> -if you want to make use of this feature.

lazy-count is no longer a configurable option?

-Eric

>  .RE
>  .TP
>  .BI \-n " naming_options"
> -- 1.5.4.1
> 
> 
> 
> 
> -- Niv Sardi 

Re: [REVIEW] mkfs.xfs man page needs the default settings updated.

[Eric Sandeen]

Eric Sandeen wrote:
> Niv Sardi wrote:
>> Manpages update for the new defaults, please review, I believe I got'em all.
> 

(btw review was a bit pedantic becase there are always a million
questions about tuning & options.  Let's try to be as clear as we can in
the manpage at least...)

-Eric

Re: [REVIEW] mkfs.xfs man page needs the default settings updated, TAKE 2.

[Niv Sardi]

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


Thanks to Eric for the comments, is this better ?

Cheers,
-- 
Niv Sardi

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Update-mkfs-manpage-for-new-defaults.patch --]
[-- Type: text/x-diff, Size: 3452 bytes --]

>From 7e0e328663858ecf13f35678f1a6d349c3d4dd5a Mon Sep 17 00:00:00 2001
From: Niv Sardi <xaiki@sgi.com>
Date: Fri, 22 Feb 2008 16:48:32 +1100
Subject: [PATCH] Update mkfs manpage for new defaults:

log, attr and inodes v2,
Drop the ability to turn unwritten extents off completly,
reduce imaxpct for big filesystems, less AGs for single disks configs.
---
 xfsprogs/man/man8/mkfs.xfs.8 |   41 ++++++++++++++++++-----------------------
 1 files changed, 18 insertions(+), 23 deletions(-)

diff --git a/xfsprogs/man/man8/mkfs.xfs.8 b/xfsprogs/man/man8/mkfs.xfs.8
index b6024c3..afc284c 100644
--- a/xfsprogs/man/man8/mkfs.xfs.8
+++ b/xfsprogs/man/man8/mkfs.xfs.8
@@ -304,10 +304,16 @@ bits.
 This specifies the maximum percentage of space in the filesystem that
 can be allocated to inodes. The default
 .I value
-is 25%. Setting the
+is 25% for filesystems under 1TB, 5% for filesystems under 50TB and 1%
+for filesystems over 50TB. Setting the
 .I value
-to 0 means that essentially all of the filesystem can
-become inode blocks.
+to 0 means that essentially all of the filesystem can become inode
+blocks. Note that this is only used by inode32 (on 32bits platforms),
+and is ignored on 64bits platforms. On 32 bits platforms, we can only
+use the first TB of disk space for inodes, so the allocator will try
+to avoid this region, hence miss-using the first AG if this is set to
+high (the worst case is a 4TB filesystem where a full AG will be
+untouched by anything but inodes with a 25% maxpct).
 .TP
 .BI align[= value ]
 This is used to specify that inode allocation is or is not aligned. The
@@ -325,18 +331,11 @@ that does not have the inode alignment feature
 (any release of IRIX before 6.2, and IRIX 6.2 without XFS patches).
 .TP
 .BI attr[= value ]
-This is used to specify the version of extended attribute inline allocation
-policy to be used.
-By default, this is zero.  Once extended attributes are used for the
-first time, the version will be set to either one or two.
-The current version (two) uses a more efficient algorithm for managing
-the available inline inode space than version one does, however, for
-backward compatibility reasons (and in the absence of the
-.B attr=2
-mkfs option, or the
-.B attr2
-mount option), version one will be selected
-by default when attributes are first used on a filesystem.
+This is used to specify the version of extended attribute inline
+allocation policy to be used.  By default, this is 2.  The current
+version (two) uses a more efficient algorithm for managing the
+available inline inode space than version one does. This option is
+kept for backward compatibility, attr2 was added in kernel 2.6.16.
 .RE
 .TP
 .BI \-l " log_section_options"
@@ -389,15 +388,11 @@ and directory block size, the minimum log size is larger than 512 blocks.
 .BI version= value
 This specifies the version of the log. The
 .I value
-is either 1 or 2. Specifying
+is either 1 or 2 (the default is 2).
 .B version=2
-enables the
-.B sunit
-suboption, and allows the logbsize to be increased beyond 32K.
-Version 2 logs are automatically selected if a log stripe unit
-is specified.  See
-.BR sunit " and " su
-suboptions, below.
+allows bigger log buffer size (version 1 had a limit at 32K), and the
+use of the sunit and su options. Possibility to use version=1 is left
+for backward compatibility only.
 .TP
 .BI sunit= value
 This specifies the alignment to be used for log writes. The
-- 
1.5.4.3

Re: [REVIEW] mkfs.xfs man page needs the default settings updated, TAKE 2.

[Eric Sandeen]

Niv Sardi wrote:
> Thanks to Eric for the comments, is this better ?
> 
> Cheers,
> 
> -- Niv Sardi
> 
> 
> 
> From 7e0e328663858ecf13f35678f1a6d349c3d4dd5a Mon Sep 17 00:00:00 2001
> From: Niv Sardi <xaiki@sgi.com>
> Date: Fri, 22 Feb 2008 16:48:32 +1100
> Subject: [PATCH] Update mkfs manpage for new defaults:
> 
> log, attr and inodes v2,
> Drop the ability to turn unwritten extents off completly,
> reduce imaxpct for big filesystems, less AGs for single disks configs.
> ---
>  xfsprogs/man/man8/mkfs.xfs.8 |   41 ++++++++++++++++++-----------------------
>  1 files changed, 18 insertions(+), 23 deletions(-)
> 
> diff --git a/xfsprogs/man/man8/mkfs.xfs.8 b/xfsprogs/man/man8/mkfs.xfs.8
> index b6024c3..afc284c 100644
> --- a/xfsprogs/man/man8/mkfs.xfs.8
> +++ b/xfsprogs/man/man8/mkfs.xfs.8
> @@ -304,10 +304,16 @@ bits.
>  This specifies the maximum percentage of space in the filesystem that
>  can be allocated to inodes. The default
>  .I value
> -is 25%. Setting the
> +is 25% for filesystems under 1TB, 5% for filesystems under 50TB and 1%
> +for filesystems over 50TB. Setting the
>  .I value
> -to 0 means that essentially all of the filesystem can
> -become inode blocks.
> +to 0 means that essentially all of the filesystem can become inode
> +blocks. Note that this is only used by inode32 (on 32bits platforms),
> +and is ignored on 64bits platforms. 

Really?  The m_maxicount tests in xfs_ialloc_ag_alloc and xfs_dialloc
don't seem to care about inode32 or not, unless I'm missing something.

> +On 32 bits platforms, we can only
> +use the first TB of disk space for inodes, 

well, that depends on the inode size...

> +so the allocator will try

the data allocator...

> +to avoid this region, hence miss-using the first AG if this is set to
> +high (the worst case is a 4TB filesystem where a full AG will be
> +untouched by anything but inodes with a 25% maxpct).

ah, ok.  It becomes slightly clearer.  :)

How about...

maxpct=value
	This specifies the maximum percentage of space in the
	filesystem that can be allocated to  inodes. The
	default value is 25% for filesystems under 1TB, 5% for
	filesystems under 50TB and 1% for filesystems over 50TB.

	In the default inode allocation mode, inode blocks are
	chosen such that inode numbers will not exceed 32 bits,
	which restricts the inode blocks to the lower portion of
	the filesystem.  The data block allocator will avoid these
	low blocks to accommodate the specified maxpct, so a high
	value may result in a filesystem with nothing but inodes
	in a significant portion of the lower blocks of the
	filesystem.  (This restriction is not present when
	the filesystem is mounted with the "inode64" option on
	64-bit platforms).

	Setting the value to 0 means that essentially all of the
	filesystem can become inode blocks, subject to inode32
	restrictions.

	This value can be modified with xfs_growfs(8).

eh... could be better... but how's it sound?

>  .TP
>  .BI align[= value ]
>  This is used to specify that inode allocation is or is not aligned. The
> @@ -325,18 +331,11 @@ that does not have the inode alignment feature
>  (any release of IRIX before 6.2, and IRIX 6.2 without XFS patches).
>  .TP
>  .BI attr[= value ]
> -This is used to specify the version of extended attribute inline allocation
> -policy to be used.
> -By default, this is zero.  Once extended attributes are used for the
> -first time, the version will be set to either one or two.
> -The current version (two) uses a more efficient algorithm for managing
> -the available inline inode space than version one does, however, for
> -backward compatibility reasons (and in the absence of the
> -.B attr=2
> -mkfs option, or the
> -.B attr2
> -mount option), version one will be selected
> -by default when attributes are first used on a filesystem.
> +This is used to specify the version of extended attribute inline
> +allocation policy to be used.  By default, this is 2.  The current
> +version (two) uses a more efficient algorithm for managing the
> +available inline inode space than version one does. This option is
> +kept for backward compatibility, attr2 was added in kernel 2.6.16.

attr[=value] (hmm why the brackets; is value really optional?)
	This is used to specify the version of extended attribute
	inline allocation policy to be used.  By default, this is 2,
	which uses an efficient algorithm for managing the available
	inline inode space between attribute and extent data.

	The previous version 1, which has fixed regions for attribute
	and extent data, is kept for backwards compatibility with
	kernels older than version 2.6.16.

(aside: will older kernels refuse to mount attr2 filesystems?  I suppose
they will but I'm not sure they need to?)


-Eric

>  .RE
>  .TP
>  .BI \-l " log_section_options"
> @@ -389,15 +388,11 @@ and directory block size, the minimum log size is larger than 512 blocks.
>  .BI version= value
>  This specifies the version of the log. The
>  .I value
> -is either 1 or 2. Specifying
> +is either 1 or 2 (the default is 2).
>  .B version=2
> -enables the
> -.B sunit
> -suboption, and allows the logbsize to be increased beyond 32K.
> -Version 2 logs are automatically selected if a log stripe unit
> -is specified.  See
> -.BR sunit " and " su
> -suboptions, below.
> +allows bigger log buffer size (version 1 had a limit at 32K), and the
> +use of the sunit and su options. Possibility to use version=1 is left
> +for backward compatibility only.

version=value
	This specifies the version of the log.  The current default
	is 2, which allows for larger log buffer sizes, as well as
	supporting stripe-aligned log writes (see the sunit and su
	options, below).

	The previous version 1, which is limited to 32k log buffers
	and does not support stripe-aligned writes, is kept for
	backwards compatibility with kernels older than version
	2.XX.XX

>  .TP
>  .BI sunit= value
>  This specifies the alignment to be used for log writes. The
> -- 1.5.4.3 

Re: [REVIEW] mkfs.xfs man page needs the default settings updated, TAKE 2.

[David Chinner]

On Wed, Mar 05, 2008 at 11:29:11PM -0600, Eric Sandeen wrote:
> Niv Sardi wrote:
> > Thanks to Eric for the comments, is this better ?
> > 
> > Cheers,
> > 
> > -- Niv Sardi
> > 
> > 
> > 
> > From 7e0e328663858ecf13f35678f1a6d349c3d4dd5a Mon Sep 17 00:00:00 2001
> > From: Niv Sardi <xaiki@sgi.com>
> > Date: Fri, 22 Feb 2008 16:48:32 +1100
> > Subject: [PATCH] Update mkfs manpage for new defaults:
> > 
> > log, attr and inodes v2,
> > Drop the ability to turn unwritten extents off completly,
> > reduce imaxpct for big filesystems, less AGs for single disks configs.
> > ---
> >  xfsprogs/man/man8/mkfs.xfs.8 |   41 ++++++++++++++++++-----------------------
> >  1 files changed, 18 insertions(+), 23 deletions(-)
> > 
> > diff --git a/xfsprogs/man/man8/mkfs.xfs.8 b/xfsprogs/man/man8/mkfs.xfs.8
> > index b6024c3..afc284c 100644
> > --- a/xfsprogs/man/man8/mkfs.xfs.8
> > +++ b/xfsprogs/man/man8/mkfs.xfs.8
> > @@ -304,10 +304,16 @@ bits.
> >  This specifies the maximum percentage of space in the filesystem that
> >  can be allocated to inodes. The default
> >  .I value
> > -is 25%. Setting the
> > +is 25% for filesystems under 1TB, 5% for filesystems under 50TB and 1%
> > +for filesystems over 50TB. Setting the
> >  .I value
> > -to 0 means that essentially all of the filesystem can
> > -become inode blocks.
> > +to 0 means that essentially all of the filesystem can become inode
> > +blocks. Note that this is only used by inode32 (on 32bits platforms),
> > +and is ignored on 64bits platforms. 
> 
> Really?  The m_maxicount tests in xfs_ialloc_ag_alloc and xfs_dialloc
> don't seem to care about inode32 or not, unless I'm missing something.

See xfs_set_maxicount() and then how it is used in xfs_initialize_perag()
to set up pag->pagi_inodeok, pag->pagf_metadata and mp->m_maxagi which
are used by the allocator....

> How about...
> 
> maxpct=value
> 	This specifies the maximum percentage of space in the
> 	filesystem that can be allocated to  inodes. The
> 	default value is 25% for filesystems under 1TB, 5% for
> 	filesystems under 50TB and 1% for filesystems over 50TB.
> 
> 	In the default inode allocation mode, inode blocks are
> 	chosen such that inode numbers will not exceed 32 bits,
> 	which restricts the inode blocks to the lower portion of
> 	the filesystem.  The data block allocator will avoid these
> 	low blocks to accommodate the specified maxpct, so a high
> 	value may result in a filesystem with nothing but inodes
> 	in a significant portion of the lower blocks of the
> 	filesystem.  (This restriction is not present when
> 	the filesystem is mounted with the "inode64" option on
> 	64-bit platforms).
> 
> 	Setting the value to 0 means that essentially all of the
> 	filesystem can become inode blocks, subject to inode32
> 	restrictions.
> 
> 	This value can be modified with xfs_growfs(8).
> 
> eh... could be better... but how's it sound?

Much better.

Cheers,

Dave.
-- 
Dave Chinner
Principal Engineer
SGI Australian Software Group

Re: [REVIEW] mkfs.xfs man page needs the default settings updated, TAKE 2.

[David Chinner]

On Thu, Mar 06, 2008 at 03:41:29PM +1100, Niv Sardi wrote:
> Thanks to Eric for the comments, is this better ?

Not much of a changelog....


> diff --git a/xfsprogs/man/man8/mkfs.xfs.8 b/xfsprogs/man/man8/mkfs.xfs.8
> index b6024c3..afc284c 100644
> --- a/xfsprogs/man/man8/mkfs.xfs.8
> +++ b/xfsprogs/man/man8/mkfs.xfs.8
> @@ -304,10 +304,16 @@ bits.
>  This specifies the maximum percentage of space in the filesystem that
>  can be allocated to inodes. The default
>  .I value
> -is 25%. Setting the
> +is 25% for filesystems under 1TB, 5% for filesystems under 50TB and 1%
> +for filesystems over 50TB. Setting the
>  .I value
> -to 0 means that essentially all of the filesystem can
> -become inode blocks.
> +to 0 means that essentially all of the filesystem can become inode
> +blocks. Note that this is only used by inode32 (on 32bits platforms),
> +and is ignored on 64bits platforms. On 32 bits platforms, we can only

This is wrong. inode32 is the default on 64 bit platforms as well,
and it matters then as well.

> +use the first TB of disk space for inodes, so the allocator will try

That's not strictly true, either - it depends on inode size; 2k inodes
stratch this to 8TB.

> +to avoid this region, hence miss-using the first AG if this is set to
> +high (the worst case is a 4TB filesystem where a full AG will be
> +untouched by anything but inodes with a 25% maxpct).

No, it doesn't "miss-use" this space - it reserves it for inodes and
metadata and prevents data allocation in those AGs until all other space
is consumed.

Cheers,

Dave.
-- 
Dave Chinner
Principal Engineer
SGI Australian Software Group