Re: [PATCH RFC 4/5] nfsref: Improve nfsref(5)

[Chuck Lever <chuck.lever@oracle.com>]

On 1/25/25 7:02 AM, Wang Yugui wrote:
> Hi,
> 
>> From: Chuck Lever <chuck.lever@oracle.com>
>>
>> Neil Brown says:
>>> ... I found the man page a bit confusing.  It starts off talking about
>>> "referrals", which are suitably defined.  Then drifts into talking about
>>> "junctions" which might be the same thing, but aren't defined.
>>>
>>> The intro suggests that the admin can use "refer=" in /etc/exports, but
>>> doesn't say why they might want to use "nfsref" instead, or how the two
>>> relate.
>>>
>>> Description says "Other administrative commands provide richer access to
>>> junction information." but there are no pointers in "See Also".
>>>
>>> The --type option, we are told, can specify nfs-fedfs but there is no
>>> further mention of this, or any pointers to more info.  Maybe add
>>> "(deprecated)"??
>>
>> Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
>> ---
>>   utils/nfsref/nfsref.man |   60 ++++++++++++++++++++++++-----------------------
>>   1 file changed, 31 insertions(+), 29 deletions(-)
>>
>> diff --git a/utils/nfsref/nfsref.man b/utils/nfsref/nfsref.man
>> index 12615497a404..1970f9dd4144 100644
>> --- a/utils/nfsref/nfsref.man
>> +++ b/utils/nfsref/nfsref.man
>> @@ -53,33 +53,37 @@ nfsref \- manage NFS referrals
>>   NFS version 4 introduces the concept of
>>   .I file system referrals
>>   to NFS.
>> -A file system referral is like a symbolic link on a file server
>> -to another file system share, possibly on another file server.
>> -On an NFS client, a referral behaves like an automounted directory.
>> -The client, under the server's direction, mounts a new NFS export
>> -automatically when an application first accesses that directory.
>>   .P
>> -Referrals are typically used to construct a single file name space
>> -across multiple file servers.
>> -Because file servers control the shape of the name space,
>> -no client configuration is required,
>> -and all clients see the same referral information.
>> +A file system referral is like a symbolic link
>> +(or,
>> +.IR symlink )
>> +to another file system share, typically on another file server.
>> +An NFS client, under the server's direction,
>> +mounts the referred-to NFS export
>> +automatically when an application first accesses it.
>>   .P
>> -The Linux NFS server supports NFS version 4 referrals.
>> -Administrators can specify the
>> -.B refer=
>> -export option in
>> -.I /etc/exports
>> -to configure a list of exports from which the client can choose.
>> -See
>> -.BR exports (5)
>> -for details.
>> +NFSv4 referrals can be used to transparently redirect clients
>> +to file systems that have been moved elsewhere, or
>> +to construct a single file name space across multiple file servers.
>> +Because file servers control the shape of the whole file name space,
>> +no client configuration is required.
>>   .P
>>   .SH DESCRIPTION
>> +A
>> +.I junction
>> +is a file system object on an NFS server that,
>> +when an NFS client encounters it, triggers a referral.
>> +Similar to a symlink, a junction contains one or more target locations
>> +that the server sends to clients in the form of an NFSv4 referral.
>> +.P
>> +On Linux, an existing directory can be converted to a junction
>> +and back atomically and without the loss of the directory contents.
>> +When a directory acts as a junction, it's local content is hidden
>> +from NFSv4 clients.
>> +.P
>>   The
>>   .BR nfsref (8)
>> -command is a simple way to get started managing junction metadata.
>> -Other administrative commands provide richer access to junction information.
>> +command is a simple way to get started managing junctions and their content.
>>   .SS Subcommands
>>   Valid
>>   .BR nfsref (8)
>> @@ -135,6 +139,10 @@ For the
>>   .B add
>>   subcommand, the default value if this option is not specified is
>>   .BR nfs-basic .
>> +The
>> +.B nfs-fedfs
>> +type is not used in this implementation.
>> +.IP
>>   For the
>>   .B remove
>>   and
>> @@ -163,18 +171,12 @@ you might issue this command as root:
>>   .sp
>>   # mkdir /home
>>   .br
>> -# nfsref --type=nfs-basic add /home home.example.net /
>> +# nfsref add /home home.example.net /
>>   .br
>>   Created junction /home.
>>   .sp
>>   .RE
>> -.SH FILES
>> -.TP
>> -.I /etc/exports
>> -NFS server export table
>>   .SH "SEE ALSO"
>> -.BR exports (5)
>> -.sp
>> -RFC 5661 for a description of NFS version 4 referrals
>> +RFC 8881 for a description of the NFS version 4 referral mechanism
>>   .SH "AUTHOR"
>>   Chuck Lever <chuck.lever@oracle.com>
> 
> Very nice info.
> 
> some test result here and then some question.
> 
> nfs client / nfs server: kernel 6.6.74/6.12.11
> nfs-utis: 2.7.1
> 
> test case 1 of refer= (only single refer= in /etc/exports) works well.
> #/etc/exports
> /mnt/test *(rw,async,crossmnt,no_root_squash,refer=/mnt@192.168.2.75)
> 
> test case 2 of refer= (add /mnt to /exports to test crossmnt) faild to work.
> #/etc/exports
> /mnt    *(rw,async,crossmnt,no_root_squash)
> /mnt/test *(rw,async,crossmnt,no_root_squash,refer=/mnt@192.168.2.75)
> 
> test case 1 of nfsref failed to work
> #/etc/exports
> /mnt/test    *(rw,async,crossmnt,no_root_squash)
> # nfsref add /mnt/test 192.168.2.75 /mnt
> # nfsref lookup /mnt/test/
> 192.168.2.75:/mnt
> 
>          NFS port:       2049
>          Valid for:      0
>          Currency:       -1
>          Flags:          varsub(false)
>          GenFlags:       writable(false), going(false), split(true)
>          TransFlags:     rdma(true)
>          Class:          simul(0), handle(0), fileid(0)
>          Class:          writever(0), change(0), readdir(0)
>          Read:           rank(0), order(0)
>          Write:          rank(0), order(0)# mount 192.168.2.74:/mnt  /nfs
> # mount 192.168.2.74:/mnt/test /nfs
> mount.nfs: Stale file handle for (null) on /nfs
> 
> 
> test case 2 of nfsref(crossmnt) failed to work
> #/etc/exports
> /mnt *(rw,async,crossmnt,no_root_squash
> #mount.nfs4 192.168.2.74:/mnt /nfs
> #find /nfs
> find: ‘/nfs/test’: Stale file handle
> 
> Question 1:
> refer= in /exports yet fail to work with crossmnt?
> 
> Question 2:
> nfsref yet fail to work, or we need more setting?

I'm afraid all of this has fallen out of my brain cache a long
time ago. Can you provide a little more context? Can you say
how you expect "crossmnt" to affect the action of a referral?


-- 
Chuck Lever