src/man/klog.1

   1 klog                       AFS Commands                    klog
   2
   3
   4 NAME
   5
   6    klog -- authenticate  with  Authentication Server to obtain
   7
   8                        token.
   9
  10
  11    klog [-x]  [-principal <user name>]  [-password <user's
  12    password>]
  13    [-tmp]  [-cell <cell name>]  [-servers <explicit list of
  14            +
  15    servers> ]
  16    [-pipe]  [-lifetime <ticket lifetime in hh[:mm[:ss]]>]
  17    [-help]
  18
  19 ACCEPTABLE ABBREVIATIONS/ALIASES
  20
  21    klog [-x]  [-pr <user name>]  [-pa <user's password>] [-t]
  22    [-c <cell name>]
  23                                  +
  24    [-s <explicit list of servers> ]  [-pi]
  25    [-l <ticket lifetime in hh[:mm[:ss]]>]  [-h]
  26
  27 DESCRIPTION
  28
  29    Authenticates the issuer in the indicated cell.  The  issuer
  30    obtains a token accepted by the AFS server processes in that
  31    cell.  The Cache Manager stores the token  in  a  credential
  32    structure associated with the issuer.  If the issuer already
  33    has a token for the cell,  the  token  resulting  from  this
  34    command replaces it in the credential structure.
  35
  36    By default, the token generated is appropriate for the local
  37    cell (the one to  which  the  local  machine  belongs):  the
  38    command interpreter contacts an Authentication Server in the
  39    local  cell,   chosen   at   random   from   the   list   in
  40    /usr/vice/etc/CellServDB,  and  requests  a  token  for  the
  41    issuer logged into the local machine.  Use  the  -principal,
  42    -cell  and/or  -servers  arguments  to  specify  a different
  43    identity,   cell   or   set   of   Authentication    Servers
  44    respectively.     See  the  ARGUMENTS  section  for  further
  45    explanation.
  46
  47    This command does not change the identity  under  which  the
  48    issuer is logged into the local UNIX file system.
  49
  50    The issuer (or user indicated with -principal) does not have
  51    to  appear  in  the  local  password  file  (/etc/passwd  or
  52    equivalent)  to  issue this command; in previous versions of
  53    this command, users had to add the -x flag if they  did  not
  54    appear in that file.
  55
  56    During  a  single  login  on  a given machine, a user can be
  57    authenticated in multiple cells simultaneously, but can have
  58    only  one  token  at  a  time  for each cell (i.e., can only
  59    authenticate under one identity per cell).
  60
  61    The lifetime of the token resulting from this command is the
  62    smallest of the following:
  63
  64       - the  lifetime  requested  by  the  issuer with the
  65
  66
  67
  68         -lifetime  argument.    If  the  issuer  does  not
  69         include  this  argument, the value defaults to 720
  70         hours (30 days).
  71
  72       - the "maximum  ticket  lifetime"  recorded  in  the
  73         "afs"  entry  in the Authentication Database.  The
  74         default is 100 hours.  Administrators can  inspect
  75         this  value using kas examine, and change it using
  76         kas setfields.
  77
  78       - the "maximum  ticket  lifetime"  recorded  in  the
  79         issuer's   Authentication  Database  entry.    The
  80         default is 25 hours for user  entries  created  by
  81         the AFS 3.1 or later version of the Authentication
  82         Server, and 100 hours for user entries created  by
  83         the  AFS 3.0 version of the Authentication Server.
  84         Administrators and the  user  himself/herself  can
  85         inspect   this   value   using   kas examine,  and
  86         administrators can change it using kas setfields.
  87
  88       - the "maximum  ticket  lifetime"  recorded  in  the
  89         "krbtgt.CELLNAME"   entry  in  the  Authentication
  90         Database; this entry corresponds  to  the  ticket-
  91         granting  ticket used internally in generating the
  92         token.  The default is 720 hours (30 days).
  93
  94    If none of  these  defaults  have  been  changed,  then  the
  95    standard   token  lifetime  is  25  hours  for  users  whose
  96    Authentication Database entries were created by the AFS  3.1
  97    or later version of the Authentication Server, and 100 hours
  98    for users whose Authentication Database entries were created
  99    by  the  AFS  3.0 version of the Authentication Server.  The
 100    user can issue klog to request  a  token  with  a  different
 101    lifetime.
 102
 103    The  maximum  lifetime for any token is 720 hours (30 days),
 104    and the minimum is 5 minutes.  Between these  values,  token
 105    lifetimes  are  not  granted on a linear scale; only certain
 106    values are possible.
 107
 108    Lifetimes between 5 minutes and  10  hours  40  minutes  are
 109    granted  at 5 minute intervals, rounding up. For example, if
 110    the issuer requests a lifetime of 12  minutes,  the  token's
 111    actual lifetime is 15 minutes.
 112
 113    For  token  lifetimes  greater  than  10  hours  40 minutes,
 114    consult the following table,  which  presents  the  possible
 115    times  in  units  of  hours:minutes:seconds.  The  number in
 116    parentheses is a translation to daysd  hoursh;  the  minutes
 117    and  seconds  are  the  same  as in the corresponding hourly
 118    time.  For example, 282:22:17 means 282  hours,  22  minutes
 119    and  17 seconds, which translates to 11d 18h (11 days and 18
 120    hours, etc.).  If the issuer requests a lifetime between two
 121    values,  the  token's  lifetime  is rounded up to the higher
 122    value.
 123
 124       11:24:15 (0d 11h)             33:14:21 (1d 09h)
 125       12:11:34 (0d 12h)             35:32:15 (1d 11h)
 126       13:02:09 (0d 13h)             37:59:41 (1d 13h)
 127       13:56:14 (0d 13h)             40:37:19 (1d 16h)
 128       14:54:03 (0d 14h)             43:25:50 (1d 19h)
 129
 130
 131
 132       15:55:52 (0d 15h)             46:26:01 (1d 22h)
 133       17:01:58 (0d 17h)             49:38:40 (2d 01h)
 134       18:12:38 (0d 18h)             53:04:37 (2d 05h)
 135       19:28:11 (0d 19h)             56:44:49 (2d 08h)
 136       20:48:57 (0d 20h)             60:40:15 (2d 12h)
 137       22:15:19 (0d 22h)             64:51:57 (2d 16h)
 138       23:47:38 (0d 23h)             69:21:04 (2d 21h)
 139       25:26:21 (1d 01h)             74:08:46 (3d 02h)
 140       27:11:54 (1d 03h)             79:16:23 (3d 07h)
 141       29:04:44 (1d 05h)             84:45:16 (3d 12h)
 142       31:05:22 (1d 07h)             90:36:53 (3d 18h)
 143
 144 WARNING
 145
 146    This command does not create a new  "process  authentication
 147    group" (commonly abbreviated PAG; see the description of the
 148    pagsh command in this chapter to learn about PAGs).    Users
 149    in  cells  not  using  the AFS version of login should issue
 150    pagsh before issuing this command, so that  the  tokens  get
 151    stored  in  a credential structure that is identified by PAG
 152    rather than UNIX UID.  The potential security problem with a
 153    credential  structure  identified  by  UID  is  that  anyone
 154    already logged in as "root"  on  a  machine  is  allowed  to
 155    assume  any other identity by issuing su.  If the credential
 156    structure is identified by UID rather than  PAG,  then  when
 157    "root"  assumes  another UID it can use the token, too.  Use
 158    of a PAG as an identifier eliminates that possibility.
 159
 160    If the issuer entered the current session by issuing the AFS
 161    login  command,  his  or her credential structure is already
 162    identified by a PAG.  Issuing klog during the  same  session
 163    creates a new token associated with the existing PAG.
 164
 165 ARGUMENTS
 166
 167    -x        appears  only  for  backwards  compatibility.  Its
 168              former function is now  the  default  behavior  of
 169              this  command,  as  mentioned  in  the DESCRIPTION
 170              section.
 171
 172    -principal
 173              is  the user name under which the issuer wishes to
 174              authenticate.    By  default,  the  Authentication
 175              Server  attempts  to  authenticate the user logged
 176              into the local machine's UNIX file system.    This
 177              argument  allows the issuer to specify a different
 178              user name.
 179
 180    -password specifies the issuer's password (or that  of  user
 181              name  if  principal  is  provided).    Use of this
 182              argument is STRONGLY DISCOURAGED, as it makes  the
 183              password  visible  on  the  command  line.  If the
 184              issuer omits this argument, klog prompts  for  the
 185              password and does not echo it visibly:
 186
 187              Password: <user's password>
 188
 189    -tmp      indicates  that  a  copy  of  the "ticket-granting
 190              ticket" should be placed in a file  on  the  local
 191              machine's  /tmp  directory.    The  file is called
 192              /tmp/tktUnix_UID (example for user with  UNIX  UID
 193
 194
 195
 196              1000: /tmp/tkt1000).
 197
 198              The  ticket-granting  ticket  is  an  intermediate
 199              ticket that the Ticket Granting  Service  requires
 200              of  clients  who  desire server tickets (the extra
 201              level of indirection increases security).  Putting
 202              the   ticket-granting   ticket  into  /tmp  allows
 203              standard Kerberos applications to  access  it  and
 204              use it for obtaining server tickets.  If this flag
 205              is  omitted,  the  Cache  Manager   discards   the
 206              ticket-granting  ticket  after  it obtains the AFS
 207              server ticket.
 208
 209    -cell     specifies the cell in which the issuer  wishes  to
 210              authenticate,  by  directing  the  command to that
 211              cell's Authentication Servers.   During  a  single
 212              login   on   a   given  machine,  a  user  may  be
 213              authenticated in  multiple  cells  simultaneously,
 214              but  can have only one token at a time for each of
 215              them  (i.e.,  can  only  authenticate  under   one
 216              identity per cell per machine).
 217
 218              If  this  argument  is  omitted,  the  command  is
 219              executed  in  the  local  cell,  as   defined   in
 220              /usr/vice/etc/ThisCell  on  the  client machine on
 221              which the command  is  issued.    The  issuer  may
 222              abbreviate  cell  name  to  the shortest form that
 223              distinguishes it from the other  cells  listed  in
 224              /usr/vice/etc/CellServDB  on the client machine on
 225              which the command is issued.
 226
 227    -servers  causes the  command  interpreter  to  establish  a
 228              connection  with the Authentication Server running
 229              on each specified database  server  machine.    It
 230              then chooses one of these at random to execute the
 231              command.  The command  accepts  shortened  machine
 232              names,   but   exactly   which  abbreviations  are
 233              acceptable depends on the state of the cell's name
 234              server at the time the command is issued.
 235
 236              If   this   argument   is   omitted,  the  command
 237              interpreter establishes  a  connection  with  each
 238              machine listed for the indicated cell in the local
 239              workstation's  copy  of  /usr/vice/etc/CellServDB,
 240              and  then  chooses  one  of  those  at  random for
 241              command execution.
 242
 243              This option is useful for testing specific servers
 244              if problems are encountered.
 245
 246    -pipe     indicates  that  the  command  should  run without
 247              printing anything on the screen, including prompts
 248              or  error  messages.  The klog command interpreter
 249              Server  expects  to  receive  the  password   from
 250              standard input (stdin).  The issuer is discouraged
 251              from  using  this  argument;  it  is  for  use  by
 252              application programs rather than human users.
 253
 254    -lifetime indicates  the lifetime that the issuer wishes the
 255              token to have.  The value provided  is  considered
 256              in  the  lifetime  calculation  described  in  the
 257
 258
 259
 260              DESCRIPTION section above, along with the  maximum
 261              ticket lifetimes mentioned there.  The DESCRIPTION
 262              section also explains how the actual  lifetime  of
 263              the  token  is determined, since not all times are
 264              possible.  If this argument is  not  provided,  it
 265              defaults  to 720 hours.  The format for specifying
 266              the lifetime is
 267
 268                 hh[:mm[:ss]]
 269
 270              Legal values for hh (hours) range from 00  through
 271              720.    Legal  values  for  mm and ss (minutes and
 272              seconds) range from 00 through 59.
 273
 274    -help     prints the online help for this command.   Do  not
 275              provide  any  other  arguments  or flags with this
 276              one.
 277
 278 EXAMPLES
 279
 280    Most often, this command is issued without arguments.    The
 281    appropriate password is for the person currently logged into
 282    the local UNIX  file  system.    The  ticket's  lifetime  is
 283    calculated as described in the DESCRIPTION section above (if
 284    no defaults have been changed, it is 25  hours  for  a  user
 285    whose  Authentication  Database entry was created by the AFS
 286    3.1 or later version of the Authentication Server, 100 hours
 287    for  a  user whose Authentication Database entry was created
 288    with the AFS 3.0 version).
 289
 290    % klog  Password:
 291
 292    The following allows the issuer working on a machine in  the
 293    Transarc  cell to authenticate as admin in the Transarc test
 294    cell, even though he or she  is  logged  into  the  Transarc
 295    machine under a different name.
 296
 297    % klog admin -c test.transarc.com  Password: <admin's
 298    password>
 299
 300    In  the  following, the issuer requests a ticket lifetime of
 301    104 hours 30 minutes (4 days 8 hours 30 minutes).  Presuming
 302    that   this  lifetime  is  allowed  by  the  maximum  ticket
 303    lifetimes and other factors  described  in  the  DESCRIPTION
 304    section,   the   token  will  have  an  actual  lifetime  of
 305    110:44:28, which the next largest possible value.
 306
 307    % klog -life 104:30  Password:
 308
 309
 310
 311 PRIVILEGE REQUIRED
 312
 313    None.    An  entry  for  the  issuer  must  exist   in   the
 314    Authentication  Database,  and  the  issuer  must supply the
 315    correct password.
 316
 317 MORE INFORMATION
 318
 319    pagsh