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