nfsref(8) — Linux manual page

NFSREF(8)                System Manager's Manual               NFSREF(8)

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

DESCRIPTION

       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.

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

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

SEE ALSO

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

AUTHOR

       Chuck Lever <chuck.lever@oracle.com>

COLOPHON

       This page is part of the nfs-utils (NFS utilities) project.
       Information about the project can be found at 
       ⟨http://linux-nfs.org/wiki/index.php/Main_Page⟩.  If you have a
       bug report for this manual page, see
       ⟨http://linux-nfs.org/wiki/index.php/Main_Page⟩.  This page was
       obtained from the project's upstream Git repository
       ⟨git://git.linux-nfs.org/projects/steved/nfs-utils.git⟩ on
       2024-06-14.  (At that time, the date of the most recent commit
       that was found in the repository was 2024-05-10.)  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for
       the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original
       manual page), send a mail to man-pages@man7.org

                               9 Jan 2018                      NFSREF(8)

Pages that refer to this page: nfsref(8)

---