[PATCH RFC 0/5] Possible changes to nfs-utils junction support

[PATCH RFC 0/5] Possible changes to nfs-utils junction support

[Chuck Lever]

Bruce suggested, years ago, that the nfsref command should become
the premier administrative interface for managing NFSD's referral
behavior.

Towards that end, some clean-up is needed for the nfsref command in
nfs-utils, which is presented for review here.

I'm hesitant to introduce more documentation at this time for the
refer= and replica= export options if we plan to remove them in the
medium term.

---

Chuck Lever (5):
      junction: Replace xmlParseMemory
      junction: Remove xmlIndentTreeOutput
      nfsref: Remove unneeded #include in utils/nfsref/nfsref.c
      nfsref: Improve nfsref(5)
      configure: Make --enable-junction=yes the default


 configure.ac            |  6 ++---
 support/junction/xml.c  |  3 +--
 utils/nfsref/nfsref.c   |  2 --
 utils/nfsref/nfsref.man | 60 +++++++++++++++++++++--------------------
 4 files changed, 35 insertions(+), 36 deletions(-)

--
Chuck Lever

[PATCH RFC 1/5] junction: Replace xmlParseMemory

[Chuck Lever]

From: Chuck Lever <chuck.lever@oracle.com>

According to:

https://gnome.pages.gitlab.gnome.org/libxml2/devhelp/libxml2-parser.html#xmlParseMemory

xmlParseMemory() is deprecated. Replace the one call site with a
call to xmlReadMemory().

Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
---
 support/junction/xml.c |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/support/junction/xml.c b/support/junction/xml.c
index 813110b4f308..ec9586528cc9 100644
--- a/support/junction/xml.c
+++ b/support/junction/xml.c
@@ -290,7 +290,7 @@ junction_parse_xml_buf(const char *pathname, const char *name,
 {
 	xmlDocPtr tmp;
 
-	tmp = xmlParseMemory(buf, (int)len);
+	tmp = xmlReadMemory(buf, (int)len, NULL, NULL, 0);
 	if (tmp == NULL) {
 		xlog(D_GENERAL, "Failed to parse XML in %s(%s)\n",
 			pathname, name);

[PATCH RFC 2/5] junction: Remove xmlIndentTreeOutput

[Chuck Lever]

From: Chuck Lever <chuck.lever@oracle.com>

Though it doesn't seem to be marked deprecated, xmlIndentTreeOutput
does not appear in recent versions of libxml2. Since

  xmlIndentTreeOutput = 1;

should be the default behavior now, we can remove this statement
without a behavior change.

Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
---
 support/junction/xml.c |    1 -
 1 file changed, 1 deletion(-)

diff --git a/support/junction/xml.c b/support/junction/xml.c
index ec9586528cc9..aef1cbbd74d3 100644
--- a/support/junction/xml.c
+++ b/support/junction/xml.c
@@ -387,7 +387,6 @@ junction_xml_write(const char *pathname, const char *name, xmlDocPtr doc)
 		return retval;
 
 	retval = FEDFS_ERR_SVRFAULT;
-	xmlIndentTreeOutput = 1;
 	xmlDocDumpFormatMemoryEnc(doc, &buf, &len, "UTF-8", 1);
 	if (len < 0)
 		goto out;

[PATCH RFC 3/5] nfsref: Remove unneeded #include in utils/nfsref/nfsref.c

[Chuck Lever]

From: Chuck Lever <chuck.lever@oracle.com>

Neil Brown says:
> The only thing that was interesting is that nfsref.c includes
> sys/capability.h, and I didn't have libcap declared as BuildRequires.
> The ./configure script didn't complain that libcap was missing - instead
> the build failed.
>
> Other places in nfs-utils that include capability.h protect it with
> #ifdef HAVE_SYS_CAPABILITY_H
>
> If nfsref.c followed that pattern I wouldn't have received an error.
> But then I wouldn't have added a dependency on libcap.
> Do I really want libcap??  I don't know.
> But I cannot see where nfsref.c uses libcap or prctl.  So maybe
> those includes aren't needed.

Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
---
 utils/nfsref/nfsref.c |    2 --
 1 file changed, 2 deletions(-)

diff --git a/utils/nfsref/nfsref.c b/utils/nfsref/nfsref.c
index 7f97d01f55ca..aa8414b425fb 100644
--- a/utils/nfsref/nfsref.c
+++ b/utils/nfsref/nfsref.c
@@ -24,8 +24,6 @@
  */
 
 #include <sys/types.h>
-#include <sys/capability.h>
-#include <sys/prctl.h>
 #include <sys/stat.h>
 
 #include <stdbool.h>

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

[Chuck Lever]

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>

[PATCH RFC 5/5] configure: Make --enable-junction=yes the default

[Chuck Lever]

From: Chuck Lever <chuck.lever@oracle.com>

When I first introduced the nfsref command as part of fedfs-utils,
Bruce suggested that we should adopt nfsref as the mechanism for
managing NFSv4 referrals, over the existing refer= and replica=
export options.

Now that nfsref has been an integral part of nfs-utils for several
years, it's time to take the next step toward that goal: ensure that
the nfsref command (and the appropriate logic inside of mountd) is
built and available by default.

Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
---
 configure.ac |    6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/configure.ac b/configure.ac
index 4ade528d72e8..e95075671571 100644
--- a/configure.ac
+++ b/configure.ac
@@ -175,14 +175,14 @@ else
 fi
 
 AC_ARG_ENABLE(sbin-override,
-	[AS_HELP_STRING([--disable-sbin-override],[Don't force nfsdcltrack and mount helpers into /sbin: always honour --sbindir])],
+	[AS_HELP_STRING([--disable-sbin-override],[Do not force nfsdcltrack and mount helpers into /sbin: always honour --sbindir])],
 	enable_sbin_override=$enableval,
 	enable_sbin_override=yes)
 	AM_CONDITIONAL(CONFIG_SBIN_OVERRIDE, [test "$enable_sbin_override" = "yes"])
 AC_ARG_ENABLE(junction,
-	[AS_HELP_STRING([--enable-junction],[enable support for NFS junctions @<:@default=no@:>@])],
+	[AS_HELP_STRING([--enable-junction],[enable support for NFS junctions @<:@default=yes@:>@])],
 	enable_junction=$enableval,
-	enable_junction=no)
+	enable_junction=yes)
 	if test "$enable_junction" = yes; then
 		AC_DEFINE(HAVE_JUNCTION_SUPPORT, 1,
                           [Define this if you want junction support compiled in])

Re: [PATCH RFC 0/5] Possible changes to nfs-utils junction support

[Chuck Lever III]

> On Nov 20, 2023, at 1:53 PM, Chuck Lever <cel@kernel.org> wrote:
> 
> Bruce suggested, years ago, that the nfsref command should become
> the premier administrative interface for managing NFSD's referral
> behavior.
> 
> Towards that end, some clean-up is needed for the nfsref command in
> nfs-utils, which is presented for review here.

I forgot to mention: the series is marked RFC because they are
compile-tested only.


> I'm hesitant to introduce more documentation at this time for the
> refer= and replica= export options if we plan to remove them in the
> medium term.
> 
> ---
> 
> Chuck Lever (5):
>      junction: Replace xmlParseMemory
>      junction: Remove xmlIndentTreeOutput
>      nfsref: Remove unneeded #include in utils/nfsref/nfsref.c
>      nfsref: Improve nfsref(5)
>      configure: Make --enable-junction=yes the default
> 
> 
> configure.ac            |  6 ++---
> support/junction/xml.c  |  3 +--
> utils/nfsref/nfsref.c   |  2 --
> utils/nfsref/nfsref.man | 60 +++++++++++++++++++++--------------------
> 4 files changed, 35 insertions(+), 36 deletions(-)
> 
> --
> Chuck Lever
> 

--
Chuck Lever

Re: [PATCH RFC 0/5] Possible changes to nfs-utils junction support

[Chuck Lever III]

> On Nov 20, 2023, at 1:58 PM, Chuck Lever III <chuck.lever@oracle.com> wrote:
> 
> 
> 
>> On Nov 20, 2023, at 1:53 PM, Chuck Lever <cel@kernel.org> wrote:
>> 
>> Bruce suggested, years ago, that the nfsref command should become
>> the premier administrative interface for managing NFSD's referral
>> behavior.
>> 
>> Towards that end, some clean-up is needed for the nfsref command in
>> nfs-utils, which is presented for review here.
> 
> I forgot to mention: the series is marked RFC because they are
> compile-tested only.

I've done some limited testing now. These seem to work.


>> I'm hesitant to introduce more documentation at this time for the
>> refer= and replica= export options if we plan to remove them in the
>> medium term.
>> 
>> ---
>> 
>> Chuck Lever (5):
>>     junction: Replace xmlParseMemory
>>     junction: Remove xmlIndentTreeOutput
>>     nfsref: Remove unneeded #include in utils/nfsref/nfsref.c
>>     nfsref: Improve nfsref(5)
>>     configure: Make --enable-junction=yes the default
>> 
>> 
>> configure.ac            |  6 ++---
>> support/junction/xml.c  |  3 +--
>> utils/nfsref/nfsref.c   |  2 --
>> utils/nfsref/nfsref.man | 60 +++++++++++++++++++++--------------------
>> 4 files changed, 35 insertions(+), 36 deletions(-)
>> 
>> --
>> Chuck Lever
>> 
> 
> --
> Chuck Lever
> 
> 

--
Chuck Lever

Re: [PATCH RFC 0/5] Possible changes to nfs-utils junction support

[Steve Dickson]

On 11/20/23 1:53 PM, Chuck Lever wrote:
> Bruce suggested, years ago, that the nfsref command should become
> the premier administrative interface for managing NFSD's referral
> behavior.
> 
> Towards that end, some clean-up is needed for the nfsref command in
> nfs-utils, which is presented for review here.
> 
> I'm hesitant to introduce more documentation at this time for the
> refer= and replica= export options if we plan to remove them in the
> medium term.
> 
> ---
> 
> Chuck Lever (5):
>        junction: Replace xmlParseMemory
>        junction: Remove xmlIndentTreeOutput
>        nfsref: Remove unneeded #include in utils/nfsref/nfsref.c
>        nfsref: Improve nfsref(5)
>        configure: Make --enable-junction=yes the default
> 
> 
>   configure.ac            |  6 ++---
>   support/junction/xml.c  |  3 +--
>   utils/nfsref/nfsref.c   |  2 --
>   utils/nfsref/nfsref.man | 60 +++++++++++++++++++++--------------------
>   4 files changed, 35 insertions(+), 36 deletions(-)
> 
> --
> Chuck Lever
> 
Committed... (tag: nfs-utils-2-7-1-rc2)

steved.

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

[Chuck Lever]

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