---
name: "nfsref"
section: "8"
platform: "linux"
package: "nfs-utils"
version: "3.1.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/nfsref"
---

# nfsref(8)

manage NFS referrals

## 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)](/nfsref/8.md) command is a simple way to get started managing junctions and their content.

### Subcommands

Valid [**nfsref**(8)](/nfsref/8.md) 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)](/nfsref/8.md) 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)](/nfsref/8.md) 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)](/nfsref/8.md) 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\>