On 1/25/25 7:02 AM, Wang Yugui wrote:
Hi,
From: Chuck Lever <chuck.lever@xxxxxxxxxx>
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@xxxxxxxxxx>
---
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@xxxxxxxxxx>
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
