Command Reference Manual

klog

Purpose

Authenticates with the Authentication Server

Synopsis

klog  [-x]  [-principal <user name>]  [-password <user's password>]  
      [-cell <cell name>]  [-servers <explicit list of servers>⁺]  
      [-pipe]  [-silent]  [-lifetime <ticket lifetime in hh[:mm[:ss]]>]  
      [-setpag]  [-tmp]  [-help]
    
klog  [-x]  [-pr <user name>]  [-pa <user's password>]  [-c <cell name>]  
      [-s <explicit list of servers>⁺]  [-pi]  [-si]  
      [-l <ticket lifetime in hh[:mm[:ss]]>]  [-se]  [-t]  [-h]

Description

The klog command obtains an AFS token from the Authentication Server for the issuer. 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 local identity (UNIX UID).

By default, the command interpreter obtains a token for the AFS user name that matches the issuer's local identity (UNIX UID). 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).

Also by default, the command interpreter obtains a token for the local cell, as defined by the /usr/vice/etc/ThisCell file. It chooses a local Authentication Server at random from the /usr/afs/etc/CellServDB file. 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.

Sites that employ standard Kerberos authentication instead of the AFS Authentication Server must use the Kerberos version of this command, klog.krb, on all client machines. It automatically places the issuer's Kerberos tickets in the file name by the KRBTKFILE environment variable, which the pagsh.krb command defines automatically as /tmp/tktpX (where X is the number of the user's PAG).

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

The lifetime requested by the issuer with the -lifetime argument. If the issuer does not include this argument, the value defaults to 720 hours (30 days).
The maximum ticket lifetime recorded for the afs entry in the Authentication Database. The default is 100 hours.
The maximum ticket lifetime recorded for the user in the Authentication Database entry for the issuer. The default is 25 hours for user entries created by an Authentication Server running AFS 3.1 or later.
The maximum ticket lifetime recorded in the krbtgt.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).

The output from the kas examine command displays an Authentication Database entry's maximum ticket lifetime as 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 hours:minutes:seconds. The number in parentheses is an approximation of the corresponding time in days and hours (as indicated by the d and hletters). For example, 282:22:17 means 282 hours, 22 minutes, and 17 seconds, which translates to approximately 11 days and 18 hours (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)

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 UNIX UID.

When a credential structure is identified by UNIX 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 eliminates this problem.

Options

-x

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

-principal

Specifies the user name to authenticate. By default, the Authentication Server attempts to authenticate the user logged into the local file system.

-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

Specifies the cell in which the issuer wishes to authenticate, by directing the command to that cell's Authentication Servers. During a single login session on a given machine, a user may 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 machine). The issuer may abbreviate cell name to the shortest form that distinguishes it from the other cells listed in the /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

First, by the value of the environment variable AFSCELL
Second, in the /usr/vice/etc/ThisCell file on the client machine on which the command is issued

-servers

Causes the command interpreter to establish a connection with the Authentication Server running on each specified database server machine. It then chooses one of these at random to execute the command. The command accepts shortened machine names, but exactly which abbreviations are acceptable depends 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 machine's copy of the /usr/vice/etc/CellServDB file, and then chooses one of those at random for command execution.

-pipe

Suppresses all output to the standard output stream, including prompts and error messages. The 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.

-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.

-lifetime

Requests a specific lifetime for the token. Provide a number of hours and optionally minutes and seconds in the format hh[:mm[:ss]]. The value is incorporated in the lifetime calculation as described in the Description section.

-setpag

Creates a process authentication group (PAG) prior to requesting authentication. The tokens created are then placed in this newly created PAG.

-tmp

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

-help

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

Cautions

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

Output

The following message indicates that the limit on consecutive authentication failures has been exceeded. An administrator can use the kas unlock command to unlock the account, or the user can wait until the lockout time set with the -locktime argument to the kas setfields command has passed.

Unable to authenticate to AFS because ID is locked - see your system admin

If the -tmp flag is included, the following message confirm that a Kerberos-style ticket file was created:

Wrote ticket file to /tmp

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 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: <admin's 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 Description section, the token's lifetime is 110:44:28, which is the next largest possible value.

% klog -lifetime 104:30
Password:

Privilege Required

None

Related Information