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 [-DfMnlvr] [-k keytab] [-p pipefsdir] [-d ccachedir] [-t time‐
10       out] [-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
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
21       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
25       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
30       For  certain  operations,  a credential is required which represents no
31       user, is otherwise unprivileged, and  is  always  available.   This  is
32       referred to as a machine credential.
33
34       Machine  credentials  are typically established using a service princi‐
35       pal, whose encrypted password, called its key, is  stored  in  a  file,
36       called  a  keytab, to avoid requiring a user prompt.  A machine creden‐
37       tial effectively does not expire because the system  can  renew  it  as
38       needed without user intervention.
39
40       Once  obtained,  credentials  are  typically  stored in local temporary
41       files with well-known pathnames.
42

DESCRIPTION

44       To establish GSS security contexts using these  credential  files,  the
45       Linux  kernel RPC client depends on a userspace daemon called rpc.gssd.
46       The rpc.gssd daemon uses the rpc_pipefs filesystem to communicate  with
47       the kernel.
48
49   User Credentials
50       When a user authenticates using a command such as kinit(1), the result‐
51       ing credential is stored in a file with a well-known  name  constructed
52       using the user's UID.
53
54       To  interact  with  an  NFS  server on behalf of a particular Kerberos-
55       authenticated user, the Linux kernel RPC client requests that  rpc.gssd
56       initialize  a  security context with the credential in that user's cre‐
57       dential file.
58
59       Typically, credential files are placed in /tmp.  However, rpc.gssd  can
60       search  for  credential  files  in  more  than  one directory.  See the
61       description of the -d option for details.
62
63   Machine Credentials
64       A user credential is established by a user and is then shared with  the
65       kernel  and  rpc.gssd.  A machine credential is established by rpc.gssd
66       for the kernel when there is no user.  Therefore rpc.gssd must  already
67       have the materials on hand to establish this credential without requir‐
68       ing user intervention.
69
70       rpc.gssd searches the local system's keytab for a principal and key  to
71       use  to establish the machine credential.  By default, rpc.gssd assumes
72       the file /etc/krb5.keytab contains principals and keys that can be used
73       to obtain machine credentials.
74
75       rpc.gssd  searches  in the following order for a principal to use.  The
76       first matching credential is used.   For  the  search,  <hostname>  and
77       <REALM>  are  replaced  with  the  local system's hostname and Kerberos
78       realm.
79
80          <HOSTNAME>$@<REALM>
81          root/<hostname>@<REALM>
82          nfs/<hostname>@<REALM>
83          host/<hostname>@<REALM>
84          root/<anyname>@<REALM>
85          nfs/<anyname>@<REALM>
86          host/<anyname>@<REALM>
87
88       The <anyname> entries match on the service name and realm,  but  ignore
89       the  hostname.   These  can  be  used if a principal matching the local
90       host's name is not found.
91
92       Note that the first principal in the search order is a  user  principal
93       that  enables  Kerberized  NFS  when  the  local system is joined to an
94       Active Directory domain using Samba.  A  password  for  this  principal
95       must be provided in the local system's keytab.
96
97       You   can   specify   another   keytab   by  using  the  -k  option  if
98       /etc/krb5.keytab does not exist or does not provide one of these  prin‐
99       cipals.
100
101   Credentials for UID 0
102       UID 0 is a special case.  By default rpc.gssd uses the system's machine
103       credentials for UID 0 accesses that require GSS  authentication.   This
104       limits the privileges of the root user when accessing network resources
105       that require authentication.
106
107       Specify the -n option when starting rpc.gssd if you'd like to force the
108       root  user  to  obtain a user credential rather than use the local sys‐
109       tem's machine credential.
110
111       When -n is specified, the kernel continues to  request  a  GSS  context
112       established  with  a  machine  credential for NFSv4 operations, such as
113       SETCLIENTID or RENEW, that manage state.  If rpc.gssd cannot  obtain  a
114       machine  credential (say, the local system has no keytab), NFSv4 opera‐
115       tions that require machine credentials will fail.
116
117   Encryption types
118       A realm administrator can choose to add keys encoded  in  a  number  of
119       different encryption types to the local system's keytab.  For instance,
120       a host/ principal might  have  keys  for  the  aes256-cts-hmac-sha1-96,
121       aes128-cts-hmac-sha1-96,  des3-cbc-sha1,  and  arcfour-hmac  encryption
122       types.  This permits rpc.gssd to choose an appropriate encryption  type
123       that the target NFS server supports.
124
125       These  encryption  types are stronger than legacy single-DES encryption
126       types.  To interoperate in environments where servers support only weak
127       encryption  types,  you can restrict your client to use only single-DES
128       encryption types by specifying the -l option when starting rpc.gssd.
129

OPTIONS

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

CONFIGURATION FILE

208       Many of the options that can be set on the command  line  can  also  be
209       controlled   through   values   set   in  the  [gssd]  section  of  the
210       /etc/nfs.conf configuration file.  Values recognized include:
211
212       use-memcache
213              A Boolean flag equivalent to -M.
214
215       use-machine-creds
216              A Boolean flag. Setting to false is equivalent to giving the  -n
217              flag.
218
219       avoid-dns
220              Setting to false is equivalent to providing the -D flag.
221
222       limit-to-legacy-enctypes
223              Equivalent to -l.
224
225       context-timeout
226              Equivalent to -T.
227
228       rpc-timeout
229              Equivalent to -t.
230
231       keytab-file
232              Equivalent to -k.
233
234       cred-cache-directory
235              Equivalent to -d.
236
237       preferred-realm
238              Equivalent to -R.
239
240       In  addtion,  the following value is recognized from the [general] sec‐
241       tion:
242
243       pipefs-directory
244              Equivalent to -p.
245
246

SEE ALSO

248       rpc.svcgssd(8), kerberos(1), kinit(1), krb5.conf(5)
249

AUTHORS

251       Dug Song <dugsong@umich.edu>
252       Andy Adamson <andros@umich.edu>
253       Marius Aamodt Eriksen <marius@umich.edu>
254       J. Bruce Fields <bfields@umich.edu>
255
256
257
258                                  20 Feb 2013                      rpc.gssd(8)
Impressum