nfsidmap(8)

💖 nfsidmap(8) — the NFS idmapper upcall program 💖

okay bestie, sit down, hydrate, and let's talk about nfsidmap — it's a System Manager's Manual situation and honestly it's giving "quietly holding your entire NFSv4 mount together" energy. 🫶

---

✨ NAME ✨

nfsidmap — the NFS idmapper upcall program. literally that's her whole job title. 💅

---

🌸 SYNOPSIS 🌸

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

six whole moods. pick your vibe. ⭐

---

🦋 DESCRIPTION 🦋

So. The NFSv4 protocol does NOT put your local system's UID and GID values on the wire as numbers, bestie. It sends them as strings that look like user@domain. And the whole process of translating from UID → string and string → UID? That's called "ID mapping." periodt.

The system gets the user part of that string by doing a password or group lookup. And where does the lookup mechanism live? It's configured in /etc/idmapd.conf. 🎀

By default, the domain part of the string is just the system's DNS domain name. BUT — and this is the lowkey important part — you can also specify it in /etc/idmapd.conf if your system is multi-homed, or if your system's DNS domain name doesn't match the name of your system's Kerberos realm. 🙈

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, that's what gets used as the domain. If the record doesn't exist, then the domain part of the DNS domain gets used. no cap. 🧚

Now the main character: the /usr/sbin/nfsidmap program performs 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 information. Then the kernel caches the translation results in that key. teamwork! 👑

nfsidmap can also clear cached ID map results in the kernel, or revoke one particular key. And why do we care? Because an incorrect cached key can result in file and directory ownership reverting to "nobody" on NFSv4 mount points. which is... the villain origin story of your afternoon. 💀

Plus, the -d and -l options are there to help diagnose misconfigurations. They have no effect on the keyring containing ID mapping results — they're just here to snoop and tell you the truth. 🌈

---

💅 OPTIONS 💅

• -c — Clear the keyring of all the keys. bye bye everything 👋
• -d — Display the system's effective NFSv4 domain name on stdout.
• -g user — Revoke the gid key of the given user.
• -h — Display usage message.
• -l — Display on stdout all keys currently in the keyring used to cache ID mapping results. Heads up bestie: these keys are visible only to the superuser. 🔐
• -r user — Revoke both the uid and gid key of the given user. both. at once. ruthless.
• -t timeout — Set the expiration timer, in seconds, on the key. The default is 600 seconds (10 mins). ⏰
• -u user — Revoke the uid key of the given user.
• -v — Increases the verbosity of the output to syslog (can be specified multiple times). say it louder for the syslog 📢

---

🎀 CONFIGURING 🎀

Okay so here's the setup part, and it's not optional, it's necessary. 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. Iconic behavior honestly. So if you would like to use your own program for a uid lookup, then you would 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. order matters, bestie, always. ⭐

---

🍓 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>

---

and that's the whole page, bestie!! 🫶 this one is from the System Manager's Manual, dated 1 October 2010, and it's the nfsidmap(8) manual page — go forth and map those IDs, you absolute legend. 💖✨🎀🦋🌸