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.