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