NFSSVC(2)

💅 NFSSVC(2) — like, the NFS services syscall, bestie

okay so real talk: this is the nfssvc() page from section 2 of the manual (system calls, duh), and it's deep in the NFS lore. grab a matcha, we're going in 🍓

---

✨ NAME ✨

nfssvc — NFS services. yeah. that's the whole name. iconic minimalism 💅

---

📚 LIBRARY 📚

Standard C Library (libc, -lc). the blueprint, the og, the one u link against 🫶

---

🧚 SYNOPSIS 🧚

like, include all of this, no skips:

#include <sys/param.h>
#include <sys/mount.h>
#include <sys/time.h>
#include <nfs/rpcv2.h>
#include <nfsserver/nfs.h>
#include <unistd.h>

int
nfssvc(int flags, void *argstructp);

---

🌸 DESCRIPTION 🌸

so nfssvc() is the syscall that the NFS daemons use to yeet information into and out of the kernel — and also to become a server daemon inside the kernel. main character energy fr 🔥

the flags argument is a bunch of bits that tell the kernel what action to take once you're in there, and argstructp points to one of three structures, depending on which bits are set in flags. three. count 'em. 👑

🦋 client side 🦋

nfsiod(8) calls nfssvc() with flags set to NFSSVC_BIOD and argstructp set to NULL, which enters the kernel as a block I/O server daemon. slay.

for NQNFS, mount_nfs(8) calls nfssvc() with the NFSSVC_MNTD flag — optionally or'd with the flags NFSSVC_GOTAUTH and NFSSVC_AUTHINFAIL — along with a pointer to a:

struct nfsd_cargs {
        char            *ncd_dirp;      /* Mount dir path */
        uid_t           ncd_authuid;    /* Effective uid */
        int             ncd_authtype;   /* Type of authenticator */
        int             ncd_authlen;    /* Length of authenticator string */
        u_char          *ncd_authstr;   /* Authenticator string */
        int             ncd_verflen;    /* and the verifier */
        u_char          *ncd_verfstr;
        NFSKERBKEY_T    ncd_key;        /* Session key */
};

structure. the initial call has only the NFSSVC_MNTD flag set, to specify service for the mount point.

if the mount point is using Kerberos, then the mount_nfs(8) utility will return from nfssvc() with errno == ENEEDAUTH whenever the client side requires an ``rcmd'' authentication ticket for the user. (yes, with the little quotes around rcmd, we're keeping the lore intact 💀)

then mount_nfs(8) will attempt to get the Kerberos ticket, and if it's successful it'll call nfssvc() with the flags NFSSVC_MNTD and NFSSVC_GOTAUTH after filling the ticket into the ncd_authstr field and setting the ncd_authlen and ncd_authtype fields of the nfsd_cargs structure. ✨

and if mount_nfs(8) failed to get the ticket? then nfssvc() gets called with the flags NFSSVC_MNTD, NFSSVC_GOTAUTH and NFSSVC_AUTHINFAIL to denote a failed authentication attempt. sad girl hours 😭

🧊 server side 🧊

on the server side, nfssvc() is called with the flag NFSSVC_NFSD and a pointer to a:

struct nfsd_srvargs {
        struct nfsd     *nsd_nfsd;      /* Pointer to in kernel nfsd struct */
        uid_t           nsd_uid;        /* Effective uid mapped to cred */
        uint32_t        nsd_haddr;      /* Ip address of client */
        struct ucred    nsd_cr;         /* Cred. uid maps to */
        int             nsd_authlen;    /* Length of auth string (ret) */
        u_char          *nsd_authstr;   /* Auth string (ret) */
        int             nsd_verflen;    /* and the verifier */
        u_char          *nsd_verfstr;
        struct timeval  nsd_timestamp;  /* timestamp from verifier */
        uint32_t        nsd_ttl;        /* credential ttl (sec) */
        NFSKERBKEY_T    nsd_key;        /* Session key */
};

to enter the kernel as an nfsd(8) daemon. whenever an nfsd(8) daemon receives a Kerberos authentication ticket, it will return from nfssvc() with errno == ENEEDAUTH. 👀

the nfsd(8) utility will then attempt to authenticate the ticket and generate a set of credentials on the server for the ``user id'' specified in the field nsd_uid. how? by first authenticating the Kerberos ticket, then mapping the Kerberos principal to a local name, and getting a set of credentials for that user via getpwnam(3) and getgrouplist(3). the way that it does like four things in a row, honestly 🎀

if that's successful, the nfsd(8) utility will call nfssvc() with the NFSSVC_NFSD and NFSSVC_AUTHIN flags set, to pass the credential mapping in nsd_cr into the kernel to be cached on the server socket for that client. cute. cached. 🦋

if the authentication failed, nfsd(8) calls nfssvc() with the flags NFSSVC_NFSD and NFSSVC_AUTHINFAIL to denote an authentication failure. no ticket, no vibes. 🙈

👑 and the master daemon 👑

the master nfsd(8) server daemon calls nfssvc() with the flag NFSSVC_ADDSOCK and a pointer to a:

struct nfsd_args {
        int     sock;   /* Socket to serve */
        caddr_t name;   /* Client address for connection based sockets */
        int     namelen;/* Length of name */
};

to pass a server side NFS socket into the kernel for servicing by the nfsd(8) daemons. handing off the aux, literally 💜

---

⭐ RETURN VALUES ⭐

normally nfssvc() does not return — unless the server is terminated by a signal, in which case a value of 0 is returned. otherwise, -1 is returned and the global variable errno is set to specify the error. it's giving "i don't come back unless something dramatic happened" 💀

---

🌈 ERRORS 🌈

• ENEEDAUTH — this special error value is really used for authentication support, particularly Kerberos, as explained above. it's not like the other girls (it's not really an error, but we'll get to that in BUGS 👀).
• EPERM — the caller is not the super-user. sorry bestie, root only 👑

---

🎀 SEE ALSO 🎀

mount_nfs(8), nfsd(8), nfsiod(8) — go read those too, iykyk 🫶

---

🕰️ HISTORY 🕰️

the nfssvc() system call first appeared in 4.4BSD. vintage. antiques roadshow core ✨

---

💀 BUGS 💀

okay so this is the part where the manpage roasts itself:

the nfssvc() system call is designed specifically for the NFS support daemons and as such is specific to their requirements. it should really return values to indicate the need for authentication support, since ENEEDAUTH is not really an error.

and — big one — several fields of the argument structures are assumed to be valid and sometimes to be unchanged from a previous call, such that nfssvc() must be used with extreme care. like, extreme extreme. be so careful. ⚠️

fr fr: this is not a "just call it and see what happens" situation. the kernel is trusting you, and that's a lot of pressure. 🫠

---

and that's the whole page, bestie 💖 this Debian flavor of the NFSSVC(2) manpage is dated June 9, 1993 — genuinely older than most of the internet — so go forth, be careful with ur structs, and remember: ENEEDAUTH is not an error, it's a vibe check. mwah 🎀✨