NAME

       nfsref - manage NFS referrals

SYNOPSIS

       nfsref [-?d] [-t type] add pathname server export [ server export ... ]

       nfsref [-?d] [-t type] remove pathname

       nfsref [-?d] [-t type] lookup pathname

INTRODUCTION

       NFS  version  4 introduces the concept of 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.

       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.

       The  Linux  NFS  server  supports  NFS version 4 referrals.  Administrators can specify the refer= export
       option in /etc/exports to configure a list of exports from which the client can choose.   See  exports(5)
       for details.

DESCRIPTION

       The  nfsref(8)  command  is a simple way to get started managing junction metadata.  Other administrative
       commands provide richer access to junction information.

   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.

   Command line options
       -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.  For the
              remove and lookup subcommands, the --type option is not required.  The nfsref(8) command  operates
              on whatever junction contents are available.

EXAMPLES

       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 --type=nfs-basic add /home home.example.net /
              Created junction /home.

FILES

       /etc/exports
              NFS server export table

SEE ALSO

       exports(5)

       RFC 5661 for a description of NFS version 4 referrals

AUTHOR

       Chuck Lever <chuck.lever@oracle.com>

                                                   9 Jan 2018                                          NFSREF(8)