Where would I find background documentation on nfsidmap?

Question

I'm trying to set up an NFSv4 client, and can't find useful documentation.

The manpage for nfsidmap(5) (I'm concerned with CentOS on the client-side, as it happens) describes a particular tool, which is configured in idmapd.conf(5), and which services the request-key upcall from the kernel. Fine.

RFC 7530 describes the underlying protocol, the contents of which which I can look at using tcpdump. It's well-known that NFSv4 does uid/gid management via strings user@domain rather than numeric UID, and thus that there is a need for a mechanism, on both client and server side, to map these names to numbers, as appropriate on the two sides (it's possible to run NFSv4 in a mode which passes numeric IDs back and forth, as strings, but it appears that this is a disrecommended mode). Fine.

Where I'm struggling is finding anything in the middle, which goes into more detail about what's happening; there's nothing I can find which fills in the gap between the protocol and the terse documentation on how to configure a particular tool. I'm trying to do something slightly (very slightly) non-standard – see below – and I'm stuck.

I've found:

• An explanation of why the up-call is happening (this is the sort of thing I'm looking for, but it's too narrow), and the question about ‘which daemon am I talking to?’ where I found this link.
• A question What exactly does nfs4_disable_idmapping parameter do? which is a rather desperate plea, apparently in response to the various one-line ‘randomly tweak this parameter’ answers I've found, which tend to suggest ‘this worked for me’ without much in the way of insight.
• A ‘why do I need idmapd?’ question, to which the answer is not much more than the strings-vs-numbers explanation above.
• There even seems to be disagreement about whether this string-to-uid mapping is obvious good or obviously redundant.
• ...plus a scatter of unanswered questions on Unix/Linux.SE.

(I keep stumbling across apparently rather good documentation on Oracle/Solaris idmapd, but that unfortunately appears to be a very different implementation.)

What I'm specifically trying to do is to configure a number of CentOS clients to make NFSv4 mounts of FreeBSD servers where, crucially, the clients are in a couple of different DNS domains, which (this took me a long while to work out) therefore means that I must configure the client/server ‘NFS domain’ differently from the default (which is to make the NFS domain the same as the DNS domain). The setup works for clients in the same DNS domain as the server, so it's this NFS-domain issue which is the remaining problem.

The apparent answer is to set Domain in /etc/idmapd.conf, restart the nfs-idmapd service, and... nope, mount -tnfs server:/filesystem /mnt works, but ls /mnt produces an IO error. I see in the logs (with idmapd verbosity turned up appropriately)

nfsidmap[5659]: nss_getpwnam: name 'root@<dnsdomain>' domain '<nfsdomain>': resulting localname '(null)'

which means... what? I'm missing the contextual documentation which would allow me to work out what is actually going wrong here. Nor can I find any diagnostic tools which give useful clues – I don't have enough context to fully interpret the output of nfsidmap -l. Even if I did find a combination of idmapd.conf settings and nfs4_disable_idmapping which did what I wanted, I'd remain profoundly uncomfortable that there was more magic here than I understand.

Answer 1

There are two aspects to nfs4 idmapd - the one, when credentials are used to identify requestor and the second one, when file's owner and owner group are shown.

Lets take look at your ls /mnt example or better ls -l /mnt, as usually ls is an alias of ls -l. First of all, the client sends a RPC request with some credentials. In your case, as there was no special mount options, I can assume, that auth sys was used. Thus, on the wire, client will send numeric local uid and gids. Depending on user ids on the server, that can be the same user or an other one.

Now, server got the request and responds with directory listing with file attributes, including owner and group information. Depending on the server implementation, server will either return numeric string or a principal, e.g. "500" or "user@domain". The Linux server will return principal string if:

• client have mounted with sys=krb5/krb5i/krb5p
• nfs4idmapd is enforced by nfs4d_disable_idmapping=0 kernel option.

After receiving the reply from a server, the client have well two possibilities: if string principal provided, call nfs4idmap, or use (actually show) provided numeric id.

If everything is in sync, then you should see a consistent result

$ id
uid=501(kofemann) gid=501(kofemann)
$ touch file
$ ls -l file
-rw-r--r--  1 kofemann  kofemann  0 Jun 13 22:03 file
$

On an other hand, if server returns a wrong principal then you will get unexpected results, like

$ id
uid=501(kofemann) gid=501(kofemann)
$ touch file
$ ls -l file
-rw-r--r--  1 nobody  nobody  0 Jun 13 22:08 file
$

To keep id mapping consistent, client and server either both should use numeric string, or both be configured to use the same nfs domain. Notice, that nfs domain is only a logical namespace of our user base. AFAIK, there are no server or clients that can support multiple domains at the same time, but this is only implementation limitation.

The whole idea of id mapping makes sense when you thing about it with kerberos in mind. Let say you have a client host, which is independent of your user base, for example a laptop, and a server, which has local user base or connected to an LDAP. Your uid on the laptop can be 501 and 1234 on the server. The only shared identity is your kerberos principal user@DOMAIN. The client will map it locally to 501, and server 1234.