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.