doc: state klog.krb is obsolete
[openafs.git] / doc / man-pages / pod1 / klog.pod
1 =head1 NAME
2
3 klog, klog.krb - Authenticates with the Authentication Server
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<klog> [B<-x>] S<<< [B<-principal> <I<user name>>] >>>
11     [-password <I<user's password>>] S<<< [B<-cell> <I<cell name>>] >>>
12     S<<< [B<-servers> <I<explicit list of servers>>+] >>>
13     [B<-pipe>] [B<-silent>]
14     S<<< [B<-lifetime> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
15     [B<-setpag>] [B<-tmp>] [B<-help>]
16
17 B<klog> [B<-x>] S<<< [B<-pr> <I<user name>>] >>> S<<< [B<-pa> <I<user's password>>] >>>
18     S<<< [B<-c> <I<cell name>>] >>>  S<<< [B<-s> <I<explicit list of servers>>+] >>>
19     [B<-pi>] [B<-si>] S<<< [B<-l> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
20     [B<-se>] [B<-t>] [B<-h>]
21
22 B<klog.krb> [B<-x>] S<<< [B<-principal> <I<user name>>] >>>
23     [-password <I<user's password>>] S<<< [B<-cell> <I<cell name>>] >>>
24     S<<< [B<-servers> <I<explicit list of servers>>+] >>>
25     [B<-pipe>] [B<-silent>]
26     S<<< [B<-lifetime> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
27     [B<-setpag>] [B<-tmp>] [B<-help>]
28
29 =for html
30 </div>
31
32 =head1 DESCRIPTION
33
34 The B<klog> and B<klog.krb> commands are obsolete and should not be used.
35 Instead, use B<kinit> followed by B<aklog> or B<klog.krb5>. See L<aklog(1)> and
36 L<klog.krb5(1)> for more information.
37
38 The B<klog> command obtains an AFS token from the obsolete Authentication
39 Server or a Kerberos KDC that speaks the same protocol, such as B<fakeka>
40 or a Heimdal Kerberos KDC. The Cache Manager on the local machine stores
41 the token in a credential structure in kernel memory and uses it when
42 obtaining authenticated access to the AFS filespace. This command does not
43 affect the issuer's identity (UNIX UID) in the local file system.
44
45 The B<klog.krb> command obtains an AFS token from the obsolete Authentication
46 Server or a Kerberos v4 KDC and also places the issuer's Kerberos v4 tickets
47 in the file named by the KRBTKFILE environment variable. The Kerberos v4 ticket
48 may used by Kerberos v4 aware programs.  The B<pagsh.krb> command defines the
49 KRBTKFILE environment variable as F</tmp/tktpI<X>> where I<X> is the number of
50 the user's PAG.
51
52 By default, the command interpreter obtains a token for the AFS user name
53 that matches the issuer's identity in the local file system. To specify an
54 alternate user, include the B<-principal> argument.  The user named by the
55 B<-principal> argument does not have to appear in the local password file
56 (the F</etc/passwd> file or equivalent).
57
58 By default, the command interpreter obtains a token for the local cell, as
59 defined by the AFSCELL environment variable set in the command shell or by
60 the F</usr/vice/etc/ThisCell> file on the local machine. To specify an
61 alternate cell, include the B<-cell> argument. The command interpreter
62 contacts an Authentication Server chosen at random from the cell's entry
63 in the local F</usr/afs/etc/CellServDB> file, unless the B<-servers>
64 argument is used to name one or more database server machines.
65
66 A user can have tokens in multiple cells simultaneously, but only one
67 token per cell per connection to the client machine. If the user's
68 credential structure already contains a token for the requested cell, the
69 token resulting from this command replaces it.
70
71 The lifetime of the token resulting from this command is the smallest of
72 the following.
73
74 =over 4
75
76 =item *
77
78 The lifetime specified by the issuer with the B<-lifetime> argument. If
79 the issuer does not include this argument, the value defaults to 720 hours
80 (30 days).
81
82 =item *
83
84 The maximum ticket lifetime recorded for the afs entry in the
85 Authentication Database. The default is 100 hours.
86
87 =item *
88
89 The maximum ticket lifetime recorded in the specified user's
90 Authentication Database entry. The default is 25 hours for user entries
91 created by an Authentication Server running AFS 3.1 or later.
92
93 =item *
94
95 The maximum ticket lifetime recorded in the krbtgt.I<CELLNAME> entry in
96 the Authentication Database; this entry corresponds to the ticket-granting
97 ticket used internally in generating the token. The default is 720 hours
98 (30 days).
99
100 =back
101
102 The output from the kas examine command displays an Authentication
103 Database entry's maximum ticket lifetime as C<Max ticket
104 lifetime>. Administrators can display any entry, and users can display
105 their own entries.
106
107 If none of the defaults have been changed, the token lifetime is 25 hours
108 for user accounts created by an Authentication Server running AFS 3.1 or
109 higher. The maximum lifetime for any token is 720 hours (30 days), and the
110 minimum is 5 minutes.
111
112 Between the minimum and maximum values, the Authentication Server uses a
113 defined set of values, according to the following rules. Requested
114 lifetimes between 5 minutes and 10 hours 40 minutes are granted at 5
115 minute intervals, rounding up. For example, if the issuer requests a
116 lifetime of 12 minutes, the token's actual lifetime is 15 minutes.
117
118 For token lifetimes greater than 10 hours 40 minutes, consult the
119 following table, which presents all the possible times in units of
120 I<hours>B<:>I<minutes>B<:>I<seconds>.  The number in parentheses is an
121 approximation of the corresponding time in days and hours (as indicated by
122 the C<d> and C<h> letters). For example, C<282:22:17> means 282 hours, 22
123 minutes, and 17 seconds, which translates to approximately 11 days and 18
124 hours (C<11d 18h>). The Authentication Server rounds up a requested
125 lifetime to the next highest possible lifetime.
126
127    11:24:15 (0d 11h)    46:26:01 (1d 22h)  189:03:38 (7d 21h)
128    12:11:34 (0d 12h)    49:38:40 (2d 01h)  202:08:00 (8d 10h)
129    13:02:09 (0d 13h)    53:04:37 (2d 05h)  216:06:35 (9d 00h)
130    13:56:14 (0d 13h)    56:44:49 (2d 08h)  231:03:09 (9d 15h)
131    14:54:03 (0d 14h)    60:40:15 (2d 12h)  247:01:43 (10d 07h)
132    15:55:52 (0d 15h)    64:51:57 (2d 16h)  264:06:34 (11d 00h)
133    17:01:58 (0d 17h)    69:21:04 (2d 21h)  282:22:17 (11d 18h)
134    18:12:38 (0d 18h)    74:08:46 (3d 02h)  301:53:45 (12d 13h)
135    19:28:11 (0d 19h)    79:16:23 (3d 07h)  322:46:13 (13d 10h)
136    20:48:57 (0d 20h)    84:45:16 (3d 12h)  345:05:18 (14d 09h)
137    22:15:19 (0d 22h)    90:36:53 (3d 18h)  368:56:58 (15d 08h)
138    23:47:38 (0d 23h)    96:52:49 (4d 00h)  394:27:37 (16d 10h)
139    25:26:21 (1d 01h)   103:34:45 (4d 07h)  421:44:07 (17d 13h)
140    27:11:54 (1d 03h)   110:44:28 (4d 14h)  450:53:46 (18d 18h)
141    29:04:44 (1d 05h)   118:23:54 (4d 22h)  482:04:24 (20d 02h)
142    31:05:22 (1d 07h)   126:35:05 (5d 06h)  515:24:22 (21d 11h)
143    33:14:21 (1d 09h)   135:20:15 (5d 15h)  551:02:38 (22d 23h)
144    35:32:15 (1d 11h)   144:41:44 (6d 00h)  589:08:45 (24d 13h)
145    37:59:41 (1d 13h)   154:42:01 (6d 10h)  629:52:56 (26d 05h)
146    40:37:19 (1d 16h)   165:23:50 (6d 21h)  673:26:07 (28d 01h)
147    43:25:50 (1d 19h)   176:50:01 (7d 08h)
148
149 =head1 CAUTIONS
150
151 B<klog> speaks a protocol specific to the obsolete Authentication Server
152 and is provided primarily to support cells that have not yet migrated to a
153 Kerberos version 5 KDC. It is still useful at cells not running the
154 Authentication Server if the associated Kerberos realm supports
155 Authentication Server queries (such as a Heimdal KDC or B<fakeka>), but
156 using B<klog.krb5> or B<kinit> plus B<aklog> instead of this command is
157 recommended.
158
159 By default, this command does not create a new process authentication
160 group (PAG); see the description of the B<pagsh> command to learn about
161 PAGs. If a cell does not use an AFS-modified login utility, users must
162 include B<-setpag> option to this command, or issue the B<pagsh> command
163 before this one, to have their tokens stored in a credential structure
164 that is identified by PAG rather than by local UID.
165
166 When a credential structure is identified by local UID, the potential
167 security exposure is that the local superuser C<root> can use the UNIX
168 B<su> command to assume any other identity and automatically inherit the
169 tokens associated with that UID. Identifying the credential structure by
170 PAG eliminates this exposure.
171
172 If the B<-password> argument is used, the specified password cannot begin
173 with a hyphen, because it is interpreted as another option name.  Use of
174 the B<-password> argument is not recommended in any case.
175
176 By default, it is possible to issue this command on a properly configured
177 NFS client machine that is accessing AFS via the NFS/AFS Translator,
178 assuming that the NFS client machine is a supported system type. However,
179 if the translator machine's administrator has enabled UID checking by
180 including the B<-uidcheck on> argument to the B<fs exportafs> command, the
181 command fails with an error message similar to the following:
182
183    Warning: Remote pioctl to <translator_machine> has failed (err=8). . .
184    Unable to authenticate to AFS because a pioctl failed.
185
186 Enabling UID checking means that the credential structure in which tokens
187 are stored on the translator machine must be identified by a UID that
188 matches the local UID of the process that is placing the tokens in the
189 credential structure. After the B<klog> command interpreter obtains the
190 token on the NFS client, it passes it to the remote executor daemon on the
191 translator machine, which makes the system call that stores the token in a
192 credential structure on the translator machine. The remote executor
193 generally runs as the local superuser C<root>, so in most cases its local
194 UID (normally zero) does not match the local UID of the user who issued
195 the B<klog> command on the NFS client machine.
196
197 Issuing the B<klog> command on an NFS client machine creates a security
198 exposure: the command interpreter passes the token across the network to
199 the remote executor daemon in clear text mode.
200
201 =head1 OPTIONS
202
203 =over 4
204
205 =item B<-x>
206
207 Appears only for backwards compatibility. Its former function is now the
208 default behavior of this command.
209
210 =item B<-principal> <I<user name>>
211
212 Specifies the user name to authenticate. If this argument is omitted, the
213 Authentication Server attempts to authenticate the user logged into the
214 local system.
215
216 =item B<-password> <I<user's password>>
217
218 Specifies the issuer's password (or that of the alternate user identified
219 by the B<-principal> argument). Omit this argument to have the command
220 interpreter prompt for the password, in which case it does not echo
221 visibly in the command shell.
222
223 =item B<-cell> <I<cell name>>
224
225 Specifies the cell for which to obtain a token. The command is directed to
226 that cell's Authentication Servers. During a single login session on a
227 given machine, a user can be authenticated in multiple cells
228 simultaneously, but can have only one token at a time for each of them
229 (that is, can only authenticate under one identity per cell per session on
230 a machine). It is acceptable to abbreviate the cell name to the shortest
231 form that distinguishes it from the other cells listed in the
232 F</usr/vice/etc/CellServDB> file on the client machine on which the
233 command is issued.
234
235 If this argument is omitted, the command is executed in the local cell, as
236 defined
237
238 =over 4
239
240 =item *
241
242 First, by the value of the environment variable AFSCELL.
243
244 =item *
245
246 Second, in the F</usr/vice/etc/ThisCell> file on the client machine on
247 which the command is issued.
248
249 =back
250
251 =item B<-servers> <I<explicit list of servers>>+
252
253 Establishes a connection with the Authentication Server running on each
254 specified database server machine. The command interpreter then chooses
255 one of these at random to execute the command. It is best to provide
256 fully-qualified hostnames, but abbreviated forms are possibly acceptable
257 depending on the state of the cell's name server at the time the command
258 is issued. This option is useful for testing specific servers if problems
259 are encountered.
260
261 If this argument is omitted, the command interpreter establishes a
262 connection with each machine listed for the indicated cell in the local
263 copy of the F</usr/vice/etc/CellServDB> file, and then chooses one of them
264 at random for command execution.
265
266 =item B<-pipe>
267
268 Suppresses all output to the standard output stream, including prompts and
269 error messages. The B<klog> command interpreter expects to receive the
270 password from the standard input stream. Do not use this argument; it is
271 designed for use by application programs rather than human users.
272
273 =item B<-silent>
274
275 Suppresses some of the trace messages that the klog command produces on
276 the standard output stream by default. It still reports on major problems
277 encountered.
278
279 =item B<-lifetime> <I<ticket lifetime>
280
281 Requests a specific lifetime for the token. Provide a number of hours and
282 optionally minutes and seconds in the format I<hh>[B<:>I<mm>[B<:>I<ss>]].
283 The value is used in calculating the token lifetime as described in
284 L</DESCRIPTION>.
285
286 =item B<-setpag>
287
288 Creates a process authentication group (PAG) prior to requesting
289 authentication. The token is associated with the newly created PAG.
290
291 =item B<-tmp>
292
293 Creates a Kerberos-style ticket file in the F</tmp> directory of the local
294 machine. The file is called F<tkt.I<AFS_UID>> where I<AFS_UID> is the AFS
295 UID of the issuer.
296
297 =item B<-help>
298
299 Prints the online help for this command. All other valid options are
300 ignored.
301
302 =back
303
304 =head1 OUTPUT
305
306 The following message indicates that the limit on consecutive
307 authentication failures has been exceeded. An administrator can use the
308 B<kas unlock> command to unlock the account, or the issuer can wait until
309 the lockout time for the account has passed. (The time is set with the
310 B<-locktime> argument to the B<kas setfields> command and displayed in the
311 output from the B<kas examine> command).
312
313    Unable to authenticate to AFS because ID is locked - see your system admin
314
315 If the B<-tmp> flag is included, the following message confirms that a
316 Kerberos-style ticket file was created:
317
318    Wrote ticket file to /tmp
319
320 =head1 EXAMPLES
321
322 Most often, this command is issued without arguments. The appropriate
323 password is for the person currently logged into the local system. The
324 ticket's lifetime is calculated as described in L</DESCRIPTION> (if no
325 defaults have been changed, it is 25 hours for a user whose Authentication
326 Database entry was created in AFS 3.1 or later).
327
328    % klog
329    Password:
330
331 The following example authenticates the user as admin in the Example
332 Corporation's test cell:
333
334    % klog -principal admin -cell test.example.com
335    Password:
336
337 In the following, the issuer requests a ticket lifetime of 104 hours 30
338 minutes (4 days 8 hours 30 minutes). Presuming that this lifetime is
339 allowed by the maximum ticket lifetimes and other factors described in
340 L</DESCRIPTION>, the token's lifetime is 110:44:28, which is the next
341 largest possible value.
342
343    % klog -lifetime 104:30
344    Password:
345
346 =head1 PRIVILEGE REQUIRED
347
348 None
349
350 =head1 SEE ALSO
351
352 L<fs_exportafs(1)>,
353 L<kas_examine(8)>,
354 L<kas_setfields(8)>,
355 L<kas_unlock(8)>,
356 L<kaserver(8)>,
357 L<pagsh(1)>,
358 L<tokens(1)>
359
360 =head1 COPYRIGHT
361
362 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
363
364 This documentation is covered by the IBM Public License Version 1.0.  It was
365 converted from HTML to POD by software written by Chas Williams and Russ
366 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.