NFS referrals

The following examples provide scenarios to help you understand referrals.

In the following examples, there are four servers:

The server called publications contains documentation files.
The server called projects contains user work directories.
The server called data contains information databases.
The server called account1 is the main NFS server that exports all other files, and is the server that all the clients know about.

Allowing all clients to access files on the main NFS server

Server account1 exports the directory /work to all clients using the following statement in the /etc/exports file:

/work -vers=4

All clients can access the files in the /work remote directory by mounting / from the account1 server onto the /mnt directory using the following command:

mount -o vers=4 account1:/ /mnt

When the user on the client lists the contents of the /mnt directory, they see the remote directory work at the path /mnt/work. The contents of the /mnt/work directory on the client is the same as the contents of the /work directory on the account1 server.

Allowing a client to access files on a specific server

The client user also wants to access the /usr/doc directory on the publications server.

In previous releases, you must export the directory from the server and mount the directory at the client.

Using referrals to build a distributed namespace

You can set up a server so that clients can access the data on other servers without the client knowing where the data is. Only the administrator on the referring server needs to know where the data is. The referring server can redirect clients to the location of the /usr/doc directory using a referral. On the server publications, the /usr/doc directory can be exported by adding the following statement to the export file:

/usr/doc -vers=4

This makes the directories available to NFSv4 clients.

The account1 server can now use referrals to make those directories available to clients by adding the following statement to the export file:

/usr/doc -vers=4,refer=/usr/doc@publications

You then export the directory. At this point, the client that mounted the /mnt directory from the / directory on the account1 server has access to the directory usr when the client lists the /mnt directory. The client does not have to perform any mounts to other servers. The client user does not even need to be aware that the files there are not being provided by the account1 server. For example, you can make the directories of /databases/db on server data and /home/accts on server projects available through account1 by exporting the directories from the data and projects servers, and creating referrals on account1 to those directories.

Because a client user is unaware of the actual location of the data, the administrator can redirect clients from one server to another simply by changing the referral statement in the exports file on the server. The administrator is responsible for the placement and correctness of data that referrals reference with their location specifications.

Administrators should make sure the second server will not refer the request back to the first server, creating a circular referral. In the above example, if the administrator had created a referral on the publications server at /usr/doc that referred to /usr/doc on the account1 server, the resulting circular referral would be undesirable.

Although referrals are created using exportfs, they are different from data exports. Locations specified for referrals should correspond to the root directories of NFSv4-exported file systems. You can create a referral within exported namespaces or in unexported namespaces. In the above example, the /usr/doc referral can be created on the account1 server even if /usr is not exported. This places the referral within the NFSv4 pseudospace. If account1 had exported /usr, the referral export would still have been allowed, in contrast to exporting a directory called doc, which would have failed if it were in the same file system. In either case, the referral export would have failed if a file or directory had existed at /usr/doc. There is no restriction on the number of referrals that can be created within either the server's NFSv4 pseudospace or within an exported file system.

Since a referral does not export any data and only has meaning to the NFSv4 protocol, referrals are available in NSFv4 only. Exporting a referral without the vers=4 option will fail. Although this example only specifies one location, up to 8 locations could have been specified.

Creating a referral creates a special referral object at the location specified by the directory parameter. Since client access to the object is determined by the client's access to the object's parent directory, most other export options have no meaning and are allowed and are ignored. The only exception is the exname option, which will have the expected behavior. For example, if the server creates the referral /n4root/special/users -vers=4,exname=/exported/users,refer=/restricted/users@secrethost, the clients that mount / from that server would see the path /mnt/exported/users, which would redirect the clients to the /restricted/users directory on secrethost. On the exporting server, the referral object would actually be created in the local namespace at /n4root/special/users, so no file or directory can exist there when the export is done. A special object gets created on the server to hold the referral location information. Any directories along the path to the referral will also be created if they do not exist. If the referral is unexported, the referral information will be removed from the object, but the object itself will not be removed. The NSFv4 server will not allow clients to access the resulting stale or orphan referral object. It will return an access error to clients that attempt to access the object. The object can be removed using rm, if desired. A referral can be re-exported with new referral information. This is not recommended as a frequent practice because it can take some time for clients that have accessed the referral to realize that the location information has changed. The server does touch the referral's parent directory to indicate that information in the directory has been changed. This helps the clients to realize that any information that the client has cached about the directory (and the referral within the directory) has changed and needs to be refetched, but there is no guarantee how long it will take for the clients to notice.

For information about using the refer option to change the order of the locations specified in the file system location list, see Reordering the file system location list using the scatter option.