1rpc.gssd(8) System Manager's Manual rpc.gssd(8)
2
6 rpc.gssd - RPCSEC_GSS daemon
7
9 rpc.gssd [-DfMnlvr] [-k keytab] [-p pipefsdir] [-d ccachedir] [-t time‐
10 out] [-R realm]
11
13 The RPCSEC_GSS protocol, defined in RFC 5403, is used to provide strong
14 security for RPC-based protocols such as NFS.
15 Before exchanging RPC requests using RPCSEC_GSS, an RPC client must
17 establish a GSS security context. A security context is shared state
18 on each end of a network transport that enables GSS-API security ser‐
19 vices.
20 Security contexts are established using security credentials. A cre‐
22 dential grants temporary access to a secure network service, much as a
23 railway ticket grants temporary access to use a rail service.
24 A user typically obtains a credential by providing a password to the
26 kinit(1) command, or via a PAM library at login time. A credential
27 acquired with a user principal is known as a user credential (see ker‐
28 beros(1) for more on principals).
29 Certain operations require a credential that represents no particular
31 user or represents the host itself. This kind of credential is called
32 a machine credential.
33 A host establishes its machine credential using a service principal
35 whose encrypted password is stored in a local file known as a keytab.
36 A machine credential remains effective without user intervention as
37 long as the host can renew it.
38 Once obtained, credentials are typically stored in local temporary
40 files with well-known pathnames.
41
43 To establish GSS security contexts using these credential files, the
44 Linux kernel RPC client depends on a userspace daemon called rpc.gssd.
45 The rpc.gssd daemon uses the rpc_pipefs filesystem to communicate with
46 the kernel.
47 User Credentials
49 When a user authenticates using a command such as kinit(1), the result‐
50 ing credential is stored in a file with a well-known name constructed
51 using the user's UID.
52 To interact with an NFS server on behalf of a particular Kerberos-
54 authenticated user, the Linux kernel RPC client requests that rpc.gssd
55 initialize a security context with the credential in that user's cre‐
56 dential file.
57 Typically, credential files are placed in /tmp. However, rpc.gssd can
59 search for credential files in more than one directory. See the
60 description of the -d option for details.
61 Machine Credentials
63 rpc.gssd searches the default keytab, /etc/krb5.keytab, in the follow‐
64 ing order for a principal and password to use when establishing the
65 machine credential. For the search, rpc.gssd replaces <hostname> and
66 <REALM> with the local system's hostname and Kerberos realm.
67 <HOSTNAME>$@<REALM>
69 root/<hostname>@<REALM>
70 nfs/<hostname>@<REALM>
71 host/<hostname>@<REALM>
72 root/<anyname>@<REALM>
73 nfs/<anyname>@<REALM>
74 host/<anyname>@<REALM>
75 rpc.gssd selects one of the <anyname> entries if it does not find a
77 service principal matching the local hostname, e.g. if DHCP assigns the
78 local hostname dynamically. The <anyname> facility enables the use of
79 the same keytab on multiple systems. However, using the same service
80 principal to establish a machine credential on multiple hosts can cre‐
81 ate unwanted security exposures and is therefore not recommended.
82 Note that <HOSTNAME>$@<REALM> is a user principal that enables Kerber‐
84 ized NFS when the local system is joined to an Active Directory domain
85 using Samba. The keytab provides the password for this principal.
86 You can specify a different keytab by using the -k option if
88 /etc/krb5.keytab does not exist or does not provide one of these prin‐
89 cipals.
90 Credentials for UID 0
92 UID 0 is a special case. By default rpc.gssd uses the system's machine
93 credentials for UID 0 accesses that require GSS authentication. This
94 limits the privileges of the root user when accessing network resources
95 that require authentication.
96 Specify the -n option when starting rpc.gssd if you'd like to force the
98 root user to obtain a user credential rather than use the local sys‐
99 tem's machine credential.
100 When -n is specified, the kernel continues to request a GSS context
102 established with a machine credential for NFSv4 operations, such as
103 SETCLIENTID or RENEW, that manage state. If rpc.gssd cannot obtain a
104 machine credential (say, the local system has no keytab), NFSv4 opera‐
105 tions that require machine credentials will fail.
106 Encryption types
108 A realm administrator can choose to add keys encoded in a number of
109 different encryption types to the local system's keytab. For instance,
110 a host/ principal might have keys for the aes256-cts-hmac-sha1-96,
111 aes128-cts-hmac-sha1-96, des3-cbc-sha1, and arcfour-hmac encryption
112 types. This permits rpc.gssd to choose an appropriate encryption type
113 that the target NFS server supports.
114 These encryption types are stronger than legacy single-DES encryption
116 types. To interoperate in environments where servers support only weak
117 encryption types, you can restrict your client to use only single-DES
118 encryption types by specifying the -l option when starting rpc.gssd.
119
121 -D The server name passed to GSSAPI for authentication is normally
122 the name exactly as requested. e.g. for NFS it is the server
123 name in the "servername:/path" mount request. Only if this
124 servername appears to be an IP address (IPv4 or IPv6) or an
125 unqualified name (no dots) will a reverse DNS lookup will be
126 performed to get the canoncial server name.
127 If -D is present, a reverse DNS lookup will always be used, even
129 if the server name looks like a canonical name. So it is needed
130 if partially qualified, or non canonical names are regularly
131 used.
132 Using -D can introduce a security vulnerability, so it is recom‐
134 mended that -D not be used, and that canonical names always be
135 used when requesting services.
136 -f Runs rpc.gssd in the foreground and sends output to stderr (as
138 opposed to syslogd)
139 -n When specified, UID 0 is forced to obtain user credentials which
141 are used instead of the local system's machine credentials.
142 -k keytab
144 Tells rpc.gssd to use the keys found in keytab to obtain machine
145 credentials. The default value is /etc/krb5.keytab.
146 -l When specified, restricts rpc.gssd to sessions to weak encryp‐
148 tion types such as des-cbc-crc. This option is available only
149 when the local system's Kerberos library supports settable
150 encryption types.
151 -p path
153 Tells rpc.gssd where to look for the rpc_pipefs filesystem. The
154 default value is /var/lib/nfs/rpc_pipefs.
155 -d search-path
157 This option specifies a colon separated list of directories that
158 rpc.gssd searches for credential files. The default value is
159 /tmp:/run/user/%U. The literal sequence "%U" can be specified
160 to substitue the UID of the user for whom credentials are being
161 searched.
162 -M By default, machine credentials are stored in files in the first
164 directory in the credential directory search path (see the -d
165 option). When -M is set, rpc.gssd stores machine credentials in
166 memory instead.
167 -v Increases the verbosity of the output (can be specified multiple
169 times).
170 -r If the RPCSEC_GSS library supports setting debug level,
172 increases the verbosity of the output (can be specified multiple
173 times).
174 -R realm
176 Kerberos tickets from this realm will be preferred when scanning
177 available credentials cache files to be used to create a con‐
178 text. By default, the default realm, as configured in the Ker‐
179 beros configuration file, is preferred.
180 -t timeout
182 Timeout, in seconds, for kernel GSS contexts. This option allows
183 you to force new kernel contexts to be negotiated after timeout
184 seconds, which allows changing Kerberos tickets and identities
185 frequently. The default is no explicit timeout, which means the
186 kernel context will live the lifetime of the Kerberos service
187 ticket used in its creation.
188 -T timeout
190 Timeout, in seconds, to create an RPC connection with a server
191 while establishing an authenticated gss context for a user. The
192 default timeout is set to 5 seconds. If you get messages like
193 "WARNING: can't create tcp rpc_clnt to server %servername% for
194 user with uid %uid%: RPC: Remote system error - Connection timed
195 out", you should consider an increase of this timeout.
196
198 Many of the options that can be set on the command line can also be
199 controlled through values set in the [gssd] section of the
200 /etc/nfs.conf configuration file. Values recognized include:
201 verbosity
203 Value which is equivalent to the number of -v.
204 rpc-verbosity
206 Value which is equivalent to the number of -r.
207 use-memcache
209 A Boolean flag equivalent to -M.
210 use-machine-creds
212 A Boolean flag. Setting to false is equivalent to giving the -n
213 flag.
214 avoid-dns
216 Setting to false is equivalent to providing the -D flag.
217 limit-to-legacy-enctypes
219 Equivalent to -l.
220 context-timeout
222 Equivalent to -t.
223 rpc-timeout
225 Equivalent to -T.
226 keytab-file
228 Equivalent to -k.
229 cred-cache-directory
231 Equivalent to -d.
232 preferred-realm
234 Equivalent to -R.
235 In addtion, the following value is recognized from the [general] sec‐
237 tion:
238 pipefs-directory
240 Equivalent to -p.
241
244 rpc.svcgssd(8), kerberos(1), kinit(1), krb5.conf(5)
245
247 Dug Song <dugsong@umich.edu>
248 Andy Adamson <andros@umich.edu>
249 Marius Aamodt Eriksen <marius@umich.edu>
250 J. Bruce Fields <bfields@umich.edu>
251 20 Feb 2013 rpc.gssd(8)