Debian Codegraph @

upstream/debian-unstable/man8/gssd.8

raw
1 .\"
2 .\" rpc.gssd(8)
3 .\"
4 .\" Copyright (C) 2003 J. Bruce Fields <[email protected]>
5 .\"
6 .TH rpc.gssd 8 "20 Feb 2013"
7 .SH NAME
8 rpc.gssd \- RPCSEC_GSS daemon
9 .SH SYNOPSIS
10 .B rpc.gssd
11 .RB [ \-DfMnlvrHC ]
12 .RB [ \-k
13 .IR keytab ]
14 .RB [ \-p
15 .IR pipefsdir ]
16 .RB [ \-d
17 .IR ccachedir ]
18 .RB [ \-t
19 .IR timeout ]
20 .RB [ \-T
21 .IR timeout ]
22 .RB [ \-U
23 .IR timeout ]
24 .RB [ \-R
25 .IR realm ]
26 .SH INTRODUCTION
27 The RPCSEC_GSS protocol, defined in RFC 5403, is used to provide
28 strong security for RPC-based protocols such as NFS.
29 .P
30 Before exchanging RPC requests using RPCSEC_GSS, an RPC client must
31 establish a GSS
32 .IR "security context" .
33 A security context is shared state on each
34 end of a network transport that enables GSS-API security services.
35 .P
36 Security contexts are established using
37 .IR "security credentials" .
38 A credential grants temporary access to a secure network service,
39 much as a railway ticket grants temporary access to use a rail service.
40 .P
41 A user typically obtains a credential by providing a password to the
42 .BR kinit (1)
43 command, or via a PAM library at login time.
44 A credential acquired with a
45 .I user principal
46 is known as a
47 .I user credential
48 (see
49 .BR kerberos (1)
50 for more on principals).
51 .P
52 Certain operations require a credential that
53 represents no particular user
54 or
55 represents the host itself.
56 This kind of credential is called a
57 .IR "machine credential" .
58 .P
59 A host establishes its machine credential using a
60 .I "service principal"
61 whose encrypted password is stored in a local file known as a
62 .IR keytab .
63 A machine credential remains effective
64 without user intervention
65 as long as the host can renew it.
66 .P
67 Once obtained, credentials are typically stored in local temporary files
68 with well-known pathnames.
69 .SH DESCRIPTION
70 To establish GSS security contexts using these credential files,
71 the Linux kernel RPC client depends on a userspace daemon called
72 .BR rpc.gssd .
73 The
74 .B rpc.gssd
75 daemon uses the rpc_pipefs filesystem to communicate with the kernel.
76 .SS User Credentials
77 When a user authenticates using a command such as
78 .BR kinit (1),
79 the resulting credential is stored in a file with a well-known name
80 constructed using the user's UID.
81 .P
82 To interact with an NFS server
83 on behalf of a particular Kerberos-authenticated user,
84 the Linux kernel RPC client requests that
85 .B rpc.gssd
86 initialize a security context with the credential
87 in that user's credential file.
88 .P
89 Typically, credential files are placed in
90 .IR /tmp .
91 However,
92 .B rpc.gssd
93 can search for credential files in more than one directory.
94 See the description of the
95 .B -d
96 option for details.
97 .SS Machine Credentials
98 .B rpc.gssd
99 searches the default keytab,
100 .IR /etc/krb5.keytab ,
101 in the following order for a principal and password to use
102 when establishing the machine credential.
103 For the search, rpc.gssd replaces <hostname> and <REALM> with the local
104 system's hostname and Kerberos realm.
105 .sp
106 <HOSTNAME>$@<REALM>
107 .br
108 root/<hostname>@<REALM>
109 .br
110 nfs/<hostname>@<REALM>
111 .br
112 host/<hostname>@<REALM>
113 .br
114 root/<anyname>@<REALM>
115 .br
116 nfs/<anyname>@<REALM>
117 .br
118 host/<anyname>@<REALM>
119 .sp
120 rpc.gssd selects one of the <anyname> entries if it does not find
121 a service principal matching the local hostname,
122 e.g. if DHCP assigns the local hostname dynamically.
123 The <anyname> facility enables the use of the same keytab on multiple systems.
124 However, using the same service principal to establish a machine credential
125 on multiple hosts can create unwanted security exposures
126 and is therefore not recommended.
127 .P
128 Note that <HOSTNAME>$@<REALM> is a user principal
129 that enables Kerberized NFS when the local system is joined
130 to an Active Directory domain using Samba.
131 The keytab provides the password for this principal.
132 .P
133 You can specify a different keytab by using the
134 .B -k
135 option if
136 .I /etc/krb5.keytab
137 does not exist or does not provide one of these principals.
138 .SS Credentials for UID 0
139 UID 0 is a special case.
140 By default
141 .B rpc.gssd
142 uses the system's machine credentials for UID 0 accesses
143 that require GSS authentication.
144 This limits the privileges of the root user
145 when accessing network resources that require authentication.
146 .P
147 Specify the
148 .B -n
149 option when starting
150 .B rpc.gssd
151 if you'd like to force the root user to obtain a user credential
152 rather than use the local system's machine credential.
153 .P
154 When
155 .B -n
156 is specified,
157 the kernel continues to request a GSS context established
158 with a machine credential for NFSv4 operations,
159 such as SETCLIENTID or RENEW, that manage state.
160 If
161 .B rpc.gssd
162 cannot obtain a machine credential (say, the local system has
163 no keytab), NFSv4 operations that require machine credentials will fail.
164 .SS Encryption types
165 A realm administrator can choose to add keys encoded in a number of different
166 encryption types to the local system's keytab.
167 For instance, a host/ principal might have keys for the
168 .BR aes256-cts-hmac-sha384-192 ,
169 .BR aes128-cts-hmac-sha256-128 ,
170 .BR aes256-cts-hmac-sha1-96 ", and"
171 .BR aes128-cts-hmac-sha1-96 " encryption types."
172 This permits
173 .B rpc.gssd
174 to choose an appropriate encryption type that the target NFS server
175 supports.
176
177 .SH OPTIONS
178 .TP
179 .B \-D
180 The server name passed to GSSAPI for authentication is normally the
181 name exactly as requested. e.g. for NFS
182 it is the server name in the "servername:/path" mount request. Only if this
183 servername appears to be an IP address (IPv4 or IPv6) or an
184 unqualified name (no dots) will a reverse DNS lookup
185 will be performed to get the canonical server name.
186
187 If
188 .B \-D
189 is present, a reverse DNS lookup will
190 .I always
191 be used, even if the server name looks like a canonical name. So it
192 is needed if partially qualified, or non canonical names are regularly
193 used.
194
195 Using
196 .B \-D
197 can introduce a security vulnerability, so it is recommended that
198 .B \-D
199 not be used, and that canonical names always be used when requesting
200 services.
201 .TP
202 .B -f
203 Runs
204 .B rpc.gssd
205 in the foreground and sends output to stderr (as opposed to syslogd)
206 .TP
207 .B -n
208 When specified, UID 0 is forced to obtain user credentials
209 which are used instead of the local system's machine credentials.
210 .TP
211 .BI "-k " keytab
212 Tells
213 .B rpc.gssd
214 to use the keys found in
215 .I keytab
216 to obtain machine credentials.
217 The default value is
218 .IR /etc/krb5.keytab .
219 .TP
220 .BI "-p " path
221 Tells
222 .B rpc.gssd
223 where to look for the rpc_pipefs filesystem. The default value is
224 .IR /var/lib/nfs/rpc_pipefs .
225 .TP
226 .BI "-d " search-path
227 This option specifies a colon separated list of directories that
228 .B rpc.gssd
229 searches for credential files. The default value is
230 .IR /tmp:/run/user/%U .
231 The literal sequence "%U" can be specified to substitute the UID
232 of the user for whom credentials are being searched.
233 .TP
234 .B -M
235 By default, machine credentials are stored in files in the first
236 directory in the credential directory search path (see the
237 .B -d
238 option). When
239 .B -M
240 is set,
241 .B rpc.gssd
242 stores machine credentials in memory instead.
243 .TP
244 .B -v
245 Increases the verbosity of the output (can be specified multiple times).
246 .TP
247 .B -r
248 If the RPCSEC_GSS library supports setting debug level,
249 increases the verbosity of the output (can be specified multiple times).
250 .TP
251 .BI "-R " realm
252 Kerberos tickets from this
253 .I realm
254 will be preferred when scanning available credentials cache files to be
255 used to create a context. By default, the default realm, as configured
256 in the Kerberos configuration file, is preferred.
257 .TP
258 .BI "-t " timeout
259 Timeout, in seconds, for kernel GSS contexts. This option allows you to force
260 new kernel contexts to be negotiated after
261 .I timeout
262 seconds, which allows changing Kerberos tickets and identities frequently.
263 The default is no explicit timeout, which means the kernel context will live
264 the lifetime of the Kerberos service ticket used in its creation.
265 .TP
266 .BI "-T " timeout
267 Timeout, in seconds, to create an RPC connection with a server while
268 establishing an authenticated gss context for a user.
269 The default timeout is set to 5 seconds.
270 If you get messages like "WARNING: can't create tcp rpc_clnt to server
271 %servername% for user with uid %uid%: RPC: Remote system error -
272 Connection timed out", you should consider an increase of this timeout.
273 .TP
274 .BI "-U " timeout
275 Timeout, in seconds, for upcall threads. Threads executing longer than
276 .I timeout
277 seconds will cause an error message to be logged. The default
278 .I timeout
279 is 30 seconds. The minimum is 5 seconds. The maximum is 600 seconds.
280 .TP
281 .B -C
282 In addition to logging an error message for threads that have timed out,
283 the thread will be canceled and an error of -ETIMEDOUT will be reported
284 to the kernel.
285 .TP
286 .B -H
287 Avoids setting $HOME to "/". This allows rpc.gssd to read per user k5identity
288 files versus trying to read /.k5identity for each user.
289
290 If
291 .B \-H
292 is not set, rpc.gssd will use the first match found in
293 /var/kerberos/krb5/user/$EUID/client.keytab and will not use a principal based on
294 host and/or service parameters listed in $HOME/.k5identity.
295 .SH CONFIGURATION FILE
296 Many of the options that can be set on the command line can also be
297 controlled through values set in the
298 .B [gssd]
299 section of the
300 .I /etc/nfs.conf
301 configuration file. Values recognized include:
302 .TP
303 .B verbosity
304 Value which is equivalent to the number of
305 .BR -v .
306 .TP
307 .B rpc-verbosity
308 Value which is equivalent to the number of
309 .BR -r .
310 .TP
311 .B use-memcache
312 A Boolean flag equivalent to
313 .BR -M .
314 .TP
315 .B use-machine-creds
316 A Boolean flag. Setting to
317 .B false
318 is equivalent to giving the
319 .B -n
320 flag.
321 .TP
322 .B avoid-dns
323 Setting to
324 .B false
325 is equivalent to providing the
326 .B -D
327 flag.
328 .TP
329 .B allowed-enctypes
330 Allows you to restrict
331 .B rpc.gssd
332 to using a subset of the encryption types permitted by the kernel and the krb5
333 libraries. This is useful if you need to interoperate with an NFS server that
334 does not have support for the newer SHA2 and Camellia encryption types, for
335 example. This configuration file option does not have an equivalent
336 command-line option.
337 .TP
338 .B context-timeout
339 Equivalent to
340 .BR -t .
341 .TP
342 .B rpc-timeout
343 Equivalent to
344 .BR -T .
345 .TP
346 .B keytab-file
347 Equivalent to
348 .BR -k .
349 .TP
350 .BR cred-cache-directory
351 Equivalent to
352 .BR -d .
353 .TP
354 .B preferred-realm
355 Equivalent to
356 .BR -R .
357 .TP
358 .B upcall-timeout
359 Equivalent to
360 .BR -U .
361 .TP
362 .B cancel-timed-out-upcalls
363 Setting to
364 .B true
365 is equivalent to providing the
366 .B -C
367 flag.
368 .TP
369 .B set-home
370 Setting to
371 .B false
372 is equivalent to providing the
373 .B -H
374 flag.
375 .TP
376 .B use-gss-proxy
377 Setting this to 1 allows
378 .BR gssproxy (8)
379 to intercept GSSAPI calls and service them on behalf of
380 .BR rpc.gssd ,
381 enabling certain features such as keytab-based client initiation.
382 Note that this is unrelated to the functionality that
383 .BR gssproxy (8)
384 provides on behalf of the NFS server. For more information, see
385 .BR https://github.com/gssapi/gssproxy/blob/main/docs/NFS.md#nfs-client .
386 .P
387 In addition, the following value is recognized from the
388 .B [general]
389 section:
390 .TP
391 .B pipefs-directory
392 Equivalent to
393 .BR -p .
394
395 .SH SEE ALSO
396 .BR rpc.svcgssd (8),
397 .BR kerberos (1),
398 .BR kinit (1),
399 .BR krb5.conf (5),
400 .BR gssproxy (8)
401 .SH AUTHORS
402 .br
403 Dug Song <[email protected]>
404 .br
405 Andy Adamson <[email protected]>
406 .br
407 Marius Aamodt Eriksen <[email protected]>
408 .br
409 J. Bruce Fields <[email protected]>