mirror of
https://git.openafs.org/openafs.git
synced 2025-01-19 15:30:14 +00:00
798ffe54af
FIXES 124799 LICENSE IPL10 Install symlinks for the *.krb versions of klog, pagsh, and tokens to the non-krb versions and add information about the *.krb versions to the non-krb man pages.
358 lines
14 KiB
Plaintext
358 lines
14 KiB
Plaintext
=head1 NAME
|
|
|
|
klog, klog.krb - 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>]
|
|
|
|
B<klog.krb> [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>]
|
|
|
|
=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) should 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.
|