doc/man-pages/pod1/klog.pod

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