Manual page bug: two inaccuracies in nfsd(7)

Manual page bug: two inaccuracies in nfsd(7)

[Chris Siebenmann]

 I was recently reading this manual page as part of exploring running
an NFS server on Ubuntu 16.04 (with Ubuntu's kernel '4.4.0') and found
two inaccuracies with the current state of the kernel (or at least how
it looks to me based on both experimentation and code).

 First, there is no /proc/net/rpc/auth.domain directory and cache any
more. This was removed from the kernel in 2006 (in commit efc36aa5608f),
so I think it should be safe to remove from current versions of the
manpage.

 Second, the manpage says about the 'flush' files to be found in eg
/proc/net/rpc/auth.unix.ip:

	When a number of seconds since epoch (1 Jan 1970) is written to
	this file, all entries in the cache that were last updated before
	that file become invalidated and will be flushed out. Writing
	1 will flush everything. [...]

The bit about 'writing 1 will flush everything' does not appear to be
accurate. Experimentally, writing 1 does not work (it flushes nothing),
and in the current kernel code there is no special handling for a write of
'1' to the "flush" files in net/sunrpc/cache.c's write_flush() function,
which I believe is where this is implemented. Based on the implementation,
the only way to flush everything is to write a time in the future to
"flush".

 Based on looking at the kernel logs and code diffs, this may have
changed in commit 778620364ef5, 'sunrpc/cache: make cache flushing more
reliable', which gitk tells me came between v4.3-rc3 and v4.4-rc1 (it
was made in October 2015). The commit description definitely talks about
changing how cache expiry works, and it touches write_flush() et al in
various ways. This may call for a kernel change to make it work again,
but even if so I would suggest that the manpage be updated to reflect
that writing 1 doesn't work in a range of kernel versions (some of which
will be in the field for years to come, eg Ubuntu 16.04 LTS).

	- cks

Re: Manual page bug: two inaccuracies in nfsd(7)

[NeilBrown]

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

On Fri, Feb 10 2017, Chris Siebenmann wrote:

>  I was recently reading this manual page as part of exploring running
> an NFS server on Ubuntu 16.04 (with Ubuntu's kernel '4.4.0') and found
> two inaccuracies with the current state of the kernel (or at least how
> it looks to me based on both experimentation and code).
>
>  First, there is no /proc/net/rpc/auth.domain directory and cache any
> more. This was removed from the kernel in 2006 (in commit efc36aa5608f),
> so I think it should be safe to remove from current versions of the
> manpage.

I agree.

>
>  Second, the manpage says about the 'flush' files to be found in eg
> /proc/net/rpc/auth.unix.ip:
>
> 	When a number of seconds since epoch (1 Jan 1970) is written to
> 	this file, all entries in the cache that were last updated before
> 	that file become invalidated and will be flushed out. Writing
> 	1 will flush everything. [...]
>
> The bit about 'writing 1 will flush everything' does not appear to be
> accurate.

I was never accurate.  I vaguely remember writing it.  I must have been
confused.

Would you be able to create a patch which fixes these issues, and post
it, with a signed-off-by ?

Thanks,
NeilBrown



>            Experimentally, writing 1 does not work (it flushes nothing),
> and in the current kernel code there is no special handling for a write of
> '1' to the "flush" files in net/sunrpc/cache.c's write_flush() function,
> which I believe is where this is implemented. Based on the implementation,
> the only way to flush everything is to write a time in the future to
> "flush".
>
>  Based on looking at the kernel logs and code diffs, this may have
> changed in commit 778620364ef5, 'sunrpc/cache: make cache flushing more
> reliable', which gitk tells me came between v4.3-rc3 and v4.4-rc1 (it
> was made in October 2015). The commit description definitely talks about
> changing how cache expiry works, and it touches write_flush() et al in
> various ways. This may call for a kernel change to make it work again,
> but even if so I would suggest that the manpage be updated to reflect
> that writing 1 doesn't work in a range of kernel versions (some of which
> will be in the field for years to come, eg Ubuntu 16.04 LTS).
>
> 	- cks
> --
> To unsubscribe from this list: send the line "unsubscribe linux-nfs" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: Manual page bug: two inaccuracies in nfsd(7)

[Chris Siebenmann]

> >  I was recently reading this manual page as part of exploring running
> > an NFS server on Ubuntu 16.04 (with Ubuntu's kernel '4.4.0') and found
> > two inaccuracies with the current state of the kernel (or at least how
> > it looks to me based on both experimentation and code).
> >
> >  First, there is no /proc/net/rpc/auth.domain directory and cache any
> > more. This was removed from the kernel in 2006 (in commit efc36aa5608f),
> > so I think it should be safe to remove from current versions of the
> > manpage.
> 
> I agree.
> 
> >
> >  Second, the manpage says about the 'flush' files to be found in eg
> > /proc/net/rpc/auth.unix.ip:
> >
> > 	When a number of seconds since epoch (1 Jan 1970) is written to
> > 	this file, all entries in the cache that were last updated before
> > 	that file become invalidated and will be flushed out. Writing
> > 	1 will flush everything. [...]
> >
> > The bit about 'writing 1 will flush everything' does not appear to be
> > accurate.
> 
> I was never accurate.  I vaguely remember writing it.  I must have been
> confused.
> 
> Would you be able to create a patch which fixes these issues, and post
> it, with a signed-off-by ?

 Here is a patch that deletes the mention of auth.domain and changes the
wording around 'flush' files. I'm not attached to the revised wording;
it's just the best I could manage in something that felt that it was
within the same style and space as the current wording.

Signed-off-by: Chris Siebenmann <cks.nfs01@cs.toronto.edu>

diff --git a/utils/exportfs/nfsd.man b/utils/exportfs/nfsd.man
index 0c516fa..9efa29f 100644
--- a/utils/exportfs/nfsd.man
+++ b/utils/exportfs/nfsd.man
@@ -105,11 +105,6 @@ clients have for different filesystems.
 The caches are:
 
 .TP
-.B auth.domain
-This cache maps the name of a client (or domain) to an internal data
-structure.  The only access that is possible is to flush the cache.
-
-.TP
 .B auth.unix.ip
 This cache contains a mapping from IP address to the name of the
 authentication domain that the ipaddress should be treated as part of.
@@ -133,7 +128,8 @@ are:
 .B flush
 When a number of seconds since epoch (1 Jan 1970) is written to this
 file, all entries in the cache that were last updated before that file
-become invalidated and will be flushed out.  Writing 1 will flush
+become invalidated and will be flushed out.  Writing a time in the
+future (in seconds since epoch) will flush
 everything.  This is the only file that will always be present.
 
 .TP


	- cks

Re: Manual page bug: two inaccuracies in nfsd(7)

[NeilBrown]

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

On Thu, Feb 23 2017, Chris Siebenmann wrote:

>> >  I was recently reading this manual page as part of exploring running
>> > an NFS server on Ubuntu 16.04 (with Ubuntu's kernel '4.4.0') and found
>> > two inaccuracies with the current state of the kernel (or at least how
>> > it looks to me based on both experimentation and code).
>> >
>> >  First, there is no /proc/net/rpc/auth.domain directory and cache any
>> > more. This was removed from the kernel in 2006 (in commit efc36aa5608f),
>> > so I think it should be safe to remove from current versions of the
>> > manpage.
>> 
>> I agree.
>> 
>> >
>> >  Second, the manpage says about the 'flush' files to be found in eg
>> > /proc/net/rpc/auth.unix.ip:
>> >
>> > 	When a number of seconds since epoch (1 Jan 1970) is written to
>> > 	this file, all entries in the cache that were last updated before
>> > 	that file become invalidated and will be flushed out. Writing
>> > 	1 will flush everything. [...]
>> >
>> > The bit about 'writing 1 will flush everything' does not appear to be
>> > accurate.
>> 
>> I was never accurate.  I vaguely remember writing it.  I must have been
>> confused.
>> 
>> Would you be able to create a patch which fixes these issues, and post
>> it, with a signed-off-by ?
>
>  Here is a patch that deletes the mention of auth.domain and changes the
> wording around 'flush' files. I'm not attached to the revised wording;
> it's just the best I could manage in something that felt that it was
> within the same style and space as the current wording.
>
> Signed-off-by: Chris Siebenmann <cks.nfs01@cs.toronto.edu>

Thanks.
Acked-by: NeilBrown <neilb@suse.com>

hopefully Steve will pick this up in due course.  He tends to apply
patches in batches every few weeks.

Thanks,
NeilBrown

>
> diff --git a/utils/exportfs/nfsd.man b/utils/exportfs/nfsd.man
> index 0c516fa..9efa29f 100644
> --- a/utils/exportfs/nfsd.man
> +++ b/utils/exportfs/nfsd.man
> @@ -105,11 +105,6 @@ clients have for different filesystems.
>  The caches are:
>  
>  .TP
> -.B auth.domain
> -This cache maps the name of a client (or domain) to an internal data
> -structure.  The only access that is possible is to flush the cache.
> -
> -.TP
>  .B auth.unix.ip
>  This cache contains a mapping from IP address to the name of the
>  authentication domain that the ipaddress should be treated as part of.
> @@ -133,7 +128,8 @@ are:
>  .B flush
>  When a number of seconds since epoch (1 Jan 1970) is written to this
>  file, all entries in the cache that were last updated before that file
> -become invalidated and will be flushed out.  Writing 1 will flush
> +become invalidated and will be flushed out.  Writing a time in the
> +future (in seconds since epoch) will flush
>  everything.  This is the only file that will always be present.
>  
>  .TP
>
>
> 	- cks
> --
> To unsubscribe from this list: send the line "unsubscribe linux-nfs" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: Manual page bug: two inaccuracies in nfsd(7)

[Steve Dickson]

On 03/02/2017 06:28 PM, NeilBrown wrote:
> On Thu, Feb 23 2017, Chris Siebenmann wrote:
> 
>>>>  I was recently reading this manual page as part of exploring running
>>>> an NFS server on Ubuntu 16.04 (with Ubuntu's kernel '4.4.0') and found
>>>> two inaccuracies with the current state of the kernel (or at least how
>>>> it looks to me based on both experimentation and code).
>>>>
>>>>  First, there is no /proc/net/rpc/auth.domain directory and cache any
>>>> more. This was removed from the kernel in 2006 (in commit efc36aa5608f),
>>>> so I think it should be safe to remove from current versions of the
>>>> manpage.
>>>
>>> I agree.
>>>
>>>>
>>>>  Second, the manpage says about the 'flush' files to be found in eg
>>>> /proc/net/rpc/auth.unix.ip:
>>>>
>>>> 	When a number of seconds since epoch (1 Jan 1970) is written to
>>>> 	this file, all entries in the cache that were last updated before
>>>> 	that file become invalidated and will be flushed out. Writing
>>>> 	1 will flush everything. [...]
>>>>
>>>> The bit about 'writing 1 will flush everything' does not appear to be
>>>> accurate.
>>>
>>> I was never accurate.  I vaguely remember writing it.  I must have been
>>> confused.
>>>
>>> Would you be able to create a patch which fixes these issues, and post
>>> it, with a signed-off-by ?
>>
>>  Here is a patch that deletes the mention of auth.domain and changes the
>> wording around 'flush' files. I'm not attached to the revised wording;
>> it's just the best I could manage in something that felt that it was
>> within the same style and space as the current wording.
>>
>> Signed-off-by: Chris Siebenmann <cks.nfs01@cs.toronto.edu>
> 
> Thanks.
> Acked-by: NeilBrown <neilb@suse.com>
> 
> hopefully Steve will pick this up in due course.  He tends to apply
> patches in batches every few weeks.
Sorry for the delay... I just saw this... inline patches like
this sometime simple through my patch filters... ;-)

Committed!

steved.

> 
> Thanks,
> NeilBrown
> 
>>
>> diff --git a/utils/exportfs/nfsd.man b/utils/exportfs/nfsd.man
>> index 0c516fa..9efa29f 100644
>> --- a/utils/exportfs/nfsd.man
>> +++ b/utils/exportfs/nfsd.man
>> @@ -105,11 +105,6 @@ clients have for different filesystems.
>>  The caches are:
>>  
>>  .TP
>> -.B auth.domain
>> -This cache maps the name of a client (or domain) to an internal data
>> -structure.  The only access that is possible is to flush the cache.
>> -
>> -.TP
>>  .B auth.unix.ip
>>  This cache contains a mapping from IP address to the name of the
>>  authentication domain that the ipaddress should be treated as part of.
>> @@ -133,7 +128,8 @@ are:
>>  .B flush
>>  When a number of seconds since epoch (1 Jan 1970) is written to this
>>  file, all entries in the cache that were last updated before that file
>> -become invalidated and will be flushed out.  Writing 1 will flush
>> +become invalidated and will be flushed out.  Writing a time in the
>> +future (in seconds since epoch) will flush
>>  everything.  This is the only file that will always be present.
>>  
>>  .TP
>>
>>
>> 	- cks
>> --
>> To unsubscribe from this list: send the line "unsubscribe linux-nfs" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html