--- /dev/null
+=head1 NAME
+
+klog - Authenticates with the Authentication Server
+
+=head1 SYNOPSIS
+
+B<klog> [B<-x>] [B<-principal> <I<user name>>] [-password <I<user's password>>]
+[B<-cell> <I<cell name>>] [B<-servers> <I<explicit list of servers>>+]
+ [B<-pipe>] [B<-silent>] [-lifetime <I<ticket lifetime in hh[:mm[:ss]]>>]
+ [B<-setpag>] [B<-tmp>] [-help]
+
+B<klog> [B<-x>] [B<-pr> <I<user name>>] [B<-pa> <I<user's password>>] [-c <I<cell name>>]
+[B<-s> <I<explicit list of servers>>+] [B<-pi>] [B<-si>]
+ [B<-l> <I<ticket lifetime in hh[:mm[:ss]]>>] [B<-se>] [B<-t>] [-h]
+
+=head1 DESCRIPTION
+
+The klog command obtains an AFS token from the Authentication
+Server. The Cache Manager on the local machine stores the token in a
+credential structure 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) in the local file system.
+
+By default, the command interpreter obtains a token for the AFS user name
+that matches the issuer's identity in the local file system. To
+specify an alternate user, include the B<-principal> argument.
+The user named by the B<-principal> argument does not have to appear
+in the local password file (the B</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
+B</usr/vice/etc/ThisCell> file on the local machine. To specify
+an alternate cell, include the B<-cell> argument. The command
+interpreter contacts an Authentication Server chosen at random from the
+cell's entry in the local B</usr/afs/etc/CellServDB> file, unless
+the B<-servers> argument is used to name one or more database server
+machines.
+
+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.
+
+Sites that employ standard Kerberos authentication instead of the AFS
+Authentication Server must use the Kerberos version of this command,
+B<klog.krb>, on all client machines. It automatically
+places the issuer's Kerberos tickets in the file named by the KRBTKFILE
+environment variable, which the B<pagsh.krb> command defines
+automatically as B</tmp/tktp>I<X> where I<X> is the
+number of the user's PAG.
+
+The lifetime of the token resulting from this command is the smallest of
+the following.
+
+=over 4
+
+=item *
+
+The lifetime specified by the issuer with the -lifetime
+argument. If the issuer does not include this argument, the value
+defaults to 720 hours (30 days).
+
+
+=item *
+
+The maximum ticket lifetime recorded for the afs entry in the
+Authentication Database. The default is 100 hours.
+
+
+=item *
+
+The maximum ticket lifetime recorded in the specified user's
+Authentication Database entry. The default is 25 hours for user entries
+created by an Authentication Server running AFS 3.1 or later.
+
+
+=item *
+
+The maximum ticket lifetime recorded in the
+B<krbtgt.>I<CELLNAME> entry in the Authentication
+Database; this entry corresponds to the ticket-granting ticket used
+internally in generating the token. The default is 720 hours (30
+days).
+
+
+=back
+
+The output from the kas examine command displays an
+Authentication Database entry's maximum ticket lifetime as C<Max
+ticket lifetime>. Administrators can display any entry, and users
+can display their own entries.
+
+If none of the defaults have been changed, the token lifetime is 25 hours
+for user accounts created by an Authentication Server running AFS 3.1
+or higher. The maximum lifetime for any token is 720 hours (30 days),
+and the minimum is 5 minutes.
+
+Between the minimum and maximum values, the Authentication Server uses a
+defined set of values, according to the following rules. Requested
+lifetimes between 5 minutes and 10 hours 40 minutes are granted at 5 minute
+intervals, rounding up. For example, if the issuer requests a lifetime
+of 12 minutes, the token's actual lifetime is 15 minutes.
+
+For token lifetimes greater than 10 hours 40 minutes, consult the following
+table, which presents all the possible times in units of
+I<hours>B<:>I<minutes>B<:>I<seconds>.
+The number in parentheses is an approximation of the corresponding time in
+days and hours (as indicated by the C<d> and C<h>
+letters). For example, C<282:22:17> means 282
+hours, 22 minutes, and 17 seconds, which translates to approximately 11 days
+and 18 hours (C<11d 18h>). The Authentication Server rounds up
+a requested lifetime to the next highest possible lifetime.
+
+ 11:24:15 (0d 11h) 46:26:01 (1d 22h) 189:03:38 (7d 21h)
+ 12:11:34 (0d 12h) 49:38:40 (2d 01h) 202:08:00 (8d 10h)
+ 13:02:09 (0d 13h) 53:04:37 (2d 05h) 216:06:35 (9d 00h)
+ 13:56:14 (0d 13h) 56:44:49 (2d 08h) 231:03:09 (9d 15h)
+ 14:54:03 (0d 14h) 60:40:15 (2d 12h) 247:01:43 (10d 07h)
+ 15:55:52 (0d 15h) 64:51:57 (2d 16h) 264:06:34 (11d 00h)
+ 17:01:58 (0d 17h) 69:21:04 (2d 21h) 282:22:17 (11d 18h)
+ 18:12:38 (0d 18h) 74:08:46 (3d 02h) 301:53:45 (12d 13h)
+ 19:28:11 (0d 19h) 79:16:23 (3d 07h) 322:46:13 (13d 10h)
+ 20:48:57 (0d 20h) 84:45:16 (3d 12h) 345:05:18 (14d 09h)
+ 22:15:19 (0d 22h) 90:36:53 (3d 18h) 368:56:58 (15d 08h)
+ 23:47:38 (0d 23h) 96:52:49 (4d 00h) 394:27:37 (16d 10h)
+ 25:26:21 (1d 01h) 103:34:45 (4d 07h) 421:44:07 (17d 13h)
+ 27:11:54 (1d 03h) 110:44:28 (4d 14h) 450:53:46 (18d 18h)
+ 29:04:44 (1d 05h) 118:23:54 (4d 22h) 482:04:24 (20d 02h)
+ 31:05:22 (1d 07h) 126:35:05 (5d 06h) 515:24:22 (21d 11h)
+ 33:14:21 (1d 09h) 135:20:15 (5d 15h) 551:02:38 (22d 23h)
+ 35:32:15 (1d 11h) 144:41:44 (6d 00h) 589:08:45 (24d 13h)
+ 37:59:41 (1d 13h) 154:42:01 (6d 10h) 629:52:56 (26d 05h)
+ 40:37:19 (1d 16h) 165:23:50 (6d 21h) 673:26:07 (28d 01h)
+ 43:25:50 (1d 19h) 176:50:01 (7d 08h)
+
+=head1 CAVEATS
+
+By default, this command does not create a new process authentication group
+(PAG); see the description of the B<pagsh> command to learn about
+PAGs. If a cell does not use an AFS-modified login utility, users must
+include B<-setpag> option to this command, or issue the
+B<pagsh> command before this one, to have their tokens stored in a
+credential structure that is identified by PAG rather than by local
+UID.
+
+When a credential structure is identified by local UID, the potential
+security exposure is that the local superuser B<root> can use the UNIX
+B<su> command to assume any other identity and automatically inherit
+the tokens associated with that UID. Identifying the credential
+structure by PAG eliminates this exposure.
+
+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 B<-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 B<-uidcheck on> argument to the B<fs exportafs> command,
+the command fails with an error message similar to the following:
+
+
+ Warning: Remote pioctl to I<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 B<klog> 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 B<root>, so in most cases its
+local UID (normally zero) does not match the local UID of the user who issued
+the B<klog> command on the NFS client machine.
+
+Issuing the klog 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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item -x
+
+Appears only for backwards compatibility. Its former function is
+now the default behavior of this command.
+
+=item -principal
+
+Specifies the user name to authenticate. If this argument is
+omitted, the Authentication Server attempts to authenticate the user logged
+into the local file system.
+
+=item -password
+
+Specifies the issuer's password (or that of the alternate user
+identified by the B<-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.
+
+=item -cell
+
+Specifies the cell for which to obtain a token. The command is
+directed to that cell's Authentication Servers. 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
+B</usr/vice/etc/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
+
+=over 4
+
+=item *
+
+First, by the value of the environment variable AFSCELL
+
+
+=item *
+
+Second, in the /usr/vice/etc/ThisCell file on the client
+machine on which the command is issued
+
+
+=back
+
+=item -servers
+
+Establishes a connection with the Authentication Server running on each
+specified database server machine. The command interpreter then chooses
+one of these at random to execute the command. It is best to provide
+fully-qualified hostnames, but abbreviated forms are possibly acceptable
+depending on the state of the cell's name server at the time the command
+is issued. This option is useful for testing specific servers if
+problems are encountered.
+
+If this argument is omitted, the command interpreter establishes a
+connection with each machine listed for the indicated cell in the local copy
+of the B</usr/vice/etc/CellServDB> file, and then chooses one of them
+at random for command execution.
+
+=item -pipe
+
+Suppresses all output to the standard output stream, including prompts and
+error messages. The B<klog> 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.
+
+=item -silent
+
+Suppresses some of the trace messages that the klog command
+produces on the standard output stream by default. It still reports on
+major problems encountered.
+
+=item -lifetime
+
+Requests a specific lifetime for the token. Provide a number of
+hours and optionally minutes and seconds in the format
+I<hh>[B<:>I<mm>[B<:>I<ss>]].
+The value is used in calculating the token lifetime as described in the
+B<Description> section.
+
+=item -setpag
+
+Creates a process authentication group (PAG) prior to requesting
+authentication. The token is associated with the newly created
+PAG.
+
+=item -tmp
+
+Creates a Kerberos-style ticket file in the /tmp directory of
+the local machine. The file is called
+B<tkt.>I<AFS_UID> where I<AFS_UID> is the AFS UID
+of the issuer.
+
+=item -help
+
+Prints the online help for this command. All other valid options
+are ignored.
+
+=back
+
+=head1 CAVEATS
+
+=head1 OUTPUT
+
+The following message indicates that the limit on consecutive
+authentication failures has been exceeded. An administrator can use the
+B<kas unlock> command to unlock the account, or the issuer can wait
+until the lockout time for the account has passed. (The time is set
+with the B<-locktime> argument to the B<kas setfields> command
+and displayed in the output from the B<kas examine> command).
+
+
+ Unable to authenticate to AFS because ID is locked - see your system admin
+
+
+If the -tmp flag is included, the following message confirms
+that a Kerberos-style ticket file was created:
+
+
+ Wrote ticket file to /tmp
+
+
+=head1 EXAMPLES
+
+Most often, this command is issued without arguments. The
+appropriate password is for the person currently logged into the local file
+system. The ticket's lifetime is calculated as described in the
+B<Description> section (if no defaults have been changed, it is 25
+hours for a user whose Authentication Database entry was created in AFS
+3.1 or later).
+
+
+ % klog
+ Password:
+
+
+The following example authenticates the user as admin in the ABC
+Corporation's test cell:
+
+
+ % klog -principal admin -cell test.abc.com
+ Password:
+
+
+In the following, the issuer requests a ticket lifetime of 104 hours 30
+minutes (4 days 8 hours 30 minutes). Presuming that this lifetime is
+allowed by the maximum ticket lifetimes and other factors described in the
+B<Description> section, the token's lifetime is
+110:44:28, which is the next largest possible value.
+
+ % klog -lifetime 104:30
+ Password:
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 SEE ALSO
+
+L<fs_exportafs(1)>,
+L<kas_examine(1)>,
+L<kas_setfields(1)>,
+L<kas_unlock(1)>,
+L<kaserver(1)>,
+L<pagsh(1)>,
+L<tokens(1)>
+
+=head1 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.