1rpc.gssd(8)                 System Manager's Manual                rpc.gssd(8)
2
3
4

NAME

6       rpc.gssd - RPCSEC_GSS daemon
7

SYNOPSIS

9       rpc.gssd  [-DfMnlvrHC]  [-k  keytab]  [-p pipefsdir] [-d ccachedir] [-t
10       timeout] [-T timeout] [-U timeout] [-R realm]
11

INTRODUCTION

13       The RPCSEC_GSS protocol, defined in RFC 5403, is used to provide strong
14       security for RPC-based protocols such as NFS.
15
16       Before exchanging RPC requests using RPCSEC_GSS, an RPC client must es‐
17       tablish a GSS security context.  A security context is shared state  on
18       each end of a network transport that enables GSS-API security services.
19
20       Security  contexts  are established using security credentials.  A cre‐
21       dential grants temporary access to a secure network service, much as  a
22       railway ticket grants temporary access to use a rail service.
23
24       A  user  typically  obtains a credential by providing a password to the
25       kinit(1) command, or via a PAM library at login time.  A credential ac‐
26       quired  with  a  user principal is known as a user credential (see ker‐
27       beros(1) for more on principals).
28
29       Certain operations require a credential that represents  no  particular
30       user  or represents the host itself.  This kind of credential is called
31       a machine credential.
32
33       A host establishes its machine credential  using  a  service  principal
34       whose  encrypted  password is stored in a local file known as a keytab.
35       A machine credential remains effective  without  user  intervention  as
36       long as the host can renew it.
37
38       Once  obtained,  credentials  are  typically  stored in local temporary
39       files with well-known pathnames.
40

DESCRIPTION

42       To establish GSS security contexts using these  credential  files,  the
43       Linux  kernel RPC client depends on a userspace daemon called rpc.gssd.
44       The rpc.gssd daemon uses the rpc_pipefs filesystem to communicate  with
45       the kernel.
46
47   User Credentials
48       When a user authenticates using a command such as kinit(1), the result‐
49       ing credential is stored in a file with a well-known  name  constructed
50       using the user's UID.
51
52       To  interact  with an NFS server on behalf of a particular Kerberos-au‐
53       thenticated user, the Linux kernel RPC client  requests  that  rpc.gssd
54       initialize  a  security context with the credential in that user's cre‐
55       dential file.
56
57       Typically, credential files are placed in /tmp.  However, rpc.gssd  can
58       search  for  credential  files in more than one directory.  See the de‐
59       scription of the -d option for details.
60
61   Machine Credentials
62       rpc.gssd searches the default keytab, /etc/krb5.keytab, in the  follow‐
63       ing order for a principal and password to use when establishing the ma‐
64       chine credential.  For the search,  rpc.gssd  replaces  <hostname>  and
65       <REALM> with the local system's hostname and Kerberos realm.
66
67          <HOSTNAME>$@<REALM>
68          root/<hostname>@<REALM>
69          nfs/<hostname>@<REALM>
70          host/<hostname>@<REALM>
71          root/<anyname>@<REALM>
72          nfs/<anyname>@<REALM>
73          host/<anyname>@<REALM>
74
75       rpc.gssd  selects  one  of  the <anyname> entries if it does not find a
76       service principal matching the local hostname, e.g. if DHCP assigns the
77       local  hostname dynamically.  The <anyname> facility enables the use of
78       the same keytab on multiple systems.  However, using the  same  service
79       principal  to establish a machine credential on multiple hosts can cre‐
80       ate unwanted security exposures and is therefore not recommended.
81
82       Note that <HOSTNAME>$@<REALM> is a user principal that enables  Kerber‐
83       ized  NFS when the local system is joined to an Active Directory domain
84       using Samba.  The keytab provides the password for this principal.
85
86       You  can  specify  a  different  keytab  by  using  the  -k  option  if
87       /etc/krb5.keytab  does not exist or does not provide one of these prin‐
88       cipals.
89
90   Credentials for UID 0
91       UID 0 is a special case.  By default rpc.gssd uses the system's machine
92       credentials  for  UID 0 accesses that require GSS authentication.  This
93       limits the privileges of the root user when accessing network resources
94       that require authentication.
95
96       Specify the -n option when starting rpc.gssd if you'd like to force the
97       root user to obtain a user credential rather than use  the  local  sys‐
98       tem's machine credential.
99
100       When -n is specified, the kernel continues to request a GSS context es‐
101       tablished with a machine credential for NFSv4 operations, such as  SET‐
102       CLIENTID  or RENEW, that manage state.  If rpc.gssd cannot obtain a ma‐
103       chine credential (say, the local system has no  keytab),  NFSv4  opera‐
104       tions that require machine credentials will fail.
105
106   Encryption types
107       A  realm  administrator  can  choose to add keys encoded in a number of
108       different encryption types to the local system's keytab.  For instance,
109       a  host/  principal  might  have  keys for the aes256-cts-hmac-sha1-96,
110       aes128-cts-hmac-sha1-96,  des3-cbc-sha1,  and  arcfour-hmac  encryption
111       types.   This permits rpc.gssd to choose an appropriate encryption type
112       that the target NFS server supports.
113
114       These encryption types are stronger than legacy  single-DES  encryption
115       types.  To interoperate in environments where servers support only weak
116       encryption types, you can restrict your client to use  only  single-DES
117       encryption types by specifying the -l option when starting rpc.gssd.
118

OPTIONS

120       -D     The  server name passed to GSSAPI for authentication is normally
121              the name exactly as requested.  e.g. for NFS it  is  the  server
122              name  in  the  "servername:/path"  mount  request.  Only if this
123              servername appears to be an IP address (IPv4 or IPv6) or an  un‐
124              qualified  name (no dots) will a reverse DNS lookup will be per‐
125              formed to get the canoncial server name.
126
127              If -D is present, a reverse DNS lookup will always be used, even
128              if the server name looks like a canonical name.  So it is needed
129              if partially qualified, or non  canonical  names  are  regularly
130              used.
131
132              Using -D can introduce a security vulnerability, so it is recom‐
133              mended that -D not be used, and that canonical names  always  be
134              used when requesting services.
135
136       -f     Runs  rpc.gssd  in the foreground and sends output to stderr (as
137              opposed to syslogd)
138
139       -n     When specified, UID 0 is forced to obtain user credentials which
140              are used instead of the local system's machine credentials.
141
142       -k keytab
143              Tells rpc.gssd to use the keys found in keytab to obtain machine
144              credentials.  The default value is /etc/krb5.keytab.
145
146       -l     When specified, restricts rpc.gssd to sessions to  weak  encryp‐
147              tion  types  such as des-cbc-crc.  This option is available only
148              when the local system's Kerberos library supports  settable  en‐
149              cryption types.
150
151       -p path
152              Tells rpc.gssd where to look for the rpc_pipefs filesystem.  The
153              default value is /var/lib/nfs/rpc_pipefs.
154
155       -d search-path
156              This option specifies a colon separated list of directories that
157              rpc.gssd  searches  for  credential files.  The default value is
158              /tmp:/run/user/%U.  The literal sequence "%U" can  be  specified
159              to  substitue the UID of the user for whom credentials are being
160              searched.
161
162       -M     By default, machine credentials are stored in files in the first
163              directory  in  the  credential directory search path (see the -d
164              option).  When -M is set, rpc.gssd stores machine credentials in
165              memory instead.
166
167       -v     Increases the verbosity of the output (can be specified multiple
168              times).
169
170       -r     If the RPCSEC_GSS library  supports  setting  debug  level,  in‐
171              creases  the  verbosity of the output (can be specified multiple
172              times).
173
174       -R realm
175              Kerberos tickets from this realm will be preferred when scanning
176              available  credentials  cache  files to be used to create a con‐
177              text.  By default, the default realm, as configured in the  Ker‐
178              beros configuration file, is preferred.
179
180       -t timeout
181              Timeout, in seconds, for kernel GSS contexts. This option allows
182              you to force new kernel contexts to be negotiated after  timeout
183              seconds,  which  allows changing Kerberos tickets and identities
184              frequently.  The default is no explicit timeout, which means the
185              kernel  context  will  live the lifetime of the Kerberos service
186              ticket used in its creation.
187
188       -T timeout
189              Timeout, in seconds, to create an RPC connection with  a  server
190              while establishing an authenticated gss context for a user.  The
191              default timeout is set to 5 seconds.  If you get  messages  like
192              "WARNING:  can't  create tcp rpc_clnt to server %servername% for
193              user with uid %uid%: RPC: Remote system error - Connection timed
194              out", you should consider an increase of this timeout.
195
196       -U timeout
197              Timeout,  in  seconds,  for  upcall  threads.  Threads executing
198              longer than timeout seconds will cause an error  message  to  be
199              logged.   The  default  timeout is 30 seconds.  The minimum is 5
200              seconds.  The maximum is 600 seconds.
201
202       -C     In addition to logging an error message for  threads  that  have
203              timed  out, the thread will be canceled and an error of -ETIMED‐
204              OUT will be reported to the kernel.
205
206       -H     Avoids setting $HOME to "/". This allows rpc.gssd  to  read  per
207              user  k5identity  files  versus  trying to read /.k5identity for
208              each user.
209
210              If -H is not set, rpc.gssd will use the  first  match  found  in
211              /var/kerberos/krb5/user/$EUID/client.keytab  and  will not use a
212              principal based on host  and/or  service  parameters  listed  in
213              $HOME/.k5identity.
214

CONFIGURATION FILE

216       Many  of  the  options  that can be set on the command line can also be
217       controlled  through  values  set  in  the   [gssd]   section   of   the
218       /etc/nfs.conf configuration file.  Values recognized include:
219
220       verbosity
221              Value which is equivalent to the number of -v.
222
223       rpc-verbosity
224              Value which is equivalent to the number of -r.
225
226       use-memcache
227              A Boolean flag equivalent to -M.
228
229       use-machine-creds
230              A  Boolean flag. Setting to false is equivalent to giving the -n
231              flag.
232
233       avoid-dns
234              Setting to false is equivalent to providing the -D flag.
235
236       limit-to-legacy-enctypes
237              Equivalent to -l.
238
239       context-timeout
240              Equivalent to -t.
241
242       rpc-timeout
243              Equivalent to -T.
244
245       keytab-file
246              Equivalent to -k.
247
248       cred-cache-directory
249              Equivalent to -d.
250
251       preferred-realm
252              Equivalent to -R.
253
254       upcall-timeout
255              Equivalent to -U.
256
257       cancel-timed-out-upcalls
258              Setting to true is equivalent to providing the -C flag.
259
260       set-home
261              Setting to false is equivalent to providing the -H flag.
262
263       In addtion, the following value is recognized from the  [general]  sec‐
264       tion:
265
266       pipefs-directory
267              Equivalent to -p.
268
269

SEE ALSO

271       rpc.svcgssd(8), kerberos(1), kinit(1), krb5.conf(5)
272

AUTHORS

274       Dug Song <dugsong@umich.edu>
275       Andy Adamson <andros@umich.edu>
276       Marius Aamodt Eriksen <marius@umich.edu>
277       J. Bruce Fields <bfields@umich.edu>
278
279
280
281                                  20 Feb 2013                      rpc.gssd(8)
Impressum