doc/man-pages/pod1/klog.pod

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