NFSREF(8)

💖 NFSREF(8) — the nfsref manual, but make it a group chat 💖

okay bestie, sit down, hydrate, and let's talk about nfsref — it lives in the System Manager's Manual section (that's section 8, the big-kid sysadmin section 👑), and it's literally the easiest way to manage NFS referrals. no cap.

---

✨ 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

that's it. three little subcommands. iconic behavior honestly 💅

---

🧚 INTRODUCTION 🧚

so NFS version 4 pulled up with a whole new concept called file system referrals. periodt.

a file system referral is basically like a symbolic link (or, symlink) to another file system share — usually on a totally different file server. and here's the slay part: an NFS client, under the server's direction, mounts the referred-to NFS export automatically the first time an application touches it. no user action. no drama. 🌈

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. and because the file servers control the shape of the whole file name space, no client configuration is required. zero. none. not a single config file. we love to see it 😌

---

💅 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. it's giving "you thought this was a directory but it's actually a portal" 🌀

on Linux, an existing directory can be converted to a junction and back atomically and without the loss of the directory contents. yes bestie, atomic. glow-up and glow-down, no casualties. but heads up: when a directory acts as a junction, its local content is hidden from NFSv4 clients. 🙈

the nfsref(8) command is a simple way to get started managing junctions and their content. it's the beginner-friendly entrance to the junctionverse, and honestly? it ate. 🔥

🎀 Subcommands 🎀

valid nfsref(8) subcommands are, in order:

• 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. 😶‍🌫️ also, you gotta give it a list of one or more file server and export path pairs on the command line. when creating an NFS basic junction, this list is stored in an extended attribute of the directory. and if junction creation is successful, the nfsref(8) command flushes the kernel's export cache to remove previously cached junction information. out with the old ✨
• 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. the hidden stuff comes back out, we're un-hiding it 🫶 and if junction deletion is successful, the nfsref(8) command flushes the kernel's export cache to remove previously cached junction information. same cache flush, different vibe.
• 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. when it's acting up and you need to see the receipts 🔍
• -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. it'll figure it out, she's smart like that 💜

---

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

look at that output. Created junction /home. perfection. no notes. 😭✨

---

🌈 SEE ALSO 🌈

• RFC 8881 for a description of the NFS version 4 referral mechanism — go read it bestie, it's the lore 📚

---

👑 AUTHOR 👑

Chuck Lever <chuck.lever@oracle.com>

---

okay that's the whole page 🎀 it came from the System Manager's Manual, dated 9 Jan 2018, and the page is NFSREF(8) — ty for coming to my ted talk, go make some junctions, drink water, ily 💖🦋✨