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