NFSDCLTRACK(8)

💅 NFSDCLTRACK(8) — like, the NFSv4 Client Tracking Callout Program, bestie

okay so we're doing nfsdcltrack(8) today and honestly? she's niche but she's important. stay with me 💖

---

✨ NAME ✨

nfsdcltrack — the NFSv4 Client Tracking Callout Program. yes that's her full government name 🎀

---

🦋 SYNOPSIS 🦋

nfsdcltrack [-d] [-f] [-s stable storage dir] <command> <args...>

---

🌸 DESCRIPTION 🌸

okay so nfsdcltrack is the NFSv4 client tracking callout program, periodt. and like — real talk — you literally do not need to install this on machines that aren't acting as NFSv4 servers. so if that's not your vibe, you can scroll past, no cap 🙈

here's the drama tho: when a network partition gets combined with a server reboot, there are these edge conditions (yes, edge conditions, the chaotic ones) that can cause the server to grant lock reclaims even when other clients have taken conflicting locks in the interim. mess. and if you want the full lore, it's described in RFC 3530, section 8.6.3 and in RFC 5661, section 8.4.3. iykyk 📚

so to prevent all that from happening, the server has to track a small amount of per-client information on stable storage. this program? she provides the userspace piece of that whole functionality. when the kernel needs to manipulate the database that stores this info, it will execute this program to handle it. like the kernel literally calls her up and is like "hey bestie, handle this" and she does 🔥

---

💅 OPTIONS 💅

• -d, --debug — turn on debug level logging. she gets chatty 💬
• -f, --foreground — log to stderr instead of syslog. main character energy, no hiding in the syslog shadows ✨
• -s storagedir, --storagedir=storage_dir — the directory where stable storage information should be kept. the default value is /var/lib/nfs/nfsdcltrack 🗂️

---

👑 COMMANDS 👑

nfsdcltrack requires a command for each invocation — like, you can't just show up with no command, she needs direction. supported commands are:

• init — initialize the database. this command requires no argument. easy slay 🎀
• create — create a new client record (or update the timestamp on an existing one). this command requires a hex-encoded nfs_client_id4 as an argument 🌱
• remove — remove a client record from the database. this command requires a hex-encoded nfs_client_id4 as an argument. bye felicia 👋
• check — check to see if a nfs_client_id4 is allowed to reclaim. this command requires a hex-encoded nfs_client_id4 as an argument 🔍
• gracedone — remove any unreclaimed client records from the database. this command requires a epoch boot time as an argument ⏰

---

⚙️ EXTERNAL CONFIGURATION ⚙️

the directory for stable storage information can be set via the file /etc/nfs.conf by setting the storagedir value in the nfsdcltrack section. for example:

[nfsdcltrack]
  storagedir = /shared/nfs/nfsdcltrack

debugging to syslog can also be enabled by setting "debug = 1" in this file. config file girlies stay winning 🫶

---

🧚 LEGACY TRANSITION MECHANISM 🧚

okay so storytime 📖 — the Linux kernel NFSv4 server has historically tracked this information on stable storage by manipulating information on the filesystem directly, in the directory to which /proc/fs/nfsd/nfsv4recoverydir points. and if the kernel passes the correct information, then nfsdcltrack can use it to allow a seamless transition from the old client tracking scheme to the new one. glow-up arc ✨

on a check operation, if there is no record of the client in the database, nfsdcltrack will look to see if the NFSDCLTRACK_LEGACY_RECDIR environment variable is set. if it is, then it will fetch that value and see if a directory exists by that name. if it does, then the check operation will succeed and the directory will be removed 👀

on a gracedone operation, nfsdcltrack will look to see if the NFSDCLTRACK_LEGACY_TOPDIR environment variable is set. if it is, then it will attempt to clean out that directory prior to exiting 🧹

⚠️ warning bestie, fr fr: note that this transition is one-way. if the machine subsequently reboots back into an older kernel that does not support the nfsdcltrack upcall then the clients will not be able to recover their state. no take-backsies, that's the rule 😭

---

📝 NOTES 📝

this program requires a kernel that supports the nfsdcltrack usermodehelper upcall. this support was first added to mainline kernels in 3.8. vintage but valid 💜

---

🌈 AUTHORS 🌈

nfsdcltrack was developed by Jeff Layton <jlayton@redhat.com>. thank you jeff, king behavior 👑💖

---

and that's the whole page bestie! dating all the way back to 2012-10-24, straight out of the NFSDCLTRACK(8) manual. she's been iconic since day one 🎀✨💅