| Chapter 2. Using OpenAFS | ||
|---|---|---|
 |  | |
| Chapter 2. Using OpenAFS | ||
|---|---|---|
| | | |
Table of Contents
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.
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.
On machines that use AFS enabled PAM modules with their login utility, you log in and authenticate in one step. On machines that do not use an AFS enabled PAM modules, you log in and authenticate in separate steps. To determine which type of login configuration 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 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:usernamePassword: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 kinit/aklog command pair as described in To Authenticate with AFS.
If your machine does not use AFS enabled PAM modules, you must perform a two-step procedure:
Log in to your client machine's local file system by providing a user name and password at the login program's prompts.
Issue the kinit command to authenticate with kerberos and obtain a ticket granting ticket ( or TGT).
% kinit
Password: your_Kerberos_password
Issue the aklog command to obtain an AFS token using your TGT.
% aklog
On systems with an AFS enabled kinit program, the kinit program can be configured to run the aklog program for you by default, but running it again has no negative side effects.
If your machine uses a two-step login procedure, you can choose to use different passwords for logging in and authenticating.
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 enabled login utility, which logs you in and authenticates you in one step. Issue the aklog command as described in To Authenticate with AFS. If your kerberos TGT has expired, you will also need to use the kinit command.
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 enabled 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 aklog 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.
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, you must first obtain a kerberos TGT for the realm used to authenticate for that cell. Unfortunately, while AFS tokens have support for multi-realm credentials, most kerberos implementations don't handle this as gracefully. You can control where kerberos stores it's credentials by using the ENV variable KRB5CCNAME. If you want to get a token for a foreign cell, without destroying the kerberos credentials of your current session, you need to follow this sequence of commands.
env KRB5CCNAME=/tmp/test.ticket kinit user@REMOTE.REALM env KRB5CCNAME=/tmp/test.ticket aklog -c remote.realm -k REMOTE.REALM
It's probably a good idea to remove the TGT from the remote realm after doing this. For kerberos implementations that don't use file based ticket caches ( Mac OS X, Windows), you will need to use the graphic kerberos ticket manager included in the OS to switch kerberos identities. You can have tokens for your home cell and one or more foreign cells at the same time.
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 aklog 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 need to run a process in a different PAG. OpenAFS provides the pagsh command to start a new shell in with a different PAG. You will then need to authenticate as described in To Authenticate with AFS.
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 kinit and aklog commands to authenticate as another Kerberos username and obtain an AFS token, 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).
Tokens and Kerberos TGT's 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 kerberos administrators set the default lifetime of your kerberos TGT. The AFS authentication service never grants a token lifetime longer than the current TGT lifetime, but you can request a TGT with a shorter lifetime. See the kinit man page on your system to learn how to use its -lifetime argument for this purpose.
If your machine is not using an AFS enabled login utility, you must authenticate after login by issuing the kinit command and then use aklog to obtain a token. You can also issue these commands at any time to obtain a token with a later expiration date than your current token.
% kinit [userid@KRB5.REALM]
Password: your_kerberos_password
where
is the kerberos userid and realm that you want to get a TGT from. If the machine is properly configured for your local cell and realm, you should not need to specify the kerberos identity.
Your password does not echo visibly appear on the screen. When the command shell prompt returns, you have a kerberos TGT. You then need to use the aklog command to obtain an AFS token.
% aklog [-cell afs.cell.name] [-k KRB5.REALM]
where
is the kerberos realm used to authenticate the AFS cell.
is the AFS cell for which you want a token.
You can use the tokens command to verify that you are authenticated, as described in the following section.
These are two things that are often the same, but each has it's own distinct rules. By convention, kerberos realms are always in UPPER CASE and afs cellnames are in lower case. Thus username@KRB5.REALM is the kerberos identity used for the AFS cell krb5.realm. There is no restriction that the cell and realm names must match, but most sites are set up that way to avoid confusion. In a well configured system you should never need worry about this until you need to access remote realms/cells.
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 example.com cell expire on August 3 at 2:35 p.m. The tokens for AFS UID 9554 in the example.org cell expire on August 4 at 1:02 a.m.
Tokens held by the Cache Manager:
User's (AFS ID 1022) tokens for afs@example.com [Expires Aug 3 14:35]
User's (AFS ID 9554) tokens for afs@example.org [Expires Aug 4 1:02]
--End of list--
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 commands:
% kinit
Password: terry's_password
% aklog
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@example.com [Expires Jun 22 14:35]
--End of list--
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.
% kinit pat
Password: pat's_password
% aklog
% tokens
Tokens held by the Cache Manager:
User's (AFS ID 4278) tokens for afs@example.com [Expires Jun 23 9:46]
--End of list--
Now terry authenticates in the example.org cell where his account is called ts09.
% env KRB5CCNAME=/tmp/temp.tgt kinit ts09@EXAMPLE.ORG
Password: ts09's_password
% env KRB5CCNAME=/tmp/temp.tgt aklog ts09 -cell example.org
% tokens
Tokens held by the Cache Manager:
User's (AFS ID 4562) tokens for afs@example.com [Expires Jun 22 14:35]
User's (AFS ID 8346) tokens for afs@example.org [Expires Jun 23 1:02]
--End of list--
| | | |
| Using OpenAFS with NFS |  | Exiting an AFS Session |