NFSDCLD(8)

💖 NFSDCLD(8) — the nfsdcld bestie handbook 💖

okay so listen, this is the manual page for nfsdcld(8), aka the NFSv4 Client Tracking Daemon, and bestie it's giving "quietly holding the whole server together" energy and I am obsessed. 🫶

---

✨ NAME ✨

nfsdcld — the NFSv4 Client Tracking Daemon. that's it, that's the name, she's straightforward and she ate. 💅

---

🌸 SYNOPSIS 🌸

nfsdcld [-d] [-F] [-p path] [-s stable storage dir]

look at her, four little flags, no drama. 🎀

---

🦋 DESCRIPTION 🦋

so nfsdcld is the NFSv4 client tracking daemon. and like, real talk — you do not need to run this on machines that aren't acting as NFSv4 servers. if your box isn't an NFSv4 server, this is not your moment, and that's okay, we respect it. 🙈

here's the drama it prevents, and ngl it's kind of a horror story: when a network partition happens combined with a server reboot, there are edge conditions that can cause the server to grant lock reclaims when other clients have taken conflicting locks in the interim. yes, that's as messy as it sounds. 😭 if you want the full deep dive, it's described in RFC 3530, section 8.6.3 — go read it, I'll wait.

to stop all that from happening, the server has to track a small amount of per-client information on stable storage. and this daemon right here? she's the userspace piece of that whole functionality. main character energy, truly. 👑

---

💅 OPTIONS 💅

• -d, --debug — turns on debug level logging. she gets chatty. 🗣️
• -F, --foreground — runs the daemon in the foreground and prints all output to stderr. no hiding, we're being transparent about it. ✨
• *-p *path, --pipefsdir=path — where the rpc_pipefs filesystem lives. the default value is /var/lib/nfs/rpc_pipefs.
• *-s *storage_dir, --storagedir=storage_dir — the directory where stable storage information should be kept. the default value is /var/lib/nfs/nfsdcld.

---

🎀 CONFIGURATION FILE 🎀

these values are recognized in the [nfsdcld] section of the /etc/nfs.conf configuration file:

• storagedir — equivalent to -s/--storagedir. same vibe, different font. 🍓
• debug — setting "debug = 1" is equivalent to -d/--debug. yep, just like that.

and additionally, this next one is recognized from the [general] section:

• pipefs-directory — equivalent to -p/--pipefsdir. it lives over in general, she's a social butterfly. 🦋

---

⭐ NOTES ⭐

okay this part is the lore drop, sit down, hydrate. 🧚

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. old school. manual. unhinged. 💀

this changed with the original introduction of the nfsdcld upcall in kernel version 3.4, which was later deprecated in favor of the nfsdcltrack(8) usermodehelper program — support for that one was added in kernel version 3.8. however — and this is the plot twist — since the usermodehelper upcall does not work in containers, support for a new version of the nfsdcld upcall was added in kernel version 5.2. we love a comeback arc. 🔥

this daemon requires a kernel that supports the nfsdcld upcall. on older kernels, if the legacy client name tracking code was in use, then the kernel would not create the pipe that nfsdcld uses to talk to the kernel. on newer kernels, nfsd attempts to initialize client tracking in this exact order:

1. first, the nfsdcld upcall.
2. second, the nfsdcltrack usermodehelper upcall.
3. finally, the legacy client tracking.

this daemon should be run as root, because the pipe it uses to communicate with the kernel is only accessible by root. 🫡 and then — plot twist again — the daemon does drop all superuser capabilities after starting. so because of that, the storagedir should be owned by root, and be readable and writable by owner. write that down. ✍️

the daemon now supports different upcall versions, which lets the kernel pass additional data to be stored in the on-disk database. the kernel will query the supported upcall version from nfsdcld during client tracking initialization.

here's the upgrade/downgrade tea, and it matters:

• a restart of nfsd is not necessary after upgrading nfsdcld — however, nfsd will not use a later upcall version until restart.
• a restart of nfsd is necessary after downgrading nfsdcld, to ensure that nfsd does not use an upcall version that nfsdcld does not support.

🚨 and additionally: a downgrade of nfsdcld requires the schema of the on-disk database to be downgraded as well. that can be accomplished using the nfsdclddb(8) utility. do not skip this step bestie, I'm begging. 😭

---

🌈 FILES 🌈

• /var/lib/nfs/nfsdcld/main.sqlite

---

👑 SEE ALSO 👑

• nfsdcltrack(8)
• nfsdclddb(8)

---

💜 AUTHORS 💜

the nfsdcld daemon was developed by Jeff Layton <jlayton@redhat.com> with modifications from Scott Mayhew <smayhew@redhat.com>. legends, both of them, no cap. 🫶

---

and that's the whole page, babe — this version is dated 2011-12-21 and it comes to you from the NFSDCLD(8) manual, so if you ever need to cite your sources, you know exactly where she lives. go forth and track those clients. 💖✨