Chapter 2. Using OpenAFS

Table of Contents

Logging in and Authenticating with AFS
Logging In
To Log In Using an AFS-modified Login Utility
To Log In Using a Two-Step Login Procedure
Authenticating with AFS
To Authenticate with AFS
To Display Your Tokens
Example: Authenticating in the Local Cell
Example: Authenticating as a Another User
Example: Authenticating in a Foreign Cell
Limits on Failed Authentication Attempts
To Display Your Failed Authentication Limit and Lockout Time
Exiting an AFS Session
To Discard Tokens
Example: Unauthenticating from a Specific Cell
To Log Out
Accessing the AFS Filespace
AFS Pathnames
Example: Displaying the Contents of Another User's Directory
Accessing Foreign Cells
Changing Your Password
To Display Password Expiration Date and Reuse Policy
To Change Your AFS Password
To Change Your UNIX Password

This chapter explains how to perform four basic AFS tasks: logging in and authenticating with AFS, ending an AFS session, accessing the AFS filespace, and changing your password.

Logging in and Authenticating with AFS

To access the AFS filespace as an authenticated user, you must both log into an AFS client machine's local (UNIX) file system and authenticate with AFS. When you log in, you establish your local system identity. When you authenticate, you prove your identity to AFS and obtain a token, which your Cache Manager uses to prove your authenticated status to the AFS server processes it contacts on your behalf. Users who are not authenticated (who do not have a token) have limited access to AFS directories and files.

Logging In

On machines that use an AFS-modified login utility, you log in and authenticate in one step. On machines that do not use an AFS-modified login utility, you log in and authenticate in separate steps. To determine which type of login utility your machine uses, you can check for AFS tokens after logging in, or ask your system administrator, who can also tell you about any differences between your login procedure and the two methods described here.

To Log In Using an AFS-modified Login Utility

Provide your username at the login: prompt that appears when you establish a new connection to a machine. Then provide your password at the Password: prompt as shown in the following example. (Your password does not echo visibly on the screen.)

   login: username
   Password: password

If you are not sure which type of login utility is running on your machine, it is best to issue the tokens command to check if you are authenticated; for instructions, see To Display Your Tokens. If you do not have tokens, issue the klog command as described in To Authenticate with AFS.

To Log In Using a Two-Step Login Procedure

If your machine does not use an AFS-modified login utility, you must perform a two-step procedure:

  1. Log in to your client machine's local file system by providing a user name and password at the login program's prompts.

  2. Issue the klog command to authenticate with AFS. Include the command's -setpag argument to associate your token with a special identification number called a PAG (for process authentication group). For a description of PAGs, see Protecting Your Tokens with a PAG.

      
       % klog -setpag
       Password: your_AFS_password
    

Note

If your machine uses a two-step login procedure, you can choose to use different passwords for logging in and authenticating. It is simplest to use the same one for both, though. Talk with your system administrator.

Authenticating with AFS

To work most effectively in the AFS filespace, you must authenticate with AFS. When you do, your Cache Manager is given a token as proof of your authenticated status. It uses your token when requesting services from AFS servers, which accept the token as proof of your authenticated status. If you do not have a token, AFS servers consider you to be the anonymous user and your access to AFS filespace is limited: you have only the ACL permissions granted to the system:anyuser group.

You can obtain new tokens (reauthenticate) at any time, even after using an AFS-modified login utility, which logs you in and authenticates you in one step. Issue the klog command as described in To Authenticate with AFS.

Protecting Your Tokens with a PAG

To make your access to AFS as secure as possible, it is best to associate your tokens with a unique identification number called a PAG (for process authentication group). AFS-modified login utilities automatically create a PAG and associate the new token with it. To create a PAG when you use the two-step login procedure, include the klog command's -setpag flag. If you do not use this flag, your tokens are associated with your UNIX UID number instead. This type of association has two potential drawbacks:

  • Anyone who can assume your local UNIX identity can use your tokens. The local superuser root can always use the UNIX su command to assume your UNIX UID, even without knowing your password.

  • In some environments, certain programs cannot use your tokens even when it is appropriate for them to do so. For example, printing commands such as lp or lpr possibly cannot access the files you want to print, because they cannot use your tokens.

Obtaining Tokens For Foreign Cells

A token is valid only in one cell (the cell whose AFS authentication service issued it). The AFS server processes in any other cell consider you to be the anonymous user unless you have an account in the cell and authenticate with its AFS authentication service.

To obtain tokens in a foreign cell, use the -cell argument to the klog command. You can have tokens for your home cell and one or more foreign cells at the same time.

The One-Token-Per-Cell Rule

You can have only one token per cell for each PAG you have obtained on a client machine. If you already have a token for a particular cell and issue the klog command, the new token overwrites the existing one. Getting a new token is useful if your current token is almost expired but you want to continue accessing AFS files. For a discussion of token expiration, see Token Lifetime.

To obtain a second token for the same cell, you must either login on a different machine or establish another separate connection to the machine where you already have a token (by using the telnet utility, for example). You get a new PAG for each separate machine or connection, and can use the associated tokens only while working on that machine or connection.

Obtaining Tokens as Another User

You can authenticate as another username if you know the associated password. (It is, of course, unethical to use someone else's tokens without permission.) If you use the klog command to authenticate as another AFS username, you retain your own local (UNIX) identity, but the AFS server processes recognize you as the other user. The new token replaces any token you already have for the relevant cell (for the reason described in The One-Token-Per-Cell Rule).

Token Lifetime

Tokens have a limited lifetime. To determine when your tokens expire, issue the tokens command as described in To Display Your Tokens. If you are ever unable to access AFS in a way that you normally can, issuing the tokens command tells you whether an expired token is a possible reason.

Your cell's administrators set the default lifetime of your token. The AFS authentication service never grants a token lifetime longer than the default, but you can request a token with a shorter lifetime. See the klog reference page in the OpenAFS Administration Reference to learn how to use its -lifetime argument for this purpose.

Authenticating for DFS Access

If your machine is configured to access a DCE cell's DFS filespace by means of the AFS/DFS Migration Toolkit, you can use the dlog command to authenticate with DCE. The dlog command has no effect on your ability to access AFS filespace.

If your system administrator has converted your AFS account to a DCE account and you are not sure of your DCE password, use the dpass command to display it. You must be authenticated as the AFS user whose AFS account was converted to a DCE account, and be able to provide the correct AFS password. Like the dlog command, the dpass command has no functionality with respect to AFS.

For more information on using the dlog and dpass commands, see your system administrator.

To Authenticate with AFS

If your machine is not using an AFS-modified login utility, you must authenticate after login by issuing the klog command. You can also issue this command at any time to obtain a token with a later expiration date than your current token.

   % klog [-setpag] [-cell <cell name>]
   Password: your_AFS_password

where

-setpag

Associates the resulting tokens with a PAG (see Protecting Your Tokens with a PAG). Include this flag the first time you obtain a token for a particular cell during a login session or connection. Do not include it when refreshing the token for a cell during the same session.

-cell

Names the cell for which to obtain the token. You must have an account in the cell.

Your password does not echo visibly appear on the screen. When the command shell prompt returns, you are an authenticated AFS user. You can use the tokens command to verify that you are authenticated, as described in the following section.

To Display Your Tokens

Use the tokens command to display your tokens.

   % tokens

The following output indicates that you have no tokens:

   Tokens held by the Cache Manager:
       --End of list--

If you have one or more tokens, the output looks something like the following example, in which the tokens for AFS UID 1022 in the abc.com cell expire on August 3 at 2:35 p.m. The tokens for AFS UID 9554 in the stateu.edu cell expire on August 4 at 1:02 a.m.

   Tokens held by the Cache Manager:
   User's (AFS ID 1022) tokens for afs@abc.com [Expires Aug   3 14:35]
   User's (AFS ID 9554) tokens for afs@stateu.edu [Expires Aug   4  1:02] 
      --End of list--

Example: Authenticating in the Local Cell

Suppose that user terry cannot save a file. He uses the tokens command and finds that his tokens have expired. He reauthenticates in his local cell under his current identity by issuing the following command:

   % klog
   Password:  terry's_password

The he issues the tokens command to make sure he is authenticated.

   % tokens
   Tokens held by the Cache Manager:
   User's (AFS ID 4562) tokens for afs@abc.com [Expires Jun 22 14:35]
      --End of list--

Example: Authenticating as a Another User

Now terry authenticates in his local cell as another user, pat. The new token replaces terry's existing token, because the Cache Manager can store only one token per cell per login session on a machine.

   % klog pat
   Password: pat's_password
   % tokens
   Tokens held by the Cache Manager:
   User's (AFS ID 4278) tokens for afs@abc.com [Expires Jun 23 9:46]
      --End of list--

Example: Authenticating in a Foreign Cell

Now terry authenticates in the stateu.edu cell where his account is called ts09.

   % klog  ts09 -cell stateu.edu
   Password: ts09's_password
   % tokens
   Tokens held by the Cache Manager:
   User's (AFS ID 4562) tokens for afs@abc.com [Expires Jun 22 14:35]
   User's (AFS ID 8346) tokens for afs@stateu.edu [Expires Jun 23  1:02]
       --End of list--

Limits on Failed Authentication Attempts

Your system administrator can choose to limit the number of times that you fail to provide the correct password when authenticating with AFS (using either an AFS-modified login utility or the klog command). If you exceed the limit, the AFS authentication service refuses further authentication attempts for a period of time set by your system administrator. The purpose of this limit is to prevent unauthorized users from breaking into your account by trying a series of passwords.

To determine if your user account is subject to this limit, ask your system administrator or issue the kas examine command as described in To Display Your Failed Authentication Limit and Lockout Time.

The following message indicates that you have exceeded the limit on failed authentication attempts.

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

To Display Your Failed Authentication Limit and Lockout Time

Issue the kas examine command to determine if there is a limit on the number of unsuccessful authentication attempts for your user account and any associated lockout time. You can examine only your own account. The fourth line of the output reports the maximum number of times you can provide an incorrect password before being locked out of your account. The lock time field on the next line reports how long the AFS authentication service refuses authentication attempts after the limit is exceeded.

   % kas examine your_username
   Password for your_username: your_AFS_password

The following example displays the output for the user pat, who is allowed nine failed authentication attempts. The lockout time is 25.5 minutes.

   User data for pat
    key (15) cksum is 3414844392,  last cpw: Thu Oct 21 16:05:44 1999
    password will expire:  Fri Nov 26 20:44:36 1999
    9 consecutive unsuccessful authentications are permitted.
    The lock time for this user is 25.5 minutes.
    User is not locked.
    entry never expires. Max ticket lifetime 100.00 hours.
    last mod on Wed Aug 18 08:22:29 1999 by admin
    permit password reuse