]>
Commit | Line | Data |
---|---|---|
955a857e BS |
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 | |
a602bea3 BS |
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. | |
955a857e | 21 | |
955a857e BS |
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 | #====== ======= =============== =============== =============================== | |
eb1c86b8 | 31 | create id_resolver * * /usr/sbin/nfs.idmap %k %d 600 |
955a857e | 32 | |
eb1c86b8 | 33 | This will direct all id_resolver requests to the program /usr/sbin/nfs.idmap. |
955a857e | 34 | The last parameter, 600, defines how many seconds into the future the key will |
eb1c86b8 BS |
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. | |
955a857e BS |
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 | #====== ======= =============== =============== =============================== | |
eb1c86b8 BS |
50 | create id_resolver uid:* * /some/other/program %k %d 600 |
51 | create id_resolver * * /usr/sbin/nfs.idmap %k %d 600 | |
955a857e BS |
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 | |
eb1c86b8 | 56 | /usr/sbin/nfs.idmap will handle gid, user, and group lookups. |
955a857e | 57 | |
395cf969 | 58 | See <file:Documentation/security/keys-request-key.txt> for more information |
d410fa4e | 59 | about the request-key function. |
955a857e BS |
60 | |
61 | ||
eb1c86b8 BS |
62 | ========= |
63 | nfs.idmap | |
64 | ========= | |
65 | nfs.idmap is designed to be called by request-key, and should not be run "by | |
955a857e BS |
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 | ||
eb1c86b8 | 70 | The actual lookups are performed by functions found in nfsidmap.h. nfs.idmap |
955a857e BS |
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 | ||
eb1c86b8 | 75 | nfs.idmap will return 0 if the key was instantiated, and non-zero otherwise. |