Debian Codegraph @

upstream/debian-unstable/man8/nfsidmap.8

raw
1 .\"
2 .\"@(#)nfsidmap(8) - The NFS idmapper upcall program
3 .\"
4 .\" Copyright (C) 2010 Bryan Schumaker <[email protected]>
5 .TH nfsidmap 8 "1 October 2010"
6 .SH NAME
7 nfsidmap \- The NFS idmapper upcall program
8 .SH SYNOPSIS
9 .B "nfsidmap [-v] [-t timeout] key desc"
10 .br
11 .B "nfsidmap [-v] [-c]"
12 .br
13 .B "nfsidmap [-v] [-u|-g|-r user]"
14 .br
15 .B "nfsidmap -d"
16 .br
17 .B "nfsidmap -l"
18 .br
19 .B "nfsidmap -h"
20 .SH DESCRIPTION
21 The NFSv4 protocol represents the local system's UID and GID values
22 on the wire as strings of the form
23 .IR user@domain .
24 The process of translating from UID to string and string to UID is
25 referred to as "ID mapping."
26 .PP
27 The system derives the
28 .I user
29 part of the string by performing a password or group lookup.
30 The lookup mechanism is configured in
31 .IR /etc/idmapd.conf .
32 .PP
33 By default, the
34 .I domain
35 part of the string is the system's DNS domain name.
36 It can also be specified in
37 .I /etc/idmapd.conf
38 if the system is multi-homed,
39 or if the system's DNS domain name does
40 not match the name of the system's Kerberos realm.
41 .PP
42 When the domain is not specified in
43 .I /etc/idmapd.conf
44 the local DNS server will be queried for the
45 .I _nfsv4idmapdomain
46 text record. If the record exists
47 that will be used as the domain. When the record
48 does not exist, the domain part of the DNS domain
49 will used.
50 .PP
51 The
52 .I /usr/sbin/nfsidmap
53 program performs translations on behalf of the kernel.
54 The kernel uses the request-key mechanism to perform
55 an upcall.
56 .I /usr/sbin/nfsidmap
57 is invoked by /sbin/request-key, performs the translation,
58 and initializes a key with the resulting information.
59 The kernel then caches the translation results in the key.
60 .PP
61 .I nfsidmap
62 can also clear cached ID map results in the kernel,
63 or revoke one particular key.
64 An incorrect cached key can result in file and directory ownership
65 reverting to "nobody" on NFSv4 mount points.
66 .PP
67 In addition, the
68 .B -d
69 and
70 .B -l
71 options are available to help diagnose misconfigurations.
72 They have no effect on the keyring containing ID mapping results.
73 .SH OPTIONS
74 .TP
75 .B -c
76 Clear the keyring of all the keys.
77 .TP
78 .B -d
79 Display the system's effective NFSv4 domain name on
80 .IR stdout .
81 .TP
82 .B -g user
83 Revoke the gid key of the given user.
84 .TP
85 .B -h
86 Display usage message.
87 .TP
88 .B -l
89 Display on
90 .I stdout
91 all keys currently in the keyring used to cache ID mapping results.
92 These keys are visible only to the superuser.
93 .TP
94 .B -r user
95 Revoke both the uid and gid key of the given user.
96 .TP
97 .B -t timeout
98 Set the expiration timer, in seconds, on the key.
99 The default is 600 seconds (10 mins).
100 .TP
101 .B -u user
102 Revoke the uid key of the given user.
103 .TP
104 .B -v
105 Increases the verbosity of the output to syslog
106 (can be specified multiple times).
107 .SH CONFIGURING
108 The file
109 .I /etc/request-key.conf
110 will need to be modified so
111 .I /sbin/request-key
112 can properly direct the upcall. The following line should be added before a call
113 to keyctl negate:
114 .PP
115 create id_resolver * * /usr/sbin/nfsidmap -t 600 %k %d
116 .PP
117 This will direct all id_resolver requests to the program
118 .I /usr/sbin/nfsidmap.
119 The
120 .B -t 600
121 defines how many seconds into the future the key will
122 expire. This is an optional parameter for
123 .I /usr/sbin/nfsidmap
124 and will default to 600 seconds when not specified.
125 .PP
126 The idmapper system uses four key descriptions:
127 .PP
128 uid: Find the UID for the given user
129 .br
130 gid: Find the GID for the given group
131 .br
132 user: Find the user name for the given UID
133 .br
134 group: Find the group name for the given GID
135 .PP
136 You can choose to handle any of these individually, rather than using the
137 generic upcall program. If you would like to use your own program for a uid
138 lookup then you would edit your request-key.conf so it looks similar to this:
139 .PP
140 create id_resolver uid:* * /some/other/program %k %d
141 .br
142 create id_resolver * * /usr/sbin/nfsidmap %k %d
143 .PP
144 Notice that the new line was added above the line for the generic program.
145 request-key will find the first matching line and run the corresponding program.
146 In this case, /some/other/program will handle all uid lookups, and
147 /usr/sbin/nfsidmap will handle gid, user, and group lookups.
148 .SH FILES
149 .TP
150 .I /etc/idmapd.conf
151 ID mapping configuration file
152 .TP
153 .I /etc/request-key.conf
154 Request key configuration file
155 .SH "SEE ALSO"
156 .BR idmapd.conf (5),
157 .BR request-key (8)
158 .SH AUTHOR
159 Bryan Schumaker, <[email protected]>