Introductory Guide To AFS Compiled by Larry Schwimmer (schwim@cs.stanford.edu) Last Revised: 15 Nov 1994 Archive-name: stanford/afsguide AFS-name: /afs/ir.stanford.edu/users/c/consult/pub/afs/afsguide Gopher: dcc.stanford.edu:/consult/afs/afsguide Section 0. INTRODUCTION: What is AFS? Section 1. AFS FILE PERMISSIONS 1.1 The Access Control List (ACL) 1.2 Examining and changing an ACL: fs listacl, fs setacl 1.3 Determining your quota: fs listquota 1.4 Abbrev. -- fs and ACL permissions shortcuts 1.5 Getting Help! 1.6 Recovering Files - fs mkmount, fs rmmount Section 2. TOKENS 2.1 A token: your ticket to AFS 2.2 The tokens and klog commands SECTION 3: ACCOUNT SETUP 3.0 The Default Setup 3.1 Setting Up A Dotfiles Subdirectory 3.2 Creating Public, Project, and Friends Directories 3.3 Privacy Precautions *************************** * SECTION 0: INTRODUCTION * *************************** Have you ever wondered how you could access your account from multiple machines? Filing systems such as NFS and AFS allow a central "server" machine to provide remote access to files for multiple "client" machines. NFS is established; AFS is still under development. People with NFS accounts can convert their account to AFS by logging into cardinal and running converttoafs. This process is irreversible, so you should be aware of the differences between the two systems before converting: 1) Wider Access Unlike NFS, the AFS server authenticates users, not machines. This allows people with an AFS account to access their account files from any machine that mounts the AFS filing system, such as the residential NeXTs and Terman cluster. 2) File Permissions AFS allows greater control over the file permissions of one's directories. Individuals can grant privileges to individuals or user-created groups. This is ideal for group projects. AFS users need to learn a new set of commands and file permissions. The important ones are covered in this document. File permissions under AFS are set by directory, not file. This makes setting up your account a little more difficult if you use a .forward, .plan, or .rhosts file. 3) File Restores Each night, the AFS server creates a backup of your account which you can access. This sometimes allows you to undelete files you accidently deleted or overwrote. 4) Better Network Performance Under AFS, files are maintained by a central server. Client machines cache files they access to the local disk. If a client machine updates a file, it updates a local copy and sends the update to the server. In contrast, NFS requires that filing systems be synchronized; this is not feasible across a large network connected by routers, like Stanford's. NFS works well on small and medium size networks, but is not suited for a large network like Sweet Hall's. ******************************* * SECTION 1: FILE PERMISSIONS * ******************************* =================== 1.1 AFS Permissions =================== 1.1.1 The Access Control List (ACL) ----------------------------------- Under AFS, permissions are set by directory not by file. Every file in a directory has the same permission. New directories inherit the parent's permissions. A directory's permissions is contained in the Access Control List (ACL). An ACL may have up to twenty entries. There are seven permissions you can set: l Lookup Allows user to ls the directory and examine its ACL A user needs l privilege to a parent directory to access a subdirectory of or file in a directory. r Read Allows user to read or copy any file in the directory. w Write Allows user to modify any existing file in the directory. This includes chmod permissions. k Lock Allows user to flock a file, ensuring two processes do not write simultaneously to the file. i Insert Allows user to add new files and create new subdirectories d Delete Allows user to remove files and empty subdirectories a Administer Allows user to change the ACL for a directory. Users always have this right for their home directory and their subdirectories even if they remove themselves from the ACL NOTE: read, write, lock, insert, delete, and administer permissions all require lookup permission. The filing system cannot tell what file permissions the user has without lookup privilege. Similarly, users cannot access a subdirectory unless they have lookup privileges for ALL its parent directories. 1.1.2 Examining And Changing An ACL: fs listacl, fs setacl ---------------------------------------------------------- The command fs is used to examine and change the ACL. It has a whole suite of subcommands; the major ones are fs listacl, fs setacl, and fs listquota. * LISTING THE ACL If you have lookup privileges to the directory, type: fs listacl Where is the directory you are interested in. To list all the subdirectories, type: fs listacl * * CHANGING THE ACL If you have administer privileges, type: fs setacl Where is the directory, is the username, and are the AFS permissions. * EXAMPLES 1. Listing an acl: elaine:~ >fs listacl ~consult Access list for /afs/ir/users/c/consult is Normal rights: system:administrators rlidwka system:anyuser rl consult rlidwka 2. Giving read and lookup privileges to any user for your home directory: fs setacl ~ system:anyuser rl 3. Removing privileges for your private directory: fs setacl private system:anyuser none 4. Giving user frank lookup, read, insert, and write privileges to the directory project: fs setacl project frank lriw 1.1.3 Determining Your Quota: fs listquota ------------------------------------------ To list your disk quota, type: fs listquota 1.1.4 Abbrev. -- fs And ACL Permissions Shortcuts ------------------------------------------------- Each of the fs commands has an abbreviation: fs setacl is fs sa fs listacl is fs la fs listquota is fs lq There are shortcuts for the ACL permissions read rl write rlidwk all rlidwka none (none -- removes user from acl) 1.1.5 Getting Help! ------------------- Many AFS commands can be executed with a help argument or flag. To get a list of the fs subcommands, type: fs help To get a somewhat cryptic syntax list for a subcommand, you can type: fs -help To get the worthless manual page, type: man fs If it doesn't mention AFS, then add the following line to your .login: setenv MANPATH '/usr/man:/usr/local/man:/usr/pubsw/man:/usr/pubsw/X/man' That should give you a reasonable man page path. 1.1.6 Recovering Files - fs mkmount, fs rmmount ----------------------------------------------- Between 2 and 4 AM each night, a backup image of your account is made. If you delete or modify a file in an AFS volume, you may be able to retrieve the file if it existed when the backup image was made. The command: fs mkmount ~/.backup user.$USER.backup will mount your backup volume in the directory named .backup in your home directory. You can use a name other ~/.backup if you want. To unmount the volume type: fs rmmount ~/.backup The backup volume (user.$USER.backup) is a read-only copy of your account. You cannot remove or alter files in the backup volume, and file changes made after the last backup but before the next backup are not available. To restore a file, you must copy the file from the backup volume to your account. Suppose you delete the file ~/mbox. The following commands may recover it (assuming you have sufficient quota and you do it in time): cd fs mkmount ~/.backup user.$USER.backup cp .backup/mbox mbox.bak fs rmmount ~/.backup The recovered file would be named mbox.bak ==================== 1.2 UNIX Permissions ==================== The files contained within your AFS home directory use both AFS (fs command) and Unix (chmod command) file permissions. The only Unix (NFS) permissions which are still applicable under AFS, however, are the permissions for the user. Unix permissions on directories are not used. The command "ls -l" will display the Unix permissions for the files. The command "fs la" will display the AFS permissions for the files. They are not the same thing. For more info on Unix permissions, see the afsexpert file. ********************* * Section 2. TOKENS * ********************* 2.1 A Token: Your Ticket to AFS ------------------------------- When you login to your account, you obtain a "token" that is your validation to the local computer that you are who you say you are. This token has a lifetime of 25 hours. If your token expires, you are considered to be system:anyuser and will lose access to your private directories. 2.2 The tokens And klog Commands -------------------------------- To check if you have a token, run the command tokens. To obtain a new token, run klog. This will prompt you for your password and obtain a new token for you. If your username and AFS username are different, then use klog -x afsusername, where afsusername is your AFS username. If you have trouble finding these commands, they should be located in the directory /usr/afsws/bin. ***************************************************** * SECTION 3: BE SECURE: SETTING UP YOUR DIRECTORIES * ***************************************************** ===================== 3.0 The Default Setup ===================== The default account setup has list privileges for system:anyuser on all your directories except the private directory. The Mailbox directory also has insert privileges. List permission allows any user to get a listing of all your files (but not read them). Insert privileges allows any user to add files to a directory. These are security and privacy problems, which is why I dislike the default setup. The rest of section 3 outlines how to setup your dotfiles (.rhosts, .plan, .project, .forward), create public directories, and increase both account security and openness. A more secure (but more complex) directory setup is outlined in the afsexpert document. It describes a setup that keeps all the files in your home directory private, but enables you to have public and project directories. The average user should find the information below sufficient, though. ======================================== 3.1 Creating A Public Dotfiles Directory ======================================== A public dotfiles directory is the most secure way to make your .forward, .plan, .rhosts, and other dotfiles world-readable: cd ~$USER mkdir .dotfiles fs setacl .dotfiles system:anyuser read The cd command goes to your root directory. The mkdir creates a dotfile subdirectory. The fs command gives read permission to the subdirectory. Now you can make files public. For example, to make your .forward file readable, you type: cd ~$USER mv .forward .dotfiles/ ln -s .dotfiles/.forward The mv moves your .forward file to the now world-readable subdirectory. The ln creates a "symbolic link" from the file .dotfiles/.forward to your root directory. You can do the same for your .plan, .project, and .rhosts files, if you have them. It can also be helpful to consultants if you make your .cshrc and .login files accessible. For example, cd ~$USER/ mv .plan .project .cshrc .login .rhosts .dotfiles/ ln -s .dotfiles/.plan ln -s .dotfiles/.project ln -s .dotfiles/.cshrc ln -s .dotfiles/.login ln -s .dotfiles/.rhosts If you are using filter or some other mail filter, then you also need to have the file .elm/filter-rules world-readable. You will not be able to get a filter summary (that is too great a security risk) or save files to your account, though. The best solution for that is to use a filter that can process your mail just before you read it. ===================================================== 3.2 Creating Public, Project, and Friends Directories ===================================================== 3.2.1 Overview -------------- One of the powers of AFS is its file permissions (see section 1.1 for an overview). You can grant permissions to individual users or groups. Since AFS permissions are by directory, you only need to setup the permissions on the directory and its existing subdirectories. Files inherit the permissions of their directory. New subdirectories inherit their parent directory permissions. In order for a user to access a subdirectory, at least list (l) permission MUST be given on every parent directory of the subdirectory. If you use the home directory setup described in afsexpert, then these directories must be created in ~$USER, not your home directory. You can then make a symbolic link from your home directory to the new directory. 3.2.2 Creating a Public Subdirectory ------------------------------------ Here's some example commands that will create a public directory: cd ~$USER mkdir pub fs sa pub system:anyuser read The cd command moves you to your root directory. The mkdir command creates a directory named pub. The fs command makes the directory readable for any user. Any subdirectories that you create in pub will also be public (since newly-created subdirectories inherit the permission of their parent directory). If you move a directory into this directory or use a symbolic link, however, you may need to adjust the permissions. 3.2.3 Public Insert Directories ------------------------------- Directories which provide insert privileges for anyone are a security hole. Anything added to this directory applies to your quota, so you need to watch the directory. If you do setup such a directory, it needs a minimum of system:authuser li. It should have at a maximum system:authuser rliw. If you use a subdirectory that someone added to your insert directory, be sure to change the file permissions back to system:authuser none and to what it should be (public directories should have system:anyuser read). 3.2.4 Project or Friend Directories ----------------------------------- Suppose you are working a project with curley and moe. Here's some commands that will create a project directory: cd ~$USER mkdir stooge fs sa stooge curley write fs sa stooge moe write The cd command moves you to your root directory. The mkdir command creates a project directory named stooge. The fs commands give users curley and moe write to that directory. (Be sure that you do not go over quota!) If you want others to be able to read the files, you can use fs sa stooge system:anyuser read If you do not want them to have any access, use fs sa stooge system:anyuser none For a final example, suppose you are going to be creating five subdirectories: public, private, moe, curley, and larry. Since the names should be obvious, here's how to set them up: (1) Put list on the root project directory (stooge). This is required to allow users to get to stooge/public. fs sa stooge system:anyuser l (2) Create the public directory and make it world-readable. cd stooge mkdir public fs sa public system:anyuser read (3) Now create the private directory. mkdir private fs sa private system:anyuser none (4) Now a directory to contain details of pranks to be pulled on curley: mkdir moe fs sa moe curley none fs sa moe system:anyuser none And on moe: mkdir curely fs sa curley moe none And on both of them: mkdir larry fs sa larry moe none curley none And finally, let us strip system:anyuser from these directories fs sa -dir larry curley moe -acl system:anyuser none ======================= 3.3 Privacy Precautions ======================= 3.3.1 Setting Up Your Directories --------------------------------- There are several directories in your account which you do not want people snooping through. There are also some directories that you may have which you do not need. The following will remove worthless directories: rmdir Mailbox PrintDir If you use elm or the NeXT, then you should remove access permissions from your Mail, .elm, .NeXT, and Mailboxes directories. First, make sure these directory exists. Then remove permissions from the directories: cd ~$USER mkdir Mail .elm .NeXT Mailboxes fs sa Mail system:anyuser none fs sa .elm system:anyuser none fs sa .NeXT system:anyuser none fs sa Mailboxes system:anyuser none The mkdir command may generate a "file exists" error. This is not a problem. 3.3.3 Protecting Files ---------------------- There are files which you will likely want private. You can do this by making the files symbolic links to your private directory, which has no permissions for anyone but yourself. The following example will do this: cd mv mbox .mailrc private/ ln -s private/mbox ln -s private/.mailrc Use mv and ln -s as shown above to protect other files you want private. 3.3.4 Setting Up Preferences ---------------------------- In your .mailrc file, add the lines: set folder=private set outfolder set DEAD=private/dead.letter This will force mail messages to be saved in your private directory. If you save outgoing messages, then be sure that your record variable points to a file in a private directory. =========================================================================== -- I hope this provides a good overview. If you have any comments, corrections, or questions, feel free to write back. Questions can be mailed to consult@leland.Stanford.EDU or posted to su.computers.afs.