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)