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