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 | |
7 | performing an upcall to userspace to request the information. Id mapper will | |
8 | user request-key to perform this upcall and cache the result. The program | |
9 | /usr/sbin/nfs.upcall should be called by request-key, and will perform the | |
10 | translation and initialize a key with the resulting information. | |
11 | ||
12 | NFS_USE_NEW_IDMAPPER must be selected when configuring the kernel to use this | |
13 | feature. | |
14 | ||
15 | =========== | |
16 | Configuring | |
17 | =========== | |
18 | The file /etc/request-key.conf will need to be modified so /sbin/request-key can | |
19 | direct the upcall. The following line should be added: | |
20 | ||
21 | #OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ... | |
22 | #====== ======= =============== =============== =============================== | |
23 | create id_resolver * * /usr/sbin/nfs.upcall %k %d 600 | |
24 | ||
25 | This will direct all id_resolver requests to the program /usr/sbin/nfs.upcall. | |
26 | The last parameter, 600, defines how many seconds into the future the key will | |
27 | expire. This parameter is optional for /usr/sbin/nfs.upcall. When the timeout | |
28 | is not specified, nfs.upcall will default to 600 seconds. | |
29 | ||
30 | id mapper uses for key descriptions: | |
31 | uid: Find the UID for the given user | |
32 | gid: Find the GID for the given group | |
33 | user: Find the user name for the given UID | |
34 | group: Find the group name for the given GID | |
35 | ||
36 | You can handle any of these individually, rather than using the generic upcall | |
37 | program. If you would like to use your own program for a uid lookup then you | |
38 | would edit your request-key.conf so it look similar to this: | |
39 | ||
40 | #OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ... | |
41 | #====== ======= =============== =============== =============================== | |
42 | create id_resolver uid:* * /some/other/program %k %d 600 | |
43 | create id_resolver * * /usr/sbin/nfs.upcall %k %d 600 | |
44 | ||
45 | Notice that the new line was added above the line for the generic program. | |
46 | request-key will find the first matching line and corresponding program. In | |
47 | this case, /some/other/program will handle all uid lookups and | |
48 | /usr/sbin/nfs.upcall will handle gid, user, and group lookups. | |
49 | ||
50 | See <file:Documentation/keys-request-keys.txt> for more information about the | |
51 | request-key function. | |
52 | ||
53 | ||
54 | ========== | |
55 | nfs.upcall | |
56 | ========== | |
57 | nfs.upcall is designed to be called by request-key, and should not be run "by | |
58 | hand". This program takes two arguments, a serialized key and a key | |
59 | description. The serialized key is first converted into a key_serial_t, and | |
60 | then passed as an argument to keyctl_instantiate (both are part of keyutils.h). | |
61 | ||
62 | The actual lookups are performed by functions found in nfsidmap.h. nfs.upcall | |
63 | determines the correct function to call by looking at the first part of the | |
64 | description string. For example, a uid lookup description will appear as | |
65 | "uid:user@domain". | |
66 | ||
67 | nfs.upcall will return 0 if the key was instantiated, and non-zero otherwise. |