doc/man-pages/pod1/klog.krb5.pod

   1 =head1 NAME
   2
   3 klog.krb5 - Authenticates to Kerberos and obtains a token
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<klog.krb5> [B<-x>] S<<< [B<-principal> <I<user name>>] >>>
  11     [-password <I<user's password>>] S<<< [B<-cell> <I<cell name>>] >>>
  12     S<<< [B<-k> <I<realm>>] >>> [B<-pipe>] [B<-silent>]
  13     S<<< [B<-lifetime> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
  14     [B<-setpag>] [B<-tmp>] [B<-noprdb>] [B<-unwrap>] [B<-insecure_des>]
  15     [B<-help>]
  16
  17 B<klog.krb5> [B<-x>] S<<< [B<-pr> <I<user name>>] >>>
  18     S<<< [B<-pa> <I<user's password>>] >>>
  19     S<<< [B<-c> <I<cell name>>] >>>
  20     B<<< [B<-k> <I<realm>>] >>> [B<-pi>] [B<-si>]
  21     S<<< [B<-l> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
  22     [B<-se>] [B<-t>] [B<-n>] [B<-u>] [B<-i>] [B<-h>]
  23
  24 =for html
  25 </div>
  26
  27 =head1 DESCRIPTION
  28
  29 The B<klog.krb5> command obtains a Kerberos v5 ticket from a Kerberos
  30 KDC and, from the ticket, an AFS token and then stores it in the Cache
  31 Manager.  The Cache Manager keeps the token in kernel memory and uses it
  32 when obtaining authenticated access to the AFS filespace.  This command
  33 does not affect the issuer's identity (UNIX UID) on the local file system.
  34
  35 By default, the command interpreter obtains a token for the AFS user name
  36 that matches the issuer's local user name.  To specify an alternate user,
  37 include the B<-principal> argument.  The user named by the B<-principal>
  38 argument does not have to appear in the local password file (the
  39 F</etc/passwd> file or equivalent).
  40
  41 By default, the command interpreter obtains a token for the local cell, as
  42 defined by the AFSCELL environment variable set in the command shell or by
  43 the F</usr/vice/etc/ThisCell> file on the local machine.  To specify an
  44 alternate cell, include the B<-cell> argument.  A user can have tokens in
  45 multiple cells simultaneously, but only one token per cell per connection
  46 to the client machine.  If the user's credential structure already
  47 contains a token for the requested cell, the token resulting from this
  48 command replaces it.
  49
  50 By default, the command interpreter obtains a Kerberos ticket for the
  51 local realm.  To specify a different Kerberos realm, include the B<-k>
  52 argument.  The Kerberos realm name need not match the AFS cell name.
  53 B<klog.krb5> will request a ticket for the principal C<afs/I<cell>> where
  54 I<cell> is the cell name for which the user is requesting tokens, falling
  55 back on the principal C<afs> if that principal does not work.
  56
  57 The lifetime of the token resulting from this command is the smallest of
  58 the following:
  59
  60 =over 4
  61
  62 =item *
  63
  64 The maximum ticket lifetime recorded for the C<afs/I<cell>> principal in
  65 thet Kerberos database.
  66
  67 =item *
  68
  69 The maximum ticket lifetime recorded in the specified user's Kerberos
  70 database entry.
  71
  72 =back
  73
  74 =head1 CAUTIONS
  75
  76 By default, this command does not create a new process authentication
  77 group (PAG); see the description of the B<pagsh> command to learn about
  78 PAGs.  If a cell does not use an AFS-modified login utility, users must
  79 include B<-setpag> option to this command, or issue the B<pagsh> command
  80 before this one, to have their tokens stored in a credential structure
  81 that is identified by PAG rather than by local UID.  Users should be aware
  82 that B<-setpag> will not work on some systems, most notably recent Linux
  83 systems, and using B<pagsh> is preferrable and more reliable.
  84
  85 When a credential structure is identified by local UID, the potential
  86 security exposure is that the local superuser C<root> can use the UNIX
  87 B<su> command to assume any other identity and automatically inherit the
  88 tokens associated with that UID.  Identifying the credential structure by
  89 PAG makes it more difficult (but not impossible) for the local superuser
  90 to obtain tokens of other users.
  91
  92 If the B<-password> argument is used, the specified password cannot begin
  93 with a hyphen, because it is interpreted as another option name.  Use of
  94 the B<-password> argument is not recommended in any case.
  95
  96 By default, it is possible to issue this command on a properly configured
  97 NFS client machine that is accessing AFS via the NFS/AFS Translator,
  98 assuming that the NFS client machine is a supported system type. However,
  99 if the translator machine's administrator has enabled UID checking by
 100 including the B<-uidcheck on> argument to the B<fs exportafs> command, the
 101 command fails with an error message similar to the following:
 102
 103    Warning: Remote pioctl to <translator_machine> has failed (err=8). . .
 104    Unable to authenticate to AFS because a pioctl failed.
 105
 106 Enabling UID checking means that the credential structure in which tokens
 107 are stored on the translator machine must be identified by a UID that
 108 matches the local UID of the process that is placing the tokens in the
 109 credential structure.  After the B<klog.krb5> command interpreter obtains
 110 the token on the NFS client, it passes it to the remote executor daemon on
 111 the translator machine, which makes the system call that stores the token
 112 in a credential structure on the translator machine.  The remote executor
 113 generally runs as the local superuser C<root>, so in most cases its local
 114 UID (normally zero) does not match the local UID of the user who issued
 115 the B<klog.krb5> command on the NFS client machine.
 116
 117 Issuing the B<klog.krb5> command on an NFS client machine creates a
 118 security exposure: the command interpreter passes the token across the
 119 network to the remote executor daemon in clear text mode.
 120
 121 =head1 OPTIONS
 122
 123 =over 4
 124
 125 =item B<-x>
 126
 127 Appears only for backwards compatibility.  Its former function is now the
 128 default behavior of this command.
 129
 130 =item B<-principal> <I<user name>>
 131
 132 Specifies the user name to authenticate.  If this argument is omitted, the
 133 default value is the local user name.
 134
 135 =item B<-password> <I<user's password>>
 136
 137 Specifies the issuer's password (or that of the alternate user identified
 138 by the B<-principal> argument).  Omit this argument to have the command
 139 interpreter prompt for the password, in which case it does not echo
 140 visibly in the command shell.
 141
 142 =item B<-cell> <I<cell name>>
 143
 144 Specifies the cell for which to obtain a token.  During a single login
 145 session on a given machine, a user can be authenticated in multiple cells
 146 simultaneously, but can have only one token at a time for each of them
 147 (that is, can only authenticate under one identity per cell per session on
 148 a machine).  It is acceptable to abbreviate the cell name to the shortest
 149 form that distinguishes it from the other cells listed in the
 150 F</usr/vice/etc/CellServDB> file on the client machine on which the
 151 command is issued.
 152
 153 If this argument is omitted, the command is executed in the local cell, as
 154 defined
 155
 156 =over 4
 157
 158 =item *
 159
 160 First, by the value of the environment variable AFSCELL.
 161
 162 =item *
 163
 164 Second, in the F</usr/vice/etc/ThisCell> file on the client machine on
 165 which the command is issued.
 166
 167 =back
 168
 169 =item B<-k> <I<realm>>
 170
 171 Obtain tickets and tokens from the <I<realm>> Kerberos realm.  If this
 172 option is not given, B<klog.krb5> defaults to using the default local
 173 realm.  The Kerberos realm name need not match the AFS cell name.
 174
 175 =item B<-pipe>
 176
 177 Suppresses all output to the standard output stream, including prompts and
 178 error messages. The B<klog.krb5> command interpreter expects to receive
 179 the password from the standard input stream. Do not use this argument; it
 180 is designed for use by application programs rather than human users.
 181
 182 =item B<-silent>
 183
 184 Suppresses some of the trace messages that the B<klog.krb5> command
 185 produces on the standard output stream by default.  It still reports on
 186 major problems encountered.
 187
 188 =item B<-lifetime> <I<ticket lifetime>
 189
 190 This option is not implemented by B<klog.krb5> and has no effect.
 191
 192 =item B<-setpag>
 193
 194 Creates a process authentication group (PAG) prior to requesting
 195 authentication. The token is associated with the newly created PAG.
 196
 197 =item B<-tmp>
 198
 199 Creates a Kerberos-style ticket file rather than only obtaining tokens.
 200 The ticket file will be stored in the default Kerberos ticket cache
 201 location, which is usually in the F</tmp> directory of the local machine
 202 (but depends on the Kerberos implementation used).
 203
 204 =item B<-noprdb>
 205
 206 By default, B<klog.krb5> looks up the user's AFS ID in the Protection
 207 Server and associates the token with that AFS ID.  This is helpful when
 208 looking at the output of commands like B<tokens> but is not required.  If
 209 this option is given, this behavior is suppressed and B<klog.krb5> will
 210 store the token under a generic name.  You may wish this if, for example,
 211 you have problems contacting the Protection Server for an AFS cell for
 212 some reason.
 213
 214 =item B<-unwrap>
 215
 216 Normally, B<klog.krb5> uses the Kerberos service ticket for the AFS
 217 principal as the AFS token.  If this option is given, B<klog.krb5> creates
 218 a different, simplified AFS token form based on the service ticket (the
 219 so-called "rxkad 2b" token).  Normally, this is not necessary.  However,
 220 if you are using older OpenAFS software that cannot handle large ticket
 221 sizes in conjunction with Active Directory as the Kerberos server, using
 222 B<-unwrap> can shrink the AFS token size so that older software can handle
 223 it more easily.
 224
 225 =item B<-insecure_des>
 226
 227 Configures libkrb5 to allow the use of the (insecure) single-DES encryption
 228 types.  When rxkad-k5 is in use, this is not needed.
 229
 230 =item B<-help>
 231
 232 Prints the online help for this command. All other valid options are
 233 ignored.
 234
 235 =back
 236
 237 =head1 OUTPUT
 238
 239 If the B<-tmp> flag is included, the following message confirms that a
 240 Kerberos ticket cache was created:
 241
 242    Wrote ticket file to /tmp/krb5cc_1000_rENJoZ
 243
 244 The path to the cache will vary, of course.
 245
 246 =head1 EXAMPLES
 247
 248 Most often, this command is issued without arguments. The appropriate
 249 password is for the person currently logged into the local system.  The
 250 ticket's lifetime is calculated as described in L</DESCRIPTION>.
 251
 252    % klog.krb5
 253    Password for user@EXAMPLE.ORG:
 254
 255 The following example authenticates the user as admin in the Example
 256 Corporation's test cell:
 257
 258    % klog.krb5 -principal admin -cell test.example.com
 259    Password for admin@EXAMPLE.COM:
 260
 261 =head1 PRIVILEGE REQUIRED
 262
 263 None
 264
 265 =head1 SEE ALSO
 266
 267 L<aklog(1)>,
 268 L<fs_exportafs(1)>,
 269 L<pagsh(1)>,
 270 L<tokens(1)>
 271
 272 =head1 COPYRIGHT
 273
 274 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 275
 276 This documentation is covered by the IBM Public License Version 1.0.  It
 277 was converted from HTML to POD by software written by Chas Williams and
 278 Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.