NAME

       klog.krb5 - Authenticates to Kerberos and obtains a token

SYNOPSIS

       klog.krb5 [-x] [-principal <user name>]
           [-password <user's password>] [-cell <cell name>]
           [-k <realm>] [-pipe] [-silent]
           [-lifetime <ticket lifetime in hh[:mm[:ss]]>]
           [-setpag] [-tmp] [-noprdb] [-unwrap] [-help]

       klog.krb5 [-x] [-pr <user name>]
           [-pa <user's password>]
           [-c <cell name>]
           [-k <realm>] [-pi] [-si]
           [-l <ticket lifetime in hh[:mm[:ss]]>]
           [-se] [-t] [-n] [-u] [-h]

DESCRIPTION

       The klog.krb5 command obtains a Kerberos v5 ticket from a Kerberos KDC and, from the
       ticket, an AFS token and then stores it in the Cache Manager.  The Cache Manager keeps the
       token in kernel memory and uses it when obtaining authenticated access to the AFS
       filespace.  This command does not affect the issuer's identity (UNIX UID) on the local
       file system.

       By default, the command interpreter obtains a token for the AFS user name that matches the
       issuer's local user name.  To specify an alternate user, include the -principal argument.
       The user named by the -principal argument does not have to appear in the local password
       file (the /etc/passwd file or equivalent).

       By default, the command interpreter obtains a token for the local cell, as defined by the
       AFSCELL environment variable set in the command shell or by the /etc/openafs/ThisCell file
       on the local machine.  To specify an alternate cell, include the -cell argument.  A user
       can have tokens in multiple cells simultaneously, but only one token per cell per
       connection to the client machine.  If the user's credential structure already contains a
       token for the requested cell, the token resulting from this command replaces it.

       By default, the command interpreter obtains a Kerberos ticket for the local realm.  To
       specify a different Kerberos realm, include the -k argument.  The Kerberos realm name need
       not match the AFS cell name.  klog.krb5 will request a ticket for the principal "afs/cell"
       where cell is the cell name for which the user is requesting tokens, falling back on the
       principal "afs" if that principal does not work.

       The lifetime of the token resulting from this command is the smallest of the following:

       •   The lifetime specified by the issuer with the -lifetime argument if that argument was
           given.

       •   The maximum ticket lifetime recorded for the "afs/cell" principal in thet Kerberos
           database.

       •   The maximum ticket lifetime recorded in the specified user's Kerberos database entry.

CAUTIONS

       By default, this command does not create a new process authentication group (PAG); see the
       description of the pagsh command to learn about PAGs.  If a cell does not use an AFS-
       modified login utility, users must include -setpag option to this command, or issue the
       pagsh command before this one, to have their tokens stored in a credential structure that
       is identified by PAG rather than by local UID.  Users should be aware that -setpag will
       not work on some systems, most notably recent Linux systems, and using pagsh is
       preferrable and more reliable.

       When a credential structure is identified by local UID, the potential security exposure is
       that the local superuser "root" can use the UNIX su command to assume any other identity
       and automatically inherit the tokens associated with that UID.  Identifying the credential
       structure by PAG makes it more difficult (but not impossible) for the local superuser to
       obtain tokens of other users.

       If the -password argument is used, the specified password cannot begin with a hyphen,
       because it is interpreted as another option name.  Use of the -password argument is not
       recommended in any case.

       By default, it is possible to issue this command on a properly configured NFS client
       machine that is accessing AFS via the NFS/AFS Translator, assuming that the NFS client
       machine is a supported system type. However, if the translator machine's administrator has
       enabled UID checking by including the -uidcheck on argument to the fs exportafs command,
       the command fails with an error message similar to the following:

          Warning: Remote pioctl to <translator_machine> has failed (err=8). . .
          Unable to authenticate to AFS because a pioctl failed.

       Enabling UID checking means that the credential structure in which tokens are stored on
       the translator machine must be identified by a UID that matches the local UID of the
       process that is placing the tokens in the credential structure.  After the klog.krb5
       command interpreter obtains the token on the NFS client, it passes it to the remote
       executor daemon on the translator machine, which makes the system call that stores the
       token in a credential structure on the translator machine.  The remote executor generally
       runs as the local superuser "root", so in most cases its local UID (normally zero) does
       not match the local UID of the user who issued the klog.krb5 command on the NFS client
       machine.

       Issuing the klog.krb5 command on an NFS client machine creates a security exposure: the
       command interpreter passes the token across the network to the remote executor daemon in
       clear text mode.

OPTIONS

       -x  Appears only for backwards compatibility.  Its former function is now the default
           behavior of this command.

       -principal <user name>
           Specifies the user name to authenticate.  If this argument is omitted, the default
           value is the local user name.

       -password <user's password>
           Specifies the issuer's password (or that of the alternate user identified by the
           -principal argument).  Omit this argument to have the command interpreter prompt for
           the password, in which case it does not echo visibly in the command shell.

       -cell <cell name>
           Specifies the cell for which to obtain a token.  During a single login session on a
           given machine, a user can be authenticated in multiple cells simultaneously, but can
           have only one token at a time for each of them (that is, can only authenticate under
           one identity per cell per session on a machine).  It is acceptable to abbreviate the
           cell name to the shortest form that distinguishes it from the other cells listed in
           the /etc/openafs/CellServDB file on the client machine on which the command is issued.

           If this argument is omitted, the command is executed in the local cell, as defined

           •   First, by the value of the environment variable AFSCELL.

           •   Second, in the /etc/openafs/ThisCell file on the client machine on which the
               command is issued.

       -k <realm>
           Obtain tickets and tokens from the <realm> Kerberos realm.  If this option is not
           given, klog.krb5 defaults to using the default local realm.  The Kerberos realm name
           need not match the AFS cell name.

       -pipe
           Suppresses all output to the standard output stream, including prompts and error
           messages. The klog.krb5 command interpreter expects to receive the password from the
           standard input stream. Do not use this argument; it is designed for use by application
           programs rather than human users.

       -silent
           Suppresses some of the trace messages that the klog.krb5 command produces on the
           standard output stream by default.  It still reports on major problems encountered.

       -lifetime <ticket lifetime
           Requests a specific lifetime for the token.  Provide a number of hours and optionally
           minutes and seconds in the format hh[:mm[:ss]].

       -setpag
           Creates a process authentication group (PAG) prior to requesting authentication. The
           token is associated with the newly created PAG.

       -tmp
           Creates a Kerberos-style ticket file rather than only obtaining tokens.  The ticket
           file will be stored in the default Kerberos ticket cache location, which is usually in
           the /tmp directory of the local machine (but depends on the Kerberos implementation
           used).

       -noprdb
           By default, klog.krb5 looks up the user's AFS ID in the Protection Server and
           associates the token with that AFS ID.  This is helpful when looking at the output of
           commands like tokens but is not required.  If this option is given, this behavior is
           suppressed and klog.krb5 will store the token under a generic name.  You may wish this
           if, for example, you have problems contacting the Protection Server for an AFS cell
           for some reason.

       -unwrap
           Normally, klog.krb5 uses the Kerberos service ticket for the AFS principal as the AFS
           token.  If this option is given, klog.krb5 creates a different, simplified AFS token
           form based on the service ticket (the so-called "rxkad 2b" token).  Normally, this is
           not necessary.  However, if you are using older OpenAFS software that cannot handle
           large ticket sizes in conjunction with Active Directory as the Kerberos server, using
           -unwrap can shrink the AFS token size so that older software can handle it more
           easily.

       -help
           Prints the online help for this command. All other valid options are ignored.

OUTPUT

       If the -tmp flag is included, the following message confirms that a Kerberos ticket cache
       was created:

          Wrote ticket file to /tmp/krb5cc_1000_rENJoZ

       The path to the cache will vary, of course.

EXAMPLES

       Most often, this command is issued without arguments. The appropriate password is for the
       person currently logged into the local system.  The ticket's lifetime is calculated as
       described in DESCRIPTION.

          % klog.krb5
          Password for user@EXAMPLE.ORG:

       The following example authenticates the user as admin in the ABC Corporation's test cell:

          % klog.krb5 -principal admin -cell test.abc.com
          Password for admin@ABC.COM:

       In the following, the issuer requests a ticket lifetime of 104 hours 30 minutes (4 days 8
       hours 30 minutes).

          % klog.krb5 -lifetime 104:30
          Password for user@EXAMPLE.ORG:

PRIVILEGE REQUIRED

       None

SEE ALSO

       aklog(1), fs_exportafs(1), pagsh(1), tokens(1)

COPYRIGHT

       IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

       This documentation is covered by the IBM Public License Version 1.0.  It was converted
       from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by
       Alf Wachsmann and Elizabeth Cassell.