| 1 |
============= |
| 2 |
NFS ID Mapper |
| 3 |
============= |
| 4 |
|
| 5 |
Id mapper is used by NFS to translate user and group ids into names, and to |
| 6 |
translate user and group names into ids. Part of this translation involves |
| 7 |
performing an upcall to userspace to request the information. There are two |
| 8 |
ways NFS could obtain this information: placing a call to /sbin/request-key |
| 9 |
or by placing a call to the rpc.idmap daemon. |
| 10 |
|
| 11 |
NFS will attempt to call /sbin/request-key first. If this succeeds, the |
| 12 |
result will be cached using the generic request-key cache. This call should |
| 13 |
only fail if /etc/request-key.conf is not configured for the id_resolver key |
| 14 |
type, see the "Configuring" section below if you wish to use the request-key |
| 15 |
method. |
| 16 |
|
| 17 |
If the call to /sbin/request-key fails (if /etc/request-key.conf is not |
| 18 |
configured with the id_resolver key type), then the idmapper will ask the |
| 19 |
legacy rpc.idmap daemon for the id mapping. This result will be stored |
| 20 |
in a custom NFS idmap cache. |
| 21 |
|
| 22 |
|
| 23 |
Configuring |
| 24 |
=========== |
| 25 |
|
| 26 |
The file /etc/request-key.conf will need to be modified so /sbin/request-key can |
| 27 |
direct the upcall. The following line should be added: |
| 28 |
|
| 29 |
``#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ...`` |
| 30 |
``#====== ======= =============== =============== ===============================`` |
| 31 |
``create id_resolver * * /usr/sbin/nfs.idmap %k %d 600`` |
| 32 |
|
| 33 |
|
| 34 |
This will direct all id_resolver requests to the program /usr/sbin/nfs.idmap. |
| 35 |
The last parameter, 600, defines how many seconds into the future the key will |
| 36 |
expire. This parameter is optional for /usr/sbin/nfs.idmap. When the timeout |
| 37 |
is not specified, nfs.idmap will default to 600 seconds. |
| 38 |
|
| 39 |
id mapper uses for key descriptions:: |
| 40 |
|
| 41 |
uid: Find the UID for the given user |
| 42 |
gid: Find the GID for the given group |
| 43 |
user: Find the user name for the given UID |
| 44 |
group: Find the group name for the given GID |
| 45 |
|
| 46 |
You can handle any of these individually, rather than using the generic upcall |
| 47 |
program. If you would like to use your own program for a uid lookup then you |
| 48 |
would edit your request-key.conf so it look similar to this: |
| 49 |
|
| 50 |
``#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ...`` |
| 51 |
``#====== ======= =============== =============== ===============================`` |
| 52 |
``create id_resolver uid:* * /some/other/program %k %d 600`` |
| 53 |
``create id_resolver * * /usr/sbin/nfs.idmap %k %d 600`` |
| 54 |
|
| 55 |
|
| 56 |
Notice that the new line was added above the line for the generic program. |
| 57 |
request-key will find the first matching line and corresponding program. In |
| 58 |
this case, /some/other/program will handle all uid lookups and |
| 59 |
/usr/sbin/nfs.idmap will handle gid, user, and group lookups. |
| 60 |
|
| 61 |
See Documentation/security/keys/request-key.rst for more information |
| 62 |
about the request-key function. |
| 63 |
|
| 64 |
|
| 65 |
nfs.idmap |
| 66 |
========= |
| 67 |
|
| 68 |
nfs.idmap is designed to be called by request-key, and should not be run "by |
| 69 |
hand". This program takes two arguments, a serialized key and a key |
| 70 |
description. The serialized key is first converted into a key_serial_t, and |
| 71 |
then passed as an argument to keyctl_instantiate (both are part of keyutils.h). |
| 72 |
|
| 73 |
The actual lookups are performed by functions found in nfsidmap.h. nfs.idmap |
| 74 |
determines the correct function to call by looking at the first part of the |
| 75 |
description string. For example, a uid lookup description will appear as |
| 76 |
"uid:user@domain". |
| 77 |
|
| 78 |
nfs.idmap will return 0 if the key was instantiated, and non-zero otherwise. |