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. logging in login utility commandslogin 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: 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 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. authenticationtokens as proof tokensas proof of authentication Cache Managertokens, use of 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). PAG process authentication group (PAG) setpag argument to klog command 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. authenticationin a foreign cell 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. authenticationas 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 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). tokenslifetime lifetime of tokens 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. aklog command kinit command commandsaklog commandskinit tokensgetting 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 userid@KRB5.REALM 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 KRB5.REALM is the kerberos realm used to authenticate the AFS cell. afs.cell.name 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. checkingtokens commandstokens tokenscommand tokensdisplaying displayingtokens 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-- examplesauthenticating 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-- examplesauthenticating as 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. % 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-- examplesauthenticating in a foreign cell 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-- tokensdestroying unauthenticating exiting an AFS session logging out quitting an AFS session Because logging in and authenticating with AFS are distinct operations, you must both logout and unauthenticate (issue the unlog command to discard your tokens) when exiting an AFS session. Simply logging out does not necessarily destroy your tokens. 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, to prevent other users from using your tokens during your absence. When you return to your machine, issue the aklog command to reauthenticate, as described in To Authenticate with AFS. 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 must have a token during the entire time they need authenticated access to AFS. If you have tokens from multiple cells and want to discard only some of them, include the unlog command's -cell argument. commandsunlog unlog command Issue the unlog command to discard your tokens: % unlog -cell <cell name>+ Omit the -cell argument to discard all of your tokens, or use it to name each cell for which to discard tokens. It is best to provide the full name of each cell (such as example.org or example.com). You can issue the tokens command to verify that your tokens were destroyed, as in the following example. % tokens Tokens held by the Cache Manager: --End of list-- examplesunauthenticating from selected cells In the following example, a user has tokens in both the accounting and marketing cells at her company. She discards the token for the acctg.example.com cell but keeps the token for the mktg.example.com cell. % tokens Tokens held by the Cache Manager: User's (AFS ID 35) tokens for afs@acctg.example.com [Expires Nov 10 22:30] User's (AFS ID 674) tokens for afs@mktg.example.com [Expires Nov 10 18:44] --End of list-- % unlog -cell acctg.example.com % tokens Tokens held by the Cache Manager: User's (AFS ID 674) tokens for afs@mktg.example.com [Expires Nov 10 18:44] --End of list-- After you have unauthenticated, log out by issuing the command appropriate for your machine type, which is possibly one of the following. % logout or % exit or % <Ctrl-d> filesaccessing AFS directoriesaccessing AFS While you are logged in and 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. Just as in the UNIX file system, 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. pathnames AFS pathnames look very similar to 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 every AFS cell's filespace links together their filespaces into a global filespace. AFSaccessing filespace access to AFS filespaceformat of pathnames afs (/afs) directoryas root of AFS filespace format of AFS pathnames Note for Windows users: Windows uses a backslash ( \ ) rather than a forward slash ( / ) to separate the elements in a pathname. Otherwise, your access to AFS filespace is much the same as for users working on UNIX machines. The second element in AFS pathnames is generally a cell's name. For example, the Example Corporation cell is called example.com and the pathname of every file in its filespace begins with the string /afs/example.com. Some cells also create a directory at the second level with a shortened name (such as example for example.com or testcell for testcell.example.org), 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 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/example.com/usr/pat/public doc/ directions/ guide/ jokes/ library/ foreign cellsaccessing system:anyuser groupcontrolling access by foreign users 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. There are two additional requirements: Your Cache Manager's list of foreign cells must include the cell you want to access. Only the local superuser root can edit the list of cells, but anyone can display it. See Determining Access to Foreign Cells. The ACL on the directory that houses the file, and on every parent directory in the pathname, must grant you the necessary permissions. The simplest way for the directory's owner to extend permission to foreign users is to put an entry for the system:anyuser group on the ACL. 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 aklog 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 and kerberos enabled login utility, the password is the same for both logging in and authenticating with AFS. In this case, generally you use a single command, kpasswd, to change the password. But this may vary from system to system, if in doubt contact your local system administrator. If your machine does not use an AFS and kerberos enabled 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 Kerberos password and the UNIX passwd command to change your UNIX password.