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