![[Return to Library]](../books.gif)
![[Contents]](../toc.gif)
![[Previous Topic]](../prev.gif)
![[Bottom of Topic]](../bot.gif)
![[Next Topic]](../next.gif)
![[Index]](../index.gif)
This chapter explains how to perform four basic AFS tasks: login and authenticate with AFS, end an AFS session, access AFS directories and files, and change your password.
To access the AFS filespace as an authenticated user, you must both log into the local (UNIX) file system of an AFS client machine and become authenticated with AFS. When you log in, you establish your system identity; when you authenticate, you prove your identity to AFS and establish yourself as an authenticated AFS user.
When you authenticate with AFS, you are given a token which your Cache Manager uses on your behalf to prove your status as an authenticated user. Users who are not authenticated (that is, do not have a token) have very limited access to AFS directories and files.
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 must 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.
Provide your username at the initial login: prompt and 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 the following banner appears, your machine uses an AFS-modified login utility, and you are now an authenticated AFS user. (The version is a number that indicates the version of the AFS login software running on your machine.)
AFS (R) version login
However, not all machines using an AFS-modified login utility display the banner. 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.
If your machine does not use an AFS-modified login utility, you must perform a two-step procedure:
% 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 because you are asked to provide a password for each step. It is simplest to use one, though. Talk with your system administrator. |
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; in turn, the servers accept the token as evidence of your authentication. If you do not have a token, AFS considers you to be the anonymous user and your access to AFS filespace is severely limited: you have only the ACL permissions grants to the system:anyuser group.
You can use the klog command to obtain new tokens (reauthenticate) at any time, even after using an AFS-modified login utility that logs you in and authenticates with AFS in one step.
A token is valid only in the cell whose AFS authentication service issued it. The token does not give you any special status in foreign cells. The AFS server processes in a foreign cell consider you to be the anonymous user unless you authenticate with the authentication service there.
You can hold tokens simultaneously for your local cell and for any foreign cells in which you have an account. To obtain tokens in foreign cells, use the -cell argument to the klog command.
If you have an account in a foreign cell, it is simple to access the files in the cell; just authenticate in the cell (using the klog command) and then access the files in those cells by using their standard AFS pathnames. This is simpler than logging in and out of machines in foreign cells. (For information on accessing directories and files, see Accessing Directories and Files in AFS.)
You can get a maximum of one token per cell/per authentication session/per client machine. For example, if you connect to two different machines (using the telnet utility, for example), you get a token for each machine; however, neither machine can use the token of the other.
If you are using the two-step login procedure and you do not include the -setpag argument to the klog command, your token is stored in a structure identified by your UNIX UID number rather than a PAG. This type of identification can cause two problems:
If you already have a token for a particular cell, issuing the klog command overwrites it with a new one. This can be useful if the token is nearing the end of its lifetime and you want to run an extended job in the background. For a discussion of token lifetimes, see Displaying Token Lifetime.
It is possible to authenticate as another user if you know the user's AFS account name and password (it is, of course, unethical to do this without the user's permission). If you use the klog command to authenticate as another user, you retain your own local (UNIX) identity, but the AFS server processes recognize you as the other user. Any token you already have in that user's cell is destroyed because the Cache Manager on your machine can only store one token per authentication session per cell per machine.
Tokens have a limited lifetime. To determine when your tokens expire, issue the tokens command. The output of the command displays the AFS UID number associated with each token and the cell in which it is valid, in addition to the expiration time.
If you are ever unable to perform a task that you normally can, issue the tokens command to check that the relevant token is still valid. If a token expires while you are running a background job that needs authenticated access to AFS, the job can fail.
Your cell's administrators set the default lifetime of your token. If you want a token with a shorter lifetime, you can use the -lifetime argument to the klog command to request it. The AFS authentication service cannot grant a token with a lifetime longer than the default. For instructions on using the -lifetime argument and a discussion of how AFS calculates token lifetime, see the klog reference page in the AFS Command Reference Manual.
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. Include the -setpag argument to store the resulting tokens in a structure that is identified by a PAG.
% klog -setpag Password: your_AFS_password
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.
Use the tokens command to list your tokens.
% tokens
If you have no tokens, the following output appears:
Tokens held by the Cache Manager:
--End of list--
If you have one or more tokens, the output looks something like the following:
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--
In the above example, the tokens listed for AFS UID 1022 in the abc.com cell expire on August 3 at 2:35 p.m. For AFS UID 9554 in the stateu.edu cell, the tokens expire on August 4 at 1:02 a.m.
A 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
When the command shell prompt reappears, terry 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--
Now terry authenticates in his local cell as another user, pat.
% 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--
The token for terry's previous authentication in his local cell is destroyed because the Cache Manager on terry's machine can store only one token per authentication session per 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--
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
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. 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 next line reports how long the AFS authentication service refuses authentication attempts after the limit is exceeded.
% kas examine username Password for username: user's_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 May 20 16:05:44 1999 password will expire: Fri Jul 23 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 Apr 14 08:22:29 1999 by admin permit password reuse
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 to the DCE cell. The dlog command has no functionality with respect to AFS.
Use the dlog command's -cell argument to specify the name of the DCE cell in which to contact the DCE Security Service for DCE credentials. As for AFS tokens, you can have only one set of DCE credentials ticket at a time for each cell during a login session on a given machine, but you can authenticate in multiple cells simultaneously. You can also have AFS tokens and DCE credentials at the same time. If you omit the -cell argument, the dlog command runs in the local cell as defined by the environment variable AFSCELL or the cell name specified in the local /usr/vice/etc/ThisCell file.
To authenticate in a DCE cell, issue the following command:
% dlog -cell <cell name>
The following message indicates that the dlog command interpreter was unable to contact the DCE Security Service:
dlog: server or network not responding -- failed to contact authentication service
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 when prompted by the dpass command. Like the dlog command, the dpass command has no functionality with respect to AFS.
To obtain the DCE password, issue the following command:
% dpass
The following message appears:
Please read the following before entering your password. A standard or customized message appears here. Original password for AFS cell cell_name: AFS_password Re-enter password to verify: AFS_password The new DCE password is : temporary_DCE_password
See the AFS Command Reference Manual and the AFS/DFS Migration Toolkit Administration Guide and Reference for more information on the dlog and dpass commands.
Just as accessing AFS as an authenticated user requires both logging in and authenticating, exiting an AFS session requires both unauthenticating and logging out. Simply logging out does not necessarily destroy your tokens: you must issue the unlog command. The command for logging out depends on your machine type.
You can use the unlog command any time you want to unauthenticate, not just when logging out. For instance, it is a good practice to unauthenticate before leaving your machine unattended so that other users cannot access AFS using your tokens during your absence. When you return to your machine, issue the klog command to reauthenticate.
Do not issue the unlog command when you are running jobs that take a long time to complete, even if you are logging out. Such processes need to have your token as long as they need to obtain authenticated access to AFS.
If you have tokens from multiple cells and want to discard only some of them, include the -cell argument to the unlog command.
When you want to destroy all of your tokens, issue the following command:
% unlog
To verify that your tokens were destroyed, issue the tokens command. The output looks similar to the following.
% tokens Tokens held by the Cache Manager: --End of list--
To unauthenticate from certain cells while keeping your tokens in other cells, issue the unlog command with the -cell argument. It is best to provide the full name of the cell (such as stateu.edu or abc.com).
% unlog -cell <cell name>+
In the following example, a user has tokens in both the accounting and marketing cells at her company. She wants to destroy the token for the acctg.abc.com cell but keep the token for the mktg.abc.comcell.
% tokens Tokens held by the Cache Manager: User's (AFS ID 35) tokens for afs@acctg.abc.com [Expires May 10 22:30] User's (AFS ID 674) tokens for afs@mktg.abc.com [Expires May 10 18:44] --End of list-- % unlog acctg.abc.com % tokens Tokens held by the Cache Manager: User's (AFS ID 674) tokens for afs@mktg.abc.com [Expires May 10 18:44] --End of list--
After you have unauthenticated, log out by issuing the command appropriate for your machine.
% logout
or
% exit
or
% <Ctrl-d>
Once you have logged in and are authenticated, you can access files in AFS just as you do in the UNIX file system. The only difference is that you can access potentially many more files because you are not limited to those on your local disk. Just as in UNIX, you can only access those files for which you have permission. AFS uses access control lists (ACLs) to control access, as described in Protecting Your Directories and Files.
AFS pathnames look very similar to standard UNIX file system names. The main difference is that every AFS pathname begins with the AFS root directory, which is called /afs by convention. Having /afs at the top of the filespace in every AFS cell links together their filespaces into a global filespace.
The second element in AFS pathnames is generally a cell's name, to indicate the cell membership of the file server machine housing the volume that contains the file. For example, the ABC Corporation cell is called abc.com and the pathname of every file in its filespace begins with the string /afs/abc.com. Some cells also create a directory at the second level with a shortened name (such as abc for abc.com or stateu for stateu.edu), to reduce the amount of typing necessary. Your system administrator can tell you if your cell's filespace includes shortened names like this.
The rest of the pathname depends on how the cell's administrators organized its filespace. To learn how a cell has organized its filespace, use the ls command to display the contents of the cell's /afs/cellname directory.
To access directories and files in AFS you must both specify the correct pathname and have the required permissions on the ACL that protects the directory and the files in it.
The user terry wants to look for a file belonging to another user, pat. He issues the ls command on the appropriate pathname.
% ls /afs/abc.com/usr/pat/public doc/ directions/ guide/ jokes/ library/
You can access files not only in your own cell, but in any AFS cell that you can reach via the network, regardless of geographical location. You must meet two additional criteria:
The alternative is for the foreign cell's administrator to create an account for you, essentially making you a local user in the cell. The directory's owner creates an ACL entry for you as for any other local user. To authenticate in the foreign cell, issue the klog command with the -cell argument.
For further discussion of directory and file protection, see Protecting Your Directories and Files.
In cells that use an AFS-modified login utility, the password is the same for both logging in and authenticating with AFS. In this case, you use a single command, kpasswd, to change the password.
If your machine does not use an AFS-modified login utility, there are separate passwords for logging into the local file system and authenticating with AFS. (The two passwords can be the same or different, at your discretion.) In this case, use the kpasswd command to change your AFS password and the UNIX passwd command to change your UNIX password.
Your system administrator can improve cell security by configuring several features that guide your choice of password. Keep them in mind when you issue kpasswd command:
You can change your password prior to the expiration date, but your system administrator can choose to set a minimum time between consecutive password changes. The following message indicates that the minimum time has not yet passed.
kpasswd: password was not changed because you changed it too recently; see your system administrator
kpasswd: Password was not changed because it seems like a reused password
Issue the kas examine command to display your password expiration date and reuse policy. The third line of the output reports your password's expiration date. The last line reports the password reuse policy that applies to you.
% kas examine <username> Password for username: user's_AFS_password
The following example displays the output for the user pat.
User data for pat key (15) cksum is 3414844392, last cpw: Thu May 20 16:05:44 1999 password will expire: Fri Jul 23 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 Apr 14 08:22:29 1999 by admin don't permit password reuse
Issue the kpasswd command, which prompts you to provide your old and new passwords and to confirm the new password. The passwords do not echo visibly on the screen.
% kpasswd Old password: current _password New password (RETURN to abort): new_password Retype new password: new_password
Issue the UNIX passwd command, which prompts you to provide your old and new passwords and to confirm the new password. The passwords do not echo visibly on the screen. On many machines, the passwd resides in the /bin directory, and you possibly need to type the complete pathname.
% passwd Changing password for username. Old password: current_password New password: new_password Retype new passwd: new_password
![[Top of Topic]](../top.gif)