nfsidmap(5)

💖 nfsidmap 💖 — The NFS idmapper upcall program

(that's section 5, File Formats Manual, bestie — yes we're in the file formats girlies now)

---

✨ NAME ✨

nfsidmap — the NFS idmapper upcall program 🫶

---

🦋 SYNOPSIS 🦋

nfsidmap [-v] [-t timeout] key desc
nfsidmap [-v] [-c]
nfsidmap [-v] [-u|-g|-r user]
nfsidmap -d
nfsidmap -l
nfsidmap -h

---

🌸 DESCRIPTION 🌸

okay so. The NFSv4 protocol doesn't put your local system's UID and GID values on the wire as numbers — it sends them as strings that look like user@domain. The whole glow-up of turning UID → string and string → UID is literally called "ID mapping." iconic behaviour honestly.

The system figures out the user part of that string by doing a password or group lookup. And where does it learn how to do that lookup? /etc/idmapd.conf, obviously. 💅

By default, the domain part of the string is just the system's DNS domain name. But you can also set it in /etc/idmapd.conf if your system is multi-homed, or if your system's DNS domain name does not match the name of your system's Kerberos realm. (we've all been there.)

When the domain is not specified in /etc/idmapd.conf, the local DNS server gets queried for the _nfsv4idmapdomain text record. If that record exists, bestie, that's your domain. When the record does not exist, the domain part of the DNS domain gets used instead.

The /usr/sbin/nfsidmap program does the translations on behalf of the kernel. The kernel uses the request-key mechanism to perform an upcall. So /usr/sbin/nfsidmap gets invoked by /sbin/request-key, does the translation, and initializes a key with the resulting info. Then the kernel caches those translation results in the key. teamwork!! 🤝

nfsidmap can also clear cached ID map results in the kernel, or revoke one particular key. And heads up — an incorrect cached key can result in file and directory ownership reverting to "nobody" on NFSv4 mount points. not the vibe. 😭

Plus, the -d and -l options are there to help you diagnose misconfigurations. They have no effect on the keyring containing ID mapping results, so they're purely your little diagnostic besties.

---

👑 OPTIONS 👑

• -c — Clear the keyring of all the keys. spring cleaning, but make it keys ✨
• -d — Display the system's effective NFSv4 domain name on stdout. show me the domain bestie
• -g user — Revoke the gid key of the given user.
• -h — Display usage message. (the classic "help me help you" moment)
• -l — Display on stdout all keys currently in the keyring used to cache ID mapping results. These keys are visible only to the superuser. 👑 superuser-only content fr fr
• -r user — Revoke both the uid and gid key of the given user. two for one, we love a bundle
• -t timeout — Set the expiration timer, in seconds, on the key. The default is 600 seconds (10 mins). ticking clock energy ⏰
• -u user — Revoke the uid key of the given user.
• -v — Increases the verbosity of the output to syslog (can be specified multiple times). stack them if you're nosy 💅

---

🎀 CONFIGURING 🎀

The file /etc/idmapd.conf... no wait, the file /etc/request-key.conf will need to be modified so /sbin/request-key can properly direct the upcall. The following line should be added before a call to keyctl negate:

create    id_resolver    *    *    /usr/sbin/nfsidmap -t 600 %k %d

This will direct all id_resolver requests to the program /usr/sbin/nfsidmap. The -t 600 defines how many seconds into the future the key will expire. This is an optional parameter for /usr/sbin/nfsidmap and will default to 600 seconds when not specified.

The idmapper system uses four key descriptions:

uid: Find the UID for the given user
gid: Find the GID for the given group
user: Find the user name for the given UID
group: Find the group name for the given GID

You can choose to handle any of these individually, rather than using the generic upcall program. So say you'd like to use your own program for a uid lookup — you'd edit your request-key.conf so it looks similar to this:

create    id_resolver    uid:*     *    /some/other/program %k %d
create    id_resolver    *         *    /usr/sbin/nfsidmap %k %d

Notice that the new line was added above the line for the generic program. request-key will find the first matching line and run the corresponding program. In this case, /some/other/program will handle all uid lookups, and /usr/sbin/nfsidmap will handle gid, user, and group lookups. first come, first served, periodt. 🍓

---

🧚 FILES 🧚

• /etc/idmapd.conf — ID mapping configuration file
• /etc/request-key.conf — Request key configuration file

---

🌈 SEE ALSO 🌈

idmapd.conf(5), request-key(8)

---

💜 AUTHOR 💜

Bryan Schumaker, <bjschuma@netapp.com>

---

okay that's the whole thing bestie, you ate that 🫶 this was the nfsidmap(5) page, dated 1 October 2010 — so if you're reading this in the future, yes it's giving vintage and it's still iconic. mwah 💅✨