UNIX: Guide To The AFS

--> --> UNIX: Guide To The AFS -->

Table Of Contents
Introduction To AFS
Who Is Using AFS
Home Directory Structure In AFS
Tokens And Tickets
Access Control Lists (ACLs)
Quotas on AFS Home Space
AFS Commands Quick Reference
Using Your GLUE Account From WAM
Using Your WAM Account From GLUE

Introduction To AFS
(Back to Table Of Content)

AFS is a distributed global file system that operates in the client-server model. It can effectively function in large wide area networks that span the entire globe as well as in small local area networks.

AFS is based on a distributed file system originally developed at the Information Technology Center at Carnegie-Mellon University. It was called the "Andrew File System."

An AFS administrative group of servers and clients is known as a "Cell." Our local cell, containing all the machine in the GLUE system, is called `glue.umd.edu.' A similar AFS cell exists for all the WAM machines.

Files within AFS are named as `/afs/<CELLNAME>/filepath', and such path names are uniform on all AFS clients anywhere in the world. So, for example, following paths are valid from any AFS client in the world.

/afs/glue.umd.edu/department/isr/local/lib/libatm.a
/afs/transarc.com/common/etc/CellServDB

In an AFS file server, the files and directories are contained in an "AFS volume." The size of a volume is generally larger than a directory and smaller than a disk partition. Every user is given a volume, of pre-determined size, for his or her home space and mail spool.

In addition, in conjunction with Kerberos, AFS provides a global authentication system (all passwords are verified with a site-wide database).

Who Is Using AFS
(Back to Table Of Content)

Everyone on the WAM computer system is using AFS.

Only some of the people on the Glue computer system are using AFS. To determine such information, login to a Glue machine (e.g. ssh to glue.umd.edu) and issue the pwd command. For example, if one's Glue login name is <USERID>, one would see something similar to the following after logging into glue.umd.edu:

         z:~: pwd
         /afs/glue.umd.edu/home/glue/<U>/<S>/<USERID>/home
         z:~:

Where will be the first character of their <USERID> and <S> will be the second character of their <USERID>.

The output of the pwd command describes the path to Glue home directory. If the home directory path does not start with /afs/glue.umd.edu, it is not using AFS.

Home Directory Structure In AFS
(Back to Table Of Content)

Every user is given an AFS volume entirely for him or herself. The size of the volume determines the disk quota for the user.

Let's imagine a user with the user-name "<USERID>" This <USERID> is given an AFS volume h.glue.<USERID> or h.wam.<USERID> and it is mounted at /afs/glue.umd.edu/home/glue//<S>/<USERID> or /afs/wam.umd.edu/home/wam//<S>/<USERID> where will be the first character of their <USERID> and <S> will be the second character of their <USERID>. This mount point is also equivalent to /users/<USERID>/.

The directory, /users/<USERID>/, contains the following sub-directories.

/users/<USERID>/home/ - <USERID>'s home space (equivalent to /homes/<USERID>/). The entire home space for the user lies under this directory.
/users/<USERID>/mail/ - <USERID>'s mail spool (equivalent to /mail/<USERID>/). Note that the user's mail spool is now a part of the user's AFS volume. This means that any mail that the user receives also counts towards the user's disk quota. If the user is over the disk quota, e-mail intended for him/her will bounce.
/users/<USERID>/pub/ - <USERID>'s public directory (equivalent to /pub/<USERID>/). This is where all the public files, including html files such as welcome.html must be kept. The /users/<USERID>/home directory is normally closed off to other users and the web servers. While the user is able to open up his/her home directory to other users, it is not recommended. Instead, users are encouraged to use /users/<USERID>/pub/ (/pub/<USERID> in our example) directory to make available any files to other users. Note that, a directory called "public_html" is no longer needed for the web pages.
/users/<USERID>/backup/ - This contains a snapshot of the <USERID>'s file system, taken at 4:00 am on the same day. If <USERID> deletes a file from the home space by mistake, he can cd into /users/<USERID>/backup/ and navigate through the backup file system to find the deleted file and copy it back to the working home space. If <USERID> does not copy the file back on the same day, it will not be available the following day as a new backup volume is created at 4:00 am the following morning.

Tokens And Tickets
(Back to Table Of Content)

When a user logs in, he/she is issued a Kerberos ticket and an AFS token by the login process. Kerberos is used to improve the security so that your password is not transmitted over the network in the clear.

The AFS token is used for file permission/authentication as AFS supersedes normal Unix permissions. To access files which are protected by the AFS permission mechanism, you must have a valid AFS token for each AFS cell. You may see what tokens you currently hold using the `tokens' command. For example:

   % tokens
   Tokens held by the Cache Manager:

     User's (AFS ID 1) tokens for afs@alw.nih.gov [Expires Dec  5 13:39]
        --End of list--

This output says that the user holds a token for the cell `alw.nih.gov' for AFS user ID 1. You may hold extra tokens for different cells, but you can have only one token per AFS cell. Tokens expire after a 25-hour period.

Obtaining an AFS token

If you see `Glue 1.5 Login' during your normal login process, it means a token has been automatically obtained for you. You can verify that you have a valid token with the `tokens' command. If you do not have a token or your token has expired you may obtain a one using the 'klog' command or 'renew' command. (The 'renew' command will also give you a new kerberos ticket.)

   % renew
   University of Maryland, GLUE.UMD.EDU (dollar.glue.umd.edu)
   Kerberos Initialization for "goblin"
   Password: type_your_regular_unix_password

Note:

Even when you log in using AFS login, you will still need to know how `klog' works, as your tokens will still expire after 25 hours.

If you wish to access another user's files temporarily, it is not necessary to log out and log in again. Just issue a `klog user' command and continue as the other user. (That is, of course, provided that the other user is with you to type his/her password in, as users should not share passwords with each other. See the next section about permissions for a better way to share files.)

Getting rid of a token

If you wish to destroy your token for a cell, you can use the `unlog' command. This is useful, for example, when you authenticate as someone else temporarily, and then want to destroy the token. Similarly, you can destroy your Kerberos ticket by issuing the command 'kdestroy'.

Access Control Lists (ACLs)
(Back to Table Of Content)

In AFS, every directory has an Access Control List (ACL). The ACL specifies protection at the directory level (not file level) by listing permissions of users and/or groups to a directory. There is a maximum of 20 entries per ACL.

Listing the ACLs: You can list the ACL on any directory by issuing the command:
```
   % fs listacl
   Access list for . is
   Normal rights:
     fac:coords rlidwka
     system:anyuser rl
```
This shows that fac:coords group has full access rights to that directory, while one of the system defined groups, system:anyuser, has read and lookup permissions. The command fs listacl can be abbreviated by fs la. For command options, fs la -h.
Setting the ACLs: Those who have the administer permissions in the directory can modify the ACL for a directory.
```
 % fs setacl <DIRECTORY> <USERID> <ACCESS>
```
The command fs setacl can be abbreviated as fs sa. For command options, fs sa -h. To remove all the permissions, one can set the ACL to none. While experimenting with the settings of ACLs, please be sure not to remove the "a" permission for yourself from the ACLs or you will not be able to change the ACL afterwards. Here are some examples, assuming the directory you wish to modify is the current directory ("."):
```
 % fs sa . system:anyuser none
 % fs sa . system:authuser rl
 % fs sa . goblin read
```

ACL Access Rights: There are seven access rights that can be set.

   lookup          l       Permission to examine the ACL and traverse the
                           directory (needed with most other access rights).
                           Permission to look up filenames in a directory.
   read            r       View the contents of files in the directory
   insert          i       Add new files or sub-directories
   write           w       Modify file contents, use "chmod"
   delete          d       Remove file(s) in directory
   lock            k       Permission for programs to "flock" files
                           in the directory
   administer      a       Ability to change the ACL

   There are short-hand forms:

   read            rl      read and lookup
   write           rlidwk  all rights except administer
   all             rlidwka
   none                    removes all rights

Note that the permissions set by the unix chmod are referenced for all users as if they were the owner. So you must have the read, write, or execute bits set by unix for any user to read, write, or execute the file, in addition to having their AFS ACL correctly set.

System defined protection groups: Following groups are defined by the system. Other groups can be defined by the users. (For more information, man pts or pts help.)

   system:anyuser         -- Anyone who has access to any AFS client in any
                             cell. This is literally open to the world.
   system:authuser        -- Anyone who has a valid AFS token in our local cell.
   system:administrators  -- Users who have privileges to execute some but not
                             all system administrator commands.

GLUE and ISR defined protection groups: You may see some of the following protection groups in your directories, in addition to the above system defined ones. You may decide to remove these groups from your directory ACLs. We recommend that you do not alter these permissions.
```
   system:isr-managers    -- ISR Computing Unit staff only.
   system:glue-postmaster -- This group must have rlidwk permissions in the
                             /mail/$user directory to deliver your mail.
```

Quotas on AFS Home Space
(Back to Table Of Content)

Each AFS home space has a quota. This is the maximum amount of disk space that you can use for all of your files including your mail and public files such as your web documents.

To see what your quota is, type:

quota

while in your home directory. The amount is in K (kilobytes, or 1024 bytes).

An example of a quota is the following:

% quota
Volume Name            Quota    Used    % Used 
h.glue.<USERID>         7500    5194     69%
<user volume>      <max size> <amt used> <%age>

You will want to make sure you do not run over your allotted space. Some programs will stop working, and you will not be able to receive any more mail. Any mail will bounce back to the sender. We have instructions on how to reclaim disk space.

AFS Commands Quick Reference
(Back to Table Of Content)

This table lists the most common AFS commands used by users. All commands have two help functions: command help and command option -help.

File Service Commands
`fs listquota <PATH>` `fs lq <PATH>`	list the AFS quota for the volume containing file or directory <PATH>. If no path is specified, the current directory is used.
`fs listacl <PATH>` `fs la <PATH>`	List the Access Control List for the directory <PATH> (or the directory containing <PATH>). If no path is specified, the current directory is used.
`fs setacl <PATH> <USER> <ACl>` `fs sa <PATH> <USER> <ACl>`	Set the Access Control List for the user user on the directory path.
`fs copyacl <SRCPATH> <DESTPATH>`	Copy the Access Control Lists from the directory <SRCPATH> to the directory <DESTPATH>. Note that this does not delete the existing Access Control Lists from <DESTPATH>.
`fs whereis <PATH>`	Print the name of the AFS Fileserver for the volume containing file or directory <PATH> If no path is specified, the current directory is used.

AFS Group Commands
`pts creategroup <USERID>:<GROUP>`	Create a group named <USERID>:<GROUP>. <USERID> must be your <USERID>.
`pts adduser <USER> <USERID>:<GROUP>`	Add user <USER> to group <USERID>:<GROUP>. Usually <USERID> is your <USERID>.
`pts removeuser <USER> <USERID>:<GROUP>`	Remove user <USER> from group <USERID>:<GROUP>. Usually <USERID> is your <USERID>.
`pts membership <USER>`	List the groups <USER> is a member of
`pts membership <USERID>:<GROUP>`	List the members of group <USERID>:<GROUP>
`pts listowned <USERID>`	List the groups owned by <USERID>

Authentication Commands
`tokens`	Print information about the AFS Authentication Token of the current process authentication group (PAG).
`klist`	Print information about the Kerberos tickets you currently own.
`renew`	Renew/Create Kerberos Ticket and AFS Token
`unlog`	Destroy the current AFS tokens.
`kdestroy`	Destroy the current Kerberos tickets.

Miscellaneous Commands
`up <SRCPATH> <DESTPATH>`	Recursively copy <SRCPATH> to <DESTPATH>, preserving AFS Access Control Lists.

Using Your GLUE Account From WAM
(Back to Table Of Content)

Determine the user's home directory

In order to access a Glue home directory using a WAM Unix client, the path to the user's Glue home directory must be known and must begin with /afs/glue.umd.edu. To determine such information, see Who Is Using AFS

Use the klog command

Once the path to one's Glue home directory has been determined, the next step after logging into a WAM machine is for the user to authenticate to the Glue afs cell using the klog command. (This must be done each time a Glue session is initiated from a WAM client.) Using the <USERID> user-name example from above:

        rac1:~: klog <USERID>@glue.umd.edu
        Password:
        rac1:~:

Change to the glue home directory

After the user's Glue password has been accepted and the user's identity has been authenticated, he/she will be able to change to the Glue home directory (using the cd command) and have full access to his/her Glue files.

        rac1:~: cd /afs/glue.umd.edu/home/glue/<U>/<S>/<USERID>/home
        rac1:/afs/glue.umd.edu/home/glue/<U>/<S>/<USERID>/home: ls
        Mail     welcome
        rac1:/afs/glue.umd.edu/home/glue/<U>/<S>/<USERID>/home:

Note:

Where will be the first character of their <USERID> and <S> will be the second character of their <USERID>.

Tip: Make a link to glue

To make the process simpler, the user may create a link in his/her WAM home directory that points to the Glue home directory (call the link glue, for example). Then, after being authenticated, the user may simply cd to 'glue', as in the following example:

        rac1:~: ln -s /afs/glue.umd.edu/home/glue/<U>/<S>/<USERID>/home glue
        rac1:~: cd glue
        rac1:~/glue:

Finish up by using unlog

Once finished with the Glue files, the user should un-authenticate from the Glue cell using the 'unlog' command., This will make the Glue files inaccessible, and will leave the user in the WAM environment:

        rac1:~: unlog glue.umd.edu
        rac1:~:

Using Your WAM Account From GLUE
(Back to Table Of Content)

Determine the user's home directory

In order to access a WAM home directory using a Glue Unix client, the path to the user's WAM home directory must be known. To determine such information, see Who Is Using AFS

Use the klog command

Once the path to one's WAM home directory has been determined, the next step after logging into a Glue machine is for the user to authenticate to the WAM afs cell using the klog command. (This must be done each time a WAM session is initiated from a Glue client.) Using the <USERID> user-name example from above:

        z.glue.umd.edu:~: klog <USERID>@wam.umd.edu
        Password:
        z.glue.umd.edu:~:

Change to the WAM home directory

After the user's WAM password has been accepted and the user's identity has been authenticated, he/she will be able to change to the WAM home directory (using the cd command) and have full access to his/her WAM files.

        z.glue.umd.edu:~: cd /afs/wam.umd.edu/home/wam/<U>/<S>/<USERID>/home
        z.glue.umd.edu:/afs/wam.umd.edu/home/wam/<U>/<S>/<USERID>/home: ls
        Mail     welcome
        z.glue.umd.edu:/afs/wam.umd.edu/home/wam/<U>/<S>/<USERID>/home:

Note:

Where will be the first character of their <USERID> and <S> will be the second character of their <USERID>.

Tip: Make a link to WAM

To make the process simpler, the user may create a link in his/her Glue home directory that points to the WAM home directory (call the link WAM, for example). Then, after being authenticated, the user may simply cd to 'WAM', as in the following example:

        z.glue.umd.edu:~: ln -s /afs/wam.umd.edu/home/wam/<U>/<S>/<USERID>/home WAM
        z.glue.umd.edu:~: cd WAM
        z.glue.umd.edu:~/WAM:

Finish up by using unlog

Once finished with the WAM files, the user should un-authenticate from the WAM cell using the 'unlog' command., This will make the WAM files inaccessible, and will leave the user in the Glue environment:

        z.glue.umd.edu:~: unlog wam.umd.edu
        z.glue.umd.edu:~:

How do I:
Get an account Change a password Set up e-mail Eliminate a computer virus Protect myself from computer viruses	Use the network Find a computer lab Use Coursemail Use ELMS Check my Directory information	Set or change my Directory password Find my IP address Use the LPCR teller Troubleshoot an e-mail problem