STABLERESTART(5)

✨ STABLERESTART(5) ✨

okay bestie, so this is a page from the File Formats Manual — yes it's literally called STABLERESTART(5), iconic of it — and it's all about the file that keeps your NFSv4 server from being dramatic on restart. let's get into it 💅

---

🌸 NAME 🌸

nfs-stablerestart — the restart info file for the NFSv4 server. that's it, that's the vibe 🫶

---

🎀 SYNOPSIS 🎀

nfs-stablerestart

---

💖 DESCRIPTION 💖

so the nfs-stablerestart file holds the info that lets the NFSv4 server restart without always throwing the NFSERR_NOGRACE error at everyone. this is all described in the NFSv4 server spec, so if you want the receipts: see Network File System (NFS) Version 4 Protocol RFC 3530, Section 8.6.3. no cap 📜

the first record in the file — defined by struct nfsf_rec in /usr/include/fs/nfs/nfsrvstate.h — holds the lease duration of the last incarnation of the server, plus the number of boot times that follows. after that record you get the number of previous boot times that were listed in the first record. the lease duration is what sets the grace period ⏳. the boot times exist to dodge the unlikely situation where a boot time gets reused, which could happen if the TOD clock goes backwards. like, rude. this record, plus the previous boot times with this boot time added in, gets re-written at the end of the grace period. slay 🔁

the rest of the file is appended records, defined by struct nfst_rec in /usr/include/fs/nfs/nfsrvstate.h, and they represent one of two things:

• records saying a client successfully acquired state 👑
• records saying a client's state was revoked 💀

the state revoke records mean that state info for a client got discarded — either because of lease expiry, or because a different client made an otherwise conflicting open or lock request. these records are how you figure out if clients might have hit either of those edge conditions.

and if a client might have hit either edge condition, or if this file is empty or corrupted? the server returns NFSERR_NOGRACE for any reclaim request from that client. no exceptions, bestie 😭

for the server to actually work correctly, you gotta make sure this file is written to stable storage by the time a write op with IO_SYNC specified has returned. that might mean disabling hardware-level caching for the local disk drive holding the file, or something similar. it's giving ✨persistence✨

---

🦋 FILES 🦋

• /var/db/nfs-stablerestart — the NFSv4 stable restart file, main character energy 👑
• /var/db/nfs-stablerestart.bak — backup copy of the file, the supportive bestie 🫶

---

🌈 SEE ALSO 🌈

nfsv4(4), nfsd(8) — go read those too, iykyk 📚

---

💀 BUGS 💀

if the file is empty, the NFSv4 server has literally no choice but to return NFSERR_NOGRACE for all reclaim requests. technically correct? yes. highly undesirable? also yes 😭 so like, please don't lose this file if it's at all possible. the backup copy is maintained and used by nfsd(8) specifically to minimize the risk of that happening. team effort fr fr 🫶

and bestie, listen: to move the file, you have to edit the nfsd sources and recompile it. yes, for real. this was done on purpose to discourage accidental relocation of the file. they really said "not on my watch" 🙈

---

and that's the whole page! version vibes: this one's from Debian, dated April 10, 2011 — vintage but still serving 💅✨🎀