| Bryan Schumaker | 955a857 | 2010-09-29 15:41:49 -0400 | [diff] [blame] | 1 | |
| 2 | ========= |
| 3 | ID Mapper |
| 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 |
| Bryan Schumaker | a602bea | 2012-01-26 16:54:25 -0500 | [diff] [blame] | 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. |
| Bryan Schumaker | 955a857 | 2010-09-29 15:41:49 -0400 | [diff] [blame] | 10 | |
| Bryan Schumaker | a602bea | 2012-01-26 16:54:25 -0500 | [diff] [blame] | 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 | |
| Bryan Schumaker | 955a857 | 2010-09-29 15:41:49 -0400 | [diff] [blame] | 22 | |
| 23 | =========== |
| 24 | Configuring |
| 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 | #====== ======= =============== =============== =============================== |
| Bryan Schumaker | eb1c86b | 2010-10-26 13:27:42 -0400 | [diff] [blame] | 31 | create id_resolver * * /usr/sbin/nfs.idmap %k %d 600 |
| Bryan Schumaker | 955a857 | 2010-09-29 15:41:49 -0400 | [diff] [blame] | 32 | |
| Bryan Schumaker | eb1c86b | 2010-10-26 13:27:42 -0400 | [diff] [blame] | 33 | This will direct all id_resolver requests to the program /usr/sbin/nfs.idmap. |
| Bryan Schumaker | 955a857 | 2010-09-29 15:41:49 -0400 | [diff] [blame] | 34 | The last parameter, 600, defines how many seconds into the future the key will |
| Bryan Schumaker | eb1c86b | 2010-10-26 13:27:42 -0400 | [diff] [blame] | 35 | expire. This parameter is optional for /usr/sbin/nfs.idmap. When the timeout |
| 36 | is not specified, nfs.idmap will default to 600 seconds. |
| Bryan Schumaker | 955a857 | 2010-09-29 15:41:49 -0400 | [diff] [blame] | 37 | |
| 38 | id mapper uses for key descriptions: |
| 39 | uid: Find the UID for the given user |
| 40 | gid: Find the GID for the given group |
| 41 | user: Find the user name for the given UID |
| 42 | group: Find the group name for the given GID |
| 43 | |
| 44 | You can handle any of these individually, rather than using the generic upcall |
| 45 | program. If you would like to use your own program for a uid lookup then you |
| 46 | would edit your request-key.conf so it look similar to this: |
| 47 | |
| 48 | #OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ... |
| 49 | #====== ======= =============== =============== =============================== |
| Bryan Schumaker | eb1c86b | 2010-10-26 13:27:42 -0400 | [diff] [blame] | 50 | create id_resolver uid:* * /some/other/program %k %d 600 |
| 51 | create id_resolver * * /usr/sbin/nfs.idmap %k %d 600 |
| Bryan Schumaker | 955a857 | 2010-09-29 15:41:49 -0400 | [diff] [blame] | 52 | |
| 53 | Notice that the new line was added above the line for the generic program. |
| 54 | request-key will find the first matching line and corresponding program. In |
| 55 | this case, /some/other/program will handle all uid lookups and |
| Bryan Schumaker | eb1c86b | 2010-10-26 13:27:42 -0400 | [diff] [blame] | 56 | /usr/sbin/nfs.idmap will handle gid, user, and group lookups. |
| Bryan Schumaker | 955a857 | 2010-09-29 15:41:49 -0400 | [diff] [blame] | 57 | |
| Paul Bolle | 395cf96 | 2011-08-15 02:02:26 +0200 | [diff] [blame] | 58 | See <file:Documentation/security/keys-request-key.txt> for more information |
| Randy Dunlap | d410fa4 | 2011-05-19 15:59:38 -0700 | [diff] [blame] | 59 | about the request-key function. |
| Bryan Schumaker | 955a857 | 2010-09-29 15:41:49 -0400 | [diff] [blame] | 60 | |
| 61 | |
| Bryan Schumaker | eb1c86b | 2010-10-26 13:27:42 -0400 | [diff] [blame] | 62 | ========= |
| 63 | nfs.idmap |
| 64 | ========= |
| 65 | nfs.idmap is designed to be called by request-key, and should not be run "by |
| Bryan Schumaker | 955a857 | 2010-09-29 15:41:49 -0400 | [diff] [blame] | 66 | hand". This program takes two arguments, a serialized key and a key |
| 67 | description. The serialized key is first converted into a key_serial_t, and |
| 68 | then passed as an argument to keyctl_instantiate (both are part of keyutils.h). |
| 69 | |
| Bryan Schumaker | eb1c86b | 2010-10-26 13:27:42 -0400 | [diff] [blame] | 70 | The actual lookups are performed by functions found in nfsidmap.h. nfs.idmap |
| Bryan Schumaker | 955a857 | 2010-09-29 15:41:49 -0400 | [diff] [blame] | 71 | determines the correct function to call by looking at the first part of the |
| 72 | description string. For example, a uid lookup description will appear as |
| 73 | "uid:user@domain". |
| 74 | |
| Bryan Schumaker | eb1c86b | 2010-10-26 13:27:42 -0400 | [diff] [blame] | 75 | nfs.idmap will return 0 if the key was instantiated, and non-zero otherwise. |