pod-man-pages-20051015

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

=head1 NAME

klog - Authenticates with the Authentication Server

=head1 SYNOPSIS

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

klog  [B<-x>]  [B<-pr> I<user name>]  [B<-pa> I<user's password>]  [B<-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>]  [B<-h>]

=head1 DESCRIPTION

The C<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

=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 B<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 B<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 C<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 B<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>:I<minutes>: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 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 file 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
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

=item *

First, by the value of the environment variable AFSCELL

=item *

Second, in the B</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
B</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 C<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 C<klog> command
produces on the standard output stream by default. It still
reports on major problems encountered.

=item B<-lifetime> I<ticket lifetime in hh[:mm[:ss]]>

Requests a specific lifetime for the token. Provide a number of
hours and optionally minutes and seconds in the format
I<hh>[:I<mm>[:I<ss>]]. The value is used in calculating the token
lifetime as described in the L</"DESCRIPTION"> section.

=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 B</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 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 C<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 C<kas setfields> command and displayed
in the output from the C<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 file
system. The ticket's lifetime is calculated as described in the
L</"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).

B<    klog>
   Password:

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

B<    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 L</"DESCRIPTION"> section, the token's lifetime is 110:44:28, which
is the next largest possible value.

B<    klog -lifetime 104:30>
   Password:

=head1 PRIVILEGE REQUIRED

None

=head1 CAVEATS

By default, this command does not create a new process authentication
group (PAG); see the description of the C<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 C<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 C<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> B<on> argument to the C<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 C<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 C<klog> command on the NFS
client machine.

Issuing the C<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 COPYRIGHT

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

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=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)>

=cut