fb3ab9788260d19a37d405b697bab7d390375091
[nfs-utils.git] / utils / gssd / gssd.man
1 .\"
2 .\" rpc.gssd(8)
3 .\"
4 .\" Copyright (C) 2003 J. Bruce Fields <bfields@umich.edu>
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 [ \-fMnlvr ]
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 [ \-R
21 .IR realm ]
22 .SH INTRODUCTION
23 The RPCSEC_GSS protocol, defined in RFC 5403, is used to provide
24 strong security for RPC-based protocols such as NFS.
25 .P
26 Before exchanging RPC requests using RPCSEC_GSS, an RPC client must
27 establish a GSS
28 .IR "security context" .
29 A security context is shared state on each
30 end of a network transport that enables GSS-API security services.
31 .P
32 Security contexts are established using
33 .IR "security credentials" .
34 A credential grants temporary access to a secure network service,
35 much as a railway ticket grants temporary access to use a rail service.
36 .P
37 A user typically obtains a credential by providing a password to the
38 .BR kinit (1)
39 command, or via a PAM library at login time.
40 A credential acquired with a
41 .I user principal
42 is known as a
43 .I user credential
44 (see
45 .BR kerberos (1)
46 for more on principals).
47 .P
48 For certain operations, a credential is required
49 which represents no user,
50 is otherwise unprivileged,
51 and is always available.
52 This is referred to as a
53 .IR "machine credential" .
54 .P
55 Machine credentials are typically established using a
56 .IR "service principal" ,
57 whose encrypted password, called its
58 .IR key ,
59 is stored in a file, called a
60 .IR keytab ,
61 to avoid requiring a user prompt.
62 A machine credential effectively does not expire because the system
63 can renew it as needed without user intervention.
64 .P
65 Once obtained, credentials are typically stored in local temporary files
66 with well-known pathnames.
67 .SH DESCRIPTION
68 To establish GSS security contexts using these credential files,
69 the Linux kernel RPC client depends on a userspace daemon called
70 .BR rpc.gssd .
71 The
72 .B rpc.gssd
73 daemon uses the rpc_pipefs filesystem to communicate with the kernel.
74 .SH OPTIONS
75 .TP
76 .B -f
77 Runs
78 .B rpc.gssd
79 in the foreground and sends output to stderr (as opposed to syslogd)
80 .TP
81 .B -n
82 By default,
83 .B rpc.gssd
84 treats accesses by the user with UID 0 specially, and uses
85 "machine credentials" for all accesses by that user which
86 require Kerberos authentication.
87 With the \-n option, "machine credentials" will not be used
88 for accesses by UID 0.  Instead, credentials must be obtained
89 manually like all other users.  Use of this option means that
90 "root" must manually obtain Kerberos credentials before
91 attempting to mount an nfs filesystem requiring Kerberos
92 authentication.
93 .TP
94 .BI "-k " keytab
95 Tells
96 .B rpc.gssd
97 to use the keys found in
98 .I keytab
99 to obtain "machine credentials".
100 The default value is
101 .I /etc/krb5.keytab.
102 .IP
103 Previous versions of
104 .B rpc.gssd
105 used only "nfs/*" keys found within the keytab.
106 To be more consistent with other implementations, we now look for
107 specific keytab entries.  The search order for keytabs to be used
108 for "machine credentials" is now:
109 .br
110   <HOSTNAME>$@<REALM>
111 .br
112   root/<hostname>@<REALM>
113 .br
114   nfs/<hostname>@<REALM>
115 .br
116   host/<hostname>@<REALM>
117 .br
118   root/<anyname>@<REALM>
119 .br
120   nfs/<anyname>@<REALM>
121 .br
122   host/<anyname>@<REALM>
123 .IP
124 If this search order does not use the correct key then provide a
125 keytab file that contains only correct keys.
126 .TP
127 .B -l
128 Tells
129 .B rpc.gssd
130 to limit session keys to Single DES even if the kernel supports stronger
131 encryption types. Service ticket encryption is still governed by what
132 the KDC believes the target server supports. This way the client can
133 access a server that has strong keys in its keytab for ticket decryption
134 but whose kernel only supports Single DES.
135 .IP
136 The alternative is to put only Single DES keys in the server's keytab
137 and limit encryption types for its principal to Single DES on the KDC
138 which will cause service tickets for this server to be encrypted using
139 only Single DES and (as a side-effect) contain only Single DES session
140 keys.
141 .IP
142 This legacy behaviour is only required for older servers
143 (pre nfs-utils-1.2.4). If the server has a recent kernel, Kerberos
144 implementation and nfs-utils it will work just fine with stronger
145 encryption.
146 .IP
147 .B Note:
148 This option is only available with Kerberos libraries that 
149 support setable encryption types.
150 .TP
151 .BI "-p " path
152 Tells
153 .B rpc.gssd
154 where to look for the rpc_pipefs filesystem.  The default value is
155 .IR /var/lib/nfs/rpc_pipefs .
156 .TP
157 .BI "-d " search-path
158 This option specifies a colon separated list of directories that
159 .B rpc.gssd
160 searches for credential files.  The default value is
161 .IR /tmp:/run/user/%U .
162 The literal sequence "%U" can be specified to substitue the UID
163 of the user for whom credentials are being searched.
164 .TP
165 .B -M
166 By default, machine credentials are stored in files in the first
167 directory in the credential directory search path (see the
168 .B -d
169 option).  When
170 .B -M
171 is set,
172 .B rpc.gssd
173 stores machine credentials in memory instead.
174 .TP
175 .B -v
176 Increases the verbosity of the output (can be specified multiple times).
177 .TP
178 .B -r
179 If the RPCSEC_GSS library supports setting debug level,
180 increases the verbosity of the output (can be specified multiple times).
181 .TP
182 .BI "-R " realm
183 Kerberos tickets from this
184 .I realm
185 will be preferred when scanning available credentials cache files to be
186 used to create a context.  By default, the default realm, as configured
187 in the Kerberos configuration file, is preferred.
188 .TP
189 .BI "-t " timeout
190 Timeout, in seconds, for kernel GSS contexts. This option allows you to force 
191 new kernel contexts to be negotiated after
192 .I timeout
193 seconds, which allows changing Kerberos tickets and identities frequently.
194 The default is no explicit timeout, which means the kernel context will live
195 the lifetime of the Kerberos service ticket used in its creation.
196 .SH SEE ALSO
197 .BR rpc.svcgssd (8),
198 .BR kerberos (1),
199 .BR kinit (1),
200 .BR krb5.conf (5)
201 .SH AUTHORS
202 .br
203 Dug Song <dugsong@umich.edu>
204 .br
205 Andy Adamson <andros@umich.edu>
206 .br
207 Marius Aamodt Eriksen <marius@umich.edu>
208 .br
209 J. Bruce Fields <bfields@umich.edu>