[openafs.git] / doc / man-pages / pod1 / klog.pod

=head1 NAME

klog - Authenticates with the Authentication Server

=head1 SYNOPSIS

=for html
<div class="synopsis">

B<klog> [B<-x>] S<<< [B<-principal> <I<user name>>] >>>
    [-password <I<user's password>>] S<<< [B<-cell> <I<cell name>>] >>>
    S<<< [B<-servers> <I<explicit list of servers>>+] >>>
    [B<-pipe>] [B<-silent>]
    S<<< [B<-lifetime> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
    [B<-setpag>] [B<-tmp>] [B<-help>]

B<klog> [B<-x>] S<<< [B<-pr> <I<user name>>] >>> S<<< [B<-pa> <I<user's password>>] >>>
    S<<< [B<-c> <I<cell name>>] >>>  S<<< [B<-s> <I<explicit list of servers>>+] >>>
    [B<-pi>] [B<-si>] S<<< [B<-l> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
    [B<-se>] [B<-t>] [B<-h>]

=for html
</div>

=head1 DESCRIPTION

The B<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 F</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 F</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 F</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 Kerberos authentication instead of the AFS
Authentication Server should normally use the combination of B<kinit> and
B<aklog> instead of B<klog>.

Sites using Kerberos v4 authentication (perhaps with 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 F</tmp/tktpI<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 B<-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 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 CAUTIONS

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 C<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 B<-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 <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 C<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 B<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 B<-x>

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

=item B<-principal> <I<user name>>

Specifies the user name to authenticate. If this argument is omitted, the
Authentication Server attempts to authenticate the user logged into the
local system.

=item B<-password> <I<user's 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 B<-cell> <I<cell name>>

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
F</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 F</usr/vice/etc/ThisCell> file on the client machine on
which the command is issued.

=back

=item B<-servers> <I<explicit list of 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 F</usr/vice/etc/CellServDB> file, and then chooses one of them
at random for command execution.

=item B<-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 B<-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 B<-lifetime> <I<ticket 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
L<DESCRIPTION>.

=item B<-setpag>

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

=item B<-tmp>

Creates a Kerberos-style ticket file in the F</tmp> directory of the local
machine. The file is called F<tkt.I<AFS_UID>> where I<AFS_UID> is the AFS
UID of the issuer.

=item B<-help>

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

=back

=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 B<-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 system. The
ticket's lifetime is calculated as described in L<DESCRIPTION> (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
L<DESCRIPTION>, 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(8)>,
L<kas_setfields(8)>,
L<kas_unlock(8)>,
L<kaserver(8)>,
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.