 
|
||||||||||||||||||||||||||||||||||||||||||||||
|
Last Revised: December 14th, 2005 NOTE: This document was shamelessly stolen SLAC! Contents About this Guide Authentication and Authorization Online AFS Command Help File Backup Default ACL for Your AFS Home Directory AFS Command Summary ACL Commands Online AFS Help Commands Miscellaneous AFS Commands The Andrew File System (AFS)® was pioneered at Carnegie Mellon University, then supported and further developed as a product of the Transarc® Corporation (now IBM Pittsburgh Labs). IBM made a copy of the source available for community development and maintenance. They called the release OpenAFS. This guide is an introduction to OpenAFS as implemented at UW-HEP. It describes basic AFS concepts, defines terms, and shows how to use basic AFS commands. If you are a UNIX user familiar with the NFS distributed file system, you will find AFS similar to NFS. AFS fits into the UNIX directory structure starting at the root (/), and this is a point of commonality between AFS and NFS. You will notice that you will be able to share files easily with a greater number of people including those from other institutions. Most application programs, text editors for example, will work as they did do in NFS (for exceptions, see Gotchas). However, differences that you will need to learn about include file sharing, authenticating yourself as an AFS user, and access control lists (ACLs), a mechanism which essentially replaces UNIX file permissions for controlling access to files.
-help
Familiarity with basic UNIX commands, such as cd (change directory), ls (list files), cp (copy file), and mv (move file), is assumed.The Andrew File System (AFS)® is a distributed file system that allows multiple machines to share access to a set of files in a uniform way. Files are stored on disk volumes of AFS server machines and accessed through the cache manager on AFS client machines. That means that files are stored on various machines connected to the network and sent to client machines, such as yours, when you want to access them. When a file is requested, AFS calls on the cache manager, your agent in accessing files stored in the AFS file space, to copy the portion of the file on which you are working to your workstation’s local disk. You don’t need to know on which server machine disk or volume the file you want is physically stored because AFS automatically finds it. In many ways AFS is similar to NFS. Significant advantages of AFS include:
Authentication and Authorization AFS uses authentication and authorization as its primary security techniques to ensure that files are accessed only by authorized users. Whenever you login to UNIX, AFS checks the password you supply to make sure that you are who you say you are. If you are, AFS grants you a token and thereby authenticates you as a valid AFS user and logs you into UNIX. Authorization determines what actions you may or may not perform on AFS files via the Access Control List (ACL) mechanism. This mechanism is based on authentication. AFS Access Control Lists which are discussed in detail in AFS File Protection: Access Control Lists and Protection Groups A token identifies you to AFS and is used as the AFS file server and the client machine work together to give you access to your files. Without it, your access will be limited. After you have established a UNIX account, whenever you login to UNIX you will automatically be given a token except under certain limited circumstances when issuing the ssh (secure shell for remote login to UW-HEP hosts) command. You will have only one token on each machine at UW-HEP to which you log on, but may have additional tokens for foreign (that is, non-UW-HEP) machines that run AFS. A UW-HEP token expires after 25 hours of being continuously logged in to UNIX and may be renewed with the klog command. The tokens command shows whether or not you have a token(s). A token, stored by the cache manager, is usually associated with one logon session on one host computer. If you’re using X Windows on a workstation, you need to authenticate once on that system. Then you can open as many windows with that AFS token as you want. However, if you then ssh (that is, log on to another system remotely from your workstation) to another host system, in most cases you must authenticate again to get a token on that system. Many people wonder: when do I have a token? when don’t I? The answer is:
See Authentication_Commands for details on the commands tokens, klog, and unlog. AFS, like other UNIX file sytems, uses a hierarchical file structure or tree structure. Directories, which are files that contain other files instead of text or data, are organized like inverted trees. There is a single AFS tree for the whole world. The root directory in AFS is named /afs. All subdirectories of the root are called cells. Your directories and files will be subdirectories of the cell named /afs/hep.wisc.edu or more simply /afs/hep when referred to from a computer on the UW-HEP network.Cells other than /afs/hep are known as foreign cells. Finding the names or locations of files in a foreign cell and then accessing them is rather like finding out the e-mail address of someone at another institution: contact the person with whom you want to share files and arrange for the appropriate file access controls and authentication. See Authentication_Commands for more information.Files within AFS are named /afs/cellname/pathname. For example, my home directory is named:afs/hep/home/ilse " /home/ilse" is a pointer to one’s home directory via a symlink from /home to /afs/hep/home.The cache manager is a process that requests data on your behalf from the server machines and stores a copy on your machine. You then work on the copy which reduces the number of network requests to the server. When you (or someone else) closes or saves the file, the changes to the file are transmitted to the server. There is one cache manager for each client machine, such as yours. All AFS data are stored in volumes, which are sections of AFS server disks. Each home directory is in a separate AFS volume. You need to be aware that each volume has a size limit called a quota. Therefore, each user has his or her personal quota of disk space. If you try to exceed the quota, which is given as a number of 1K blocks, AFS will respond with an error message. The command fs listquota tells you the size of your quota and how much of it you have used for your files and directories.For various reasons we like to keep individual volumes under 500MB. If your home directory is larger than this, we prefer to split it into multiple volumes. Other than finding a convenient subset into which to split your subdirectories, this will have no effect on the use of your home directory. If you fill up your initial quota, email help@hep.wisc.edu. and request an increase. AFS has two general types of commands: file server commands ( fs) and directory protection server commands (pts). There are also several authentication commands. fs and pts commands have various subcommands or operation_codes, which indicate the specific function of the command. Examples are: fs listacl, fs listquota, pts creategroup, pts delete, klog, tokens.The command: help will list all the subcommands for the given command name (that is, fs and pts).To get help on a specific subcommand, type: -help Examples:
The help entry lists the subcommand’s arguments in the prescribed order and its flags. If you are trying to do something and don’t know the AFS command, try: apropos -topic "help-string" where help-string is a topical key word. If help-string is more than one word, surround it with single or double quotes. If a match is found, a short description of any commands that match the help-string will be listed. Example:
Each time you log on to UNIX at UW-HEP or when you give the command klog and supply your AFS password, you are authenticated as a valid AFS user and given a token that identifies you to AFS. This token is used as your client machine works with the AFS file server to give you access to data. Remember that the token is good for 25 hours and then expires. When you try to perform an AFS function that needs authorization after your token has expired, AFS will give you an error message, such as "permission denied". Sometimes the text of the message might be more obscure, such as when the token expires while your program is executing. Give the klog command to reauthenticate yourself.To see the tokens you are currently holding, use the tokens command. For example:
If you do not have a token, you will see:
To obtain or renew a token, enter the command: klog. The dialog between you and AFS will look something like this:
If you want to destroy your token, use the unlog command.Before changing your password, be sure to read and understand UW-HEP's guidelines on selecting secure passwords in Password Policy. Choose your new password based on the guidelines in Good Passwords. Authenticating Yourself to a Foreign Cell To access protected directories in a foreign cell:
Here is an example in which user bobcook, who has an account in foreign cell ir.stanford.edu, gives the klog command to obtain a token in that cell. With the klog command he must identify himself (bobcook) and specify the cell name in which he wants to be authenticated (slac.stanford.edu).
User bobcook gives the tokens command to verify that he has been authenticated. Note that he now has two tokens: one for the foreign cell and one for UW-HEP.
A list of foreign cells known to your cache manager is given in the file /usr/vice/etc/CellServDB, which is updated occasionally based on the list maintained by the OpenAFS vendor.Caution Against Listing Directory /afs /afs contains the names of all AFS cells and it can take a very long time to collect them all. Therefore, don’t do cd /afs followed by ls -F, which is the default alias for ls, or an ls -l. Instead, do a /bin/ls.AFS File Protection: Access Control Lists and Protection Groups You may find that the most challenging aspect of learning AFS is how AFS file protection works. We recommend that you read this section to get a sense of what is different about AFS versus UNIX file protection, but not concern yourself about learning all the details at this time. Instead, come back to it as you find you need to understand them. You can set and modify the ACL on your directories with the fs setacl command. ACLs control who may access files and directories. More specifically, they control who may see the names of files in a directory; read, write, delete, or move a file; add or copy new files or directories; and change the ACL.A file uses the ACL of the directory in which it resides; that is, it does not have an ACL of its own. If you move a file to a new directory, it then assumes the ACL of the new directory. To protect a file as in the original directory you must move it to a like-restricted directory.When you create a subdirectory, it assumes the ACL of the parent directory. However, you can modify the ACL for the subdirectory independently after you have created it. But, if the parent directory has a more restrictive ACL than the child, other users might be denied some of the access rights you granted them in the child. Always provide lookup access in the parent directory for someone who has permissions in the subdirectory.AFS_and_the_Permission_Bits describe how permission bits work in AFS. A Typical UW-HEP Directory’s ACL To give you a sense of what an ACL looks like, let’s look at the one for a typical directory, /afs/hep/home/ilse:
In this ACL: Directory and File Access Rights Now that you have a general idea of ACLs, let’s look at them in detail. Unlike UNIX, which has only three basic rights that can be controlled, AFS has seven. These rights are subdivided into two groups: four directory access rights and three file access rights. Directory access rights apply to the directory itself. They are: l (lookup), i (insert), d (delete), and a (administer).(lookup): allows the user to issue the UNIX ls command to list the names of the files and subdirectories in the directory; to examine the ACL for the directory and to access the directory’s subdirectories; and to look at the contents of the directory (i.e., with the UNIX comand ls -l). i (insert): allows the user to add new files and subdirectories to the directory (either new or copies of files or subdirectories). d (delete): allows the user to remove files and subdirectories or move them (where the user has insert rights). a (administer): allows the user to change the ACL for the directory. File access rights apply only to files in the directory. They are: r (read), w (write), and k (lock).(read): allows the user to read and copy the contents of the files. w (write): allows the user to modify the contents of files in the directory and to change their permission bits with the chmod command. k (lock): allows the user to run programs that need to flock files in the directory. When a program locks the file (flock), other users and/or programs cannot read or write the file. This is used to prevent read/write conflicts. The following shorthand forms of multiple access rights are easier to use than the combinations they represent: : includes rlidwk (read, lookup, insert, delete,write, and lock) read: includes rl (read and lookup) all: includes rlidwka (read, lookup, insert, delete, write, lock, and administrator) none: remove the entry A protection group is similar to a UNIX group but you establish and maintain the protection group yourself. Three system-wide protection groups, provided by AFS, are available by default. They are: You can create groups yourself (that is, the group will be owned by you) that are local to UW-HEP’s cell. You can add or delete individuals to the group as needed with pts commands. After you have created a group, you can place it on a directory’s ACL with any permissions you choose, and these then apply to all members of the group. Creating a group simply allows you to give the same access rights to several people all at once instead of for each person separately. For the same reason, it is also easier to change lots of ACLs later by just changing the group.The example below shows how to create a group and add members. Use the commands pts adduser and pts removeuser to add and remove a user, and the commands pts delete and pts rename to delete a group and change a group name.
The fs (file server) command is used to check and set the ACL for directories. Use the command fs listacl directory-name to check the current permissions for a directory.This section will show you how to set and change the permissions in an ACL associated with individual users, system-wide protection groups, and for groups you have created. Remember: a directory’s ACL is inherited from the parent directory and remains that way until you modify it. Copying ACLs Between DirectoriesTo copy an ACL from one directory to one or more other directories, use the fs copyacl command. You can copy the ACL from any directory for which you have lookup right and copy it to any directory for which you have administer right.In the example below, user ilse is in subdirectory telecom and copies the ACL from subdirectory personnel to subdirectory atom-comm.
ACLs for Individual UsersSuppose you have a directory whose contents you want to share with one other user. To give this person complete access to a certain directory and all the files within that directory, you must modify the ACL for the directory. For example, to give user winters access to the directory called doc, user ilse would follow these steps:
system:administrators rlidwka ilse rlidwka
To remove an individual user’s permissions for a directory, use the same command you use to give access. none is the shorthand notations for no access permissions.
To make sure that winters was removed:
ilse rlidwka ACLs for User-Created Protection GroupsTo give access to a directory to a user-created group, use the same command, fs setacl, as for individuals. The example below illustrates how to give members of group ilse:doc all access rights using the shorthand notation all.
ACLs for System-wide Protection GroupsTo change the access on a directory for a system-wide protection group, use the command fs setacl. Do not change the permissions for system:administrators. This example shows how to change the permissions of group system:authuser from lookup and read to lookup, read, and insert files for directory doc.Any AFS-authenticated UW-HEP user can now insert files as well as lookup and read files in directory doc. (Remember to specify all rights, not just the one you want to add.)
Make sure that the correct access rights were assigned.
To make the following directory with standard protection private:
give the command: fs setacl /afs/hep/home/ilse system:anyuser noneThe following shows the revised settings.
If you are an experienced UNIX user, remember that the nine permission bits have very little meaning in AFS. However, AFS does not ignore them entirely. Specifically, AFS pays attentions to the mode bits as follows:
In spite of the above, the UNIX chmod command still turns the file permission bits on and off.25-hour token expiration and not having a token An AFS token expires roughly 25 hours after it was originally obtained. For normal AFS usage, these workarounds will suffice:
Under the circumstances described below such workarounds will not be sufficient. There are certain environments in which a program will be executed and it will not have the token it needs to write into your AFS directory. So, how does a program get a token initially if it doesn’t have one and how does it renew it when necessary? Either adopt the solution described below or store your directories into which the cron job, .forward program, or interactive command needs to write in NFS. Cron jobs. Submit the cron job (that is, a job in which the user requests UNIX to run a specified command according to a specified schedule) with the trscrontab command rather than the crontab command: trscrontab cron-job-name Give the command man trscrontab for more information. Interactive jobs. In another command window on the same host enter the tokens command periodically to see whether your token will soon expire. If so, renew it with the klog command. Default ACL for Your AFS Home Directory Your files and subdirectories in AFS are readable, but not writeable, unless explicitly changed by the owner. The default ACL for your AFS home directory will look something like this:
system:anyuser gives all users, AFS authenticated or not the privilege to issue the UNIX command ls to list the names of the files and subdirectories in your home directory; they may also read the data in the files of your home directory.system:administrators that is, SCS AFS system administrators, have all access privileges (read, lookup, insert, delete, write, lock, and administer) to the subdirectories and files in your home directory. It is our policy that you not remove the system:administrators entry from any ACLs.ilse is the owner of this home directory and has all access privileges as described for system:administrators.Commands summarized in this appendix are only those used in this Guide. See Introduction to AFS for a complete list of AFS commands and a full description of the command syntax. There you will find an explanation of when keywords in arguments (e.g., -dir) must be specified and when they can be omitted, and when multiple occurrences of arguments (e.g., -user username1 username2 ...) are allowed or prohibited.Table 1 summarizes the commands used to make modifications to the ACL for a directory (and therefore to the files within the directory). Remember that you can give access to any groups (system-wide or groups that you or others have created) or you can give access to specific individuals.
Table 2. Online AFS Help Commands
Table 3. Miscellaneous AFS Commands
|