nfsref - manage NFS referrals

       Chuck Lever <chuck.lever@oracle.com>

                                                   9 Jan 2018                                          NFSREF(8)

       A  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.

       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.

       The nfsref(8) command is a simple way to get started managing junctions and their content.

   Subcommands
       Valid nfsref(8) subcommands are:

       add    Adds  junction  information  to the directory named by pathname.  The named directory must already
              exist, and must not already contain junction information.  Regular directory contents are obscured
              to NFS clients by this operation.

              A list of one or more file server and export path pairs is also specified  on  the  command  line.
              When  creating  an  NFS  basic  junction,  this  list  is  stored  in an extended attribute of the
              directory.

              If junction creation is successful, the nfsref(8) command flushes the  kernel's  export  cache  to
              remove previously cached junction information.

       remove Removes  junction  information  from  the  directory  named by pathname.  The named directory must
              exist, and must contain junction information.  Regular directory contents are made visible to  NFS
              clients again by this operation.

              If  junction  deletion  is  successful, the nfsref(8) command flushes the kernel's export cache to
              remove previously cached junction information.

       lookup Displays junction information stored in the directory named by pathname.  The named directory must
              exist, and must contain junction information.

              When looking up an NFS basic junction, the junction information in  the  directory  is  listed  on
              stdout.

   Commandlineoptions-d,--debug
              Enables debugging messages during operation.

       -t,--type=junction-type
              Specifies  the  junction  type for the operation.  Valid values for junction-type are nfs-basic or
              nfs-fedfs.

              For the add subcommand, the default value if this option is not specified is nfs-basic.  The  nfs-fedfs type is not used in this implementation.

              For  the  remove and lookup subcommands, the --type option is not required.  The nfsref(8) command
              operates on whatever junction contents are available.

       Suppose you have two file servers, top.example.net and home.example.net.  You want all  your  clients  to
       mount top.example.net:/ and then see the files under home.example.net:/ automatically in top:/home.

       On top.example.net, you might issue this command as root:

              # mkdir /home
              # nfsref add /home home.example.net /
              Created junction /home.

       NFS version 4 introduces the concept of filesystemreferrals to NFS.

       A  file  system referral is like a symbolic link (or, 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.

       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.

       nfsref - manage NFS referrals

       RFC 8881 for a description of the NFS version 4 referral mechanism

nfsref [-?d] [-ttype]addpathnameserverexport [ serverexport ... ]

       nfsref [-?d] [-ttype]removepathnamenfsref [-?d] [-ttype]lookuppathname