# nfsref

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


* * *