023deeef6f40851cae2277b6c11f3bbed6a6f239
[openafs.git] / doc / man-pages / pod1 / klog.krb5.pod
1 =head1 NAME
2
3 klog.krb5 - Authenticates to Kerberos and obtains a token
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<klog.krb5> [B<-x>] S<<< [B<-principal> <I<user name>>] >>>
11     [-password <I<user's password>>] S<<< [B<-cell> <I<cell name>>] >>>
12     S<<< [B<-k> <I<realm>>] >>> [B<-pipe>] [B<-silent>]
13     S<<< [B<-lifetime> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
14     [B<-setpag>] [B<-tmp>] [B<-noprdb>] [B<-unwrap>] [B<-help>]
15
16 B<klog.krb5> [B<-x>] S<<< [B<-pr> <I<user name>>] >>>
17     S<<< [B<-pa> <I<user's password>>] >>>
18     S<<< [B<-c> <I<cell name>>] >>>
19     B<<< [B<-k> <I<realm>>] >>> [B<-pi>] [B<-si>]
20     S<<< [B<-l> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
21     [B<-se>] [B<-t>] [B<-n>] [B<-u>] [B<-h>]
22
23 =for html
24 </div>
25
26 =head1 DESCRIPTION
27
28 The B<klog.krb5> command obtains a Kerberos v5 ticket from a Kerberos
29 KDC and, from the ticket, an AFS token and then stores it in the Cache
30 Manager.  The Cache Manager keeps the token in kernel memory and uses it
31 when obtaining authenticated access to the AFS filespace.  This command
32 does not affect the issuer's identity (UNIX UID) on the local file system.
33
34 By default, the command interpreter obtains a token for the AFS user name
35 that matches the issuer's local user name.  To specify an alternate user,
36 include the B<-principal> argument.  The user named by the B<-principal>
37 argument does not have to appear in the local password file (the
38 F</etc/passwd> file or equivalent).
39
40 By default, the command interpreter obtains a token for the local cell, as
41 defined by the AFSCELL environment variable set in the command shell or by
42 the F</usr/vice/etc/ThisCell> file on the local machine.  To specify an
43 alternate cell, include the B<-cell> argument.  A user can have tokens in
44 multiple cells simultaneously, but only one token per cell per connection
45 to the client machine.  If the user's credential structure already
46 contains a token for the requested cell, the token resulting from this
47 command replaces it.
48
49 By default, the command interpreter obtains a Kerberos ticket for the
50 local realm.  To specify a different Kerberos realm, include the B<-k>
51 argument.  The Kerberos realm name need not match the AFS cell name.
52 B<klog.krb5> will request a ticket for the principal C<afs/I<cell>> where
53 I<cell> is the cell name for which the user is requesting tokens, falling
54 back on the principal C<afs> if that principal does not work.
55
56 The lifetime of the token resulting from this command is the smallest of
57 the following:
58
59 =over 4
60
61 =item *
62
63 The lifetime specified by the issuer with the B<-lifetime> argument if
64 that argument was given.
65
66 =item *
67
68 The maximum ticket lifetime recorded for the C<afs/I<cell>> principal in
69 thet Kerberos database.
70
71 =item *
72
73 The maximum ticket lifetime recorded in the specified user's Kerberos
74 database entry.
75
76 =back
77
78 =head1 CAUTIONS
79
80 By default, this command does not create a new process authentication
81 group (PAG); see the description of the B<pagsh> command to learn about
82 PAGs.  If a cell does not use an AFS-modified login utility, users must
83 include B<-setpag> option to this command, or issue the B<pagsh> command
84 before this one, to have their tokens stored in a credential structure
85 that is identified by PAG rather than by local UID.  Users should be aware
86 that B<-setpag> will not work on some systems, most notably recent Linux
87 systems, and using B<pagsh> is preferrable and more reliable.
88
89 When a credential structure is identified by local UID, the potential
90 security exposure is that the local superuser C<root> can use the UNIX
91 B<su> command to assume any other identity and automatically inherit the
92 tokens associated with that UID.  Identifying the credential structure by
93 PAG makes it more difficult (but not impossible) for the local superuser
94 to obtain tokens of other users.
95
96 If the B<-password> argument is used, the specified password cannot begin
97 with a hyphen, because it is interpreted as another option name.  Use of
98 the B<-password> argument is not recommended in any case.
99
100 By default, it is possible to issue this command on a properly configured
101 NFS client machine that is accessing AFS via the NFS/AFS Translator,
102 assuming that the NFS client machine is a supported system type. However,
103 if the translator machine's administrator has enabled UID checking by
104 including the B<-uidcheck on> argument to the B<fs exportafs> command, the
105 command fails with an error message similar to the following:
106
107    Warning: Remote pioctl to <translator_machine> has failed (err=8). . .
108    Unable to authenticate to AFS because a pioctl failed.
109
110 Enabling UID checking means that the credential structure in which tokens
111 are stored on the translator machine must be identified by a UID that
112 matches the local UID of the process that is placing the tokens in the
113 credential structure.  After the B<klog.krb5> command interpreter obtains
114 the token on the NFS client, it passes it to the remote executor daemon on
115 the translator machine, which makes the system call that stores the token
116 in a credential structure on the translator machine.  The remote executor
117 generally runs as the local superuser C<root>, so in most cases its local
118 UID (normally zero) does not match the local UID of the user who issued
119 the B<klog.krb5> command on the NFS client machine.
120
121 Issuing the B<klog.krb5> command on an NFS client machine creates a
122 security exposure: the command interpreter passes the token across the
123 network to the remote executor daemon in clear text mode.
124
125 =head1 OPTIONS
126
127 =over 4
128
129 =item B<-x>
130
131 Appears only for backwards compatibility.  Its former function is now the
132 default behavior of this command.
133
134 =item B<-principal> <I<user name>>
135
136 Specifies the user name to authenticate.  If this argument is omitted, the
137 default value is the local user name.
138
139 =item B<-password> <I<user's password>>
140
141 Specifies the issuer's password (or that of the alternate user identified
142 by the B<-principal> argument).  Omit this argument to have the command
143 interpreter prompt for the password, in which case it does not echo
144 visibly in the command shell.
145
146 =item B<-cell> <I<cell name>>
147
148 Specifies the cell for which to obtain a token.  During a single login
149 session on a given machine, a user can be authenticated in multiple cells
150 simultaneously, but can have only one token at a time for each of them
151 (that is, can only authenticate under one identity per cell per session on
152 a machine).  It is acceptable to abbreviate the cell name to the shortest
153 form that distinguishes it from the other cells listed in the
154 F</usr/vice/etc/CellServDB> file on the client machine on which the
155 command is issued.
156
157 If this argument is omitted, the command is executed in the local cell, as
158 defined
159
160 =over 4
161
162 =item *
163
164 First, by the value of the environment variable AFSCELL.
165
166 =item *
167
168 Second, in the F</usr/vice/etc/ThisCell> file on the client machine on
169 which the command is issued.
170
171 =back
172
173 =item B<-k> <I<realm>>
174
175 Obtain tickets and tokens from the <I<realm>> Kerberos realm.  If this
176 option is not given, B<klog.krb5> defaults to using the default local
177 realm.  The Kerberos realm name need not match the AFS cell name.
178
179 =item B<-pipe>
180
181 Suppresses all output to the standard output stream, including prompts and
182 error messages. The B<klog.krb5> command interpreter expects to receive
183 the password from the standard input stream. Do not use this argument; it
184 is designed for use by application programs rather than human users.
185
186 =item B<-silent>
187
188 Suppresses some of the trace messages that the B<klog.krb5> command
189 produces on the standard output stream by default.  It still reports on
190 major problems encountered.
191
192 =item B<-lifetime> <I<ticket lifetime>
193
194 Requests a specific lifetime for the token.  Provide a number of hours and
195 optionally minutes and seconds in the format I<hh>[B<:>I<mm>[B<:>I<ss>]].
196
197 =item B<-setpag>
198
199 Creates a process authentication group (PAG) prior to requesting
200 authentication. The token is associated with the newly created PAG.
201
202 =item B<-tmp>
203
204 Creates a Kerberos-style ticket file rather than only obtaining tokens.
205 The ticket file will be stored in the default Kerberos ticket cache
206 location, which is usually in the F</tmp> directory of the local machine
207 (but depends on the Kerberos implementation used).
208
209 =item B<-noprdb>
210
211 By default, B<klog.krb5> looks up the user's AFS ID in the Protection
212 Server and associates the token with that AFS ID.  This is helpful when
213 looking at the output of commands like B<tokens> but is not required.  If
214 this option is given, this behavior is suppressed and B<klog.krb5> will
215 store the token under a generic name.  You may wish this if, for example,
216 you have problems contacting the Protection Server for an AFS cell for
217 some reason.
218
219 =item B<-unwrap>
220
221 Normally, B<klog.krb5> uses the Kerberos service ticket for the AFS
222 principal as the AFS token.  If this option is given, B<klog.krb5> creates
223 a different, simplified AFS token form based on the service ticket (the
224 so-called "rxkad 2b" token).  Normally, this is not necessary.  However,
225 if you are using older OpenAFS software that cannot handle large ticket
226 sizes in conjunction with Active Directory as the Kerberos server, using
227 B<-unwrap> can shrink the AFS token size so that older software can handle
228 it more easily.
229
230 =item B<-help>
231
232 Prints the online help for this command. All other valid options are
233 ignored.
234
235 =back
236
237 =head1 OUTPUT
238
239 If the B<-tmp> flag is included, the following message confirms that a
240 Kerberos ticket cache was created:
241
242    Wrote ticket file to /tmp/krb5cc_1000_rENJoZ
243
244 The path to the cache will vary, of course.
245
246 =head1 EXAMPLES
247
248 Most often, this command is issued without arguments. The appropriate
249 password is for the person currently logged into the local system.  The
250 ticket's lifetime is calculated as described in L</DESCRIPTION>.
251
252    % klog.krb5
253    Password for user@EXAMPLE.ORG:
254
255 The following example authenticates the user as admin in the Example
256 Corporation's test cell:
257
258    % klog.krb5 -principal admin -cell test.example.com
259    Password for admin@EXAMPLE.COM:
260
261 In the following, the issuer requests a ticket lifetime of 104 hours 30
262 minutes (4 days 8 hours 30 minutes).
263
264    % klog.krb5 -lifetime 104:30
265    Password for user@EXAMPLE.ORG:
266
267 =head1 PRIVILEGE REQUIRED
268
269 None
270
271 =head1 SEE ALSO
272
273 L<aklog(1)>,
274 L<fs_exportafs(1)>,
275 L<pagsh(1)>,
276 L<tokens(1)>
277
278 =head1 COPYRIGHT
279
280 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
281
282 This documentation is covered by the IBM Public License Version 1.0.  It
283 was converted from HTML to POD by software written by Chas Williams and
284 Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.