Last modified: Apr 30, 2010 by Loikkanen

AFS: authentication and ACL

1. Generalities

AFS (Andrew File System) is a distributed file system with a tree structure allowing to a whole of workstations distributed over the network to share a whole of files in a coherent way. The top of the AFS tree structure is unique over the world and is /afs.

Each institute which want to use AFS, will have a unique sub-directory under /afs mounting point which is called a cell in the AFS terminology. The cell name for IN2P3 is in2p3.fr (for CERN, it is cern.ch). In consequence, all the files of each users of the Computing Centre who are connected to our workstations, are stored under the /afs/in2p3.fr directory. In parallel, the users who have also access to the CERN workstations inside the CERN cell, have their AFS CERN files under /afs/cern.ch.

One can see at this moment, the huge interest of this file system as a user having access in different cells can transfer its files from a site to another by simply using the cp command. It should only be authenticate on the 2 cells.

In a given cell, the files are remained on data servers and grouped inside entities called volume". The volumes are physical disk partitions on data servers and are managed by a quota mechanism. AFS allows to define user groups and manage the list of group members in its own database. Some arbitrary groups can be created by the users themselves with the pts AFS command. These user groups are independent of the UNIX group id or gid. The AFS groups are used for the AFS files protections.

A given user is identify by his name ("userid"), which correspond to a UNIX uid and is also called an AFS UID. It will always have the same numerical value at IN2P3. The user "home" directory is in a partition which can be shared with other users. The disk space allocated by default to a user is about 1GB. If a user exceed his quota, a warning message will be send. Generally, his quota exceeding does not affected the other users hosted on the same partition. On a client workstation (the workstation where you are logged on), you can access to the data hosted on the data server by a cache mechanism. It is a process which make a local copy of the file you are using and which guarantee the integrity and the confidentiality of the data through the network.

AFS is a system allowing a high level of security. The use of Kerberos authentication mechanism with ACL (Acces Control List) guarantees an accurate access to the system and files.

2. AFS and authentication

2.1. Introduction

When you establish a connection to a workstation under AFS, if your username and password are correct, the AFS system provides you a token. This token is an authentication object that will be used between the data server and the client to allow you to access your data. This token has a lifetime at IN2P3 Computing Centre about 3 days. One time this period is beyond, you will have only a restricted access to your data.

2.2. The "tokens" command

The tokens command allows you to verify the date expiration of your token:

> tokens 

Tokens held by the Cache Manager:

User's (AFS ID 872) tokens for afs@in2p3.fr [Expires Mar 4 17:00]
--End of list--

2.3. The "klog" command

If the deadline of your token is reached or if you want to increase it, you can use the klog command to extend it:

> klog 
Password: <enter your password>

To find more informations about the klog command, type:

> klog -help

2.4. The "unlog" command

You have always the possibility to unlog and log again !!! To kill your token, use the unlog command:

> unlog

To find more informations about the unlog command, type:

unlog -help

3. Access to an other cell

AFS authorize the use of a single token at a given time on the same cell. However, if you are registered in other cells, you can have simultaneously one token per cell. Then, you can manage files between two cells without any problems. If you are authenticated in the in2p3.fr cell and you want to access your files under AFS at CERN (cern.ch cell), you can do:

> klog -cell cern.ch
Password: <Enter your AFS password at Cern> 

and the command tokens will give you:

> tokens

Tokens held by the Cache Manager:

User's (AFS ID 872) tokens for afs@in2p3.fr [Expires Mar 4 17:00]
User's (AFS ID 1349) tokens for afs@cern.ch [Expires Mar 2 16:00]
--End of list--

4. The access control list (ACL)

The ACL are the process which allow you, under AFS, to manage the access rights to your directories and files. This process is strongly different from the Unix one's which does not work under AFS. It is build over following concepts:

• The base permissions apply to the directories.
• The sub-directories inherit the permissions of the upper directory.
• The files have no individual permissions: they inherit the protections of the directory they are in.

The management of the ACL is done using the fs command. Be careful, under UNIX, there is also an fs command which have no means with the files protections under AFS. Typically, the protections at the "home" directory level of the authenticated gnats user seem like:

> fs la ~gnats
Access list for /afs/in2p3.fr/home/g/gnats is
Normal Rights:
 usersupport rl
 system:administrators rlidwka
 system:anyuser l
 gnats rlidwka
 backup rl

The "la" argument is a short cut for "listacl". The ACL are based on a whole of couples (group protection or user, access rights). In the previous example, the group system:administrators has the rights rlidwka and the user gnats has the rights rlidwka.

To obtain the argument list of the fs command, type:

fs help

Be careful, use these arguments carefully: you can produce irreversible damages on your data and files without any immediately action of an administrator.

5. Access rights

There are 7 different access rights. The following 4 are applied directly on the directory:

• a (administrator): right to administrate the ACL on the directory.
• l (lookup): right to list the content of the directory.
• d (delete): right to delete files and sub-directories.
• i (insert): right to create new files and directories.

The following 3 are applied on files in the directory context:

• r (read): right to read a file.
• w (write): right to write in a file.
• k (lock): right to lock a file (system call of flock type).

The fs command use simplified syntaxes which are combination of these rights as:

• read: which is equivalent to rl.
• write: which is equivalent to rlidwk.
• all:all rights, namely rlidwka. These are the standard user rights in its "home" directory.
• none: no one.

6. Protection groups

A protection group in AFS is similar to a Unix group. But, in AFS, the user can manage himself its groups, instead of Unix where only the system administrator can do it. There are 3 base groups non modifiable predefined in AFS:

• system:administrators where you will find the AFS administrators of the current cell,
• system:authuser where are all the users defined on the current cell,
• system:anyuser where are all the users, authenticated or not on the current or other cell,

You are free to create the groups you need and to put in all the members you want. Once the group is created, you can insert protections relative to this group in a directory ACL. The pts command allows you to manage the protection groups: to create them, to delete them, to add or remove a member, ... If you are the myself user, you can create a new group like etal by:

> pts creategroup myself:etal
group myself:etal has id -615

As indicated in the command output, AFS gives you, as in a standard Unix environment, an numerical group id (615 here). This group is empty. To add jean and untel users:

> pts adduser -user jean untel -group myself:etal  

To see the features of the myself:etal group:

> pts examine myself:etal 
Name: myself:etal, id: -615, owner: myself, creator: myself, membership: 2,
flags: S-M--, group quota: 0.

This command allows you to verify the group id, the owner, the number of members. You can list all the members using the command:

> pts membership myself:etal 
Members of myself:etal (id: -615) are:
jean 
untel  

To remove a member of the group (untel for example), you should do:

> pts removeuser untel -group myself:etal  

You can find online help about the pts command by:

> pts help  

and for each pts sub-command, you will have two ways:

> pts help adduser 
> pts adduser -help  

that give you help for the adduser pts sub-command like:

pts adduser: add a user to a group 
Usage: pts adduser -user <username>+ -group <groupname>+ [-cell <cellname>]
[-noauth ] [-test ] [-force ] [-help ] 

There are also the traditional Unix man pages for each AFS command and sub-command:

> man command_sub-command

the underscore "_" character separates the command and the sub-command. For example:

> man pts_adduser  

Be careful, the shortcut command will not be valid. For example, man fs_la will not be recognized, you should use:

> man fs_listacl  

7. ACL manipulation

Using the pts and fs commands, you are able to manage all the ACL on directories where you have the "a" administrator right. The online help on the fs command is similar as the pts one's:

> fs help
> fs listacl -help
> fs help listacl

To list the ACL associated to a directory, enter the following command:

> fs listacl ~gnats ~gnats/public
Access list for /afs/in2p3.fr/home/g/gnats is
Normal rights:
 system:administrators rlidwka
 system:anyuser l
 gnats rlidwka
 
Access list for /afs/in2p3.fr/home/g/gnats/public is
Normal rights:
 system:administrators rlidwka
 system:anyuser rl
 gnats rlidwka

The output of this command tell you that the ACL of the gnats user "home" directory allows you only to list the content of the directory ("l" right for system:anyuser). But everybody (system:anyuser) can read the files on the public sub-directory ("rl" rights). The gnats user has all the rights on its directory tree structure ("rlidwka").

The creation of a new directory in its "home" directory has the ACL inheritance mechanism:

> mkdir newrep
> fs la newrep
Access list for newrep is
Normal rights:
 system:administrators rlidwka
 system:anyuser l
 gnats rlidwka

The ACL modification is done with the setacl (or sa) of fs sub-command.

> fs sa newrep toto rli

will give to the toto user the rights to create and to read in the newrep directory. Then:

> fs la newrep
Access list for newrep is
Normal rights:
 system:administrators rlidwka
 system:anyuser l
 toto rli
 gnats rlidwka

To remove the toto user from the ACL of the newrep directory, you should specify the "none" permission:

> fs sa newrep toto none

You will use the same fs setacl command to allow to a protection group, created before with the pts command, to access to a directory. Assuming that the gnats:etal protection group exist, then:

> fs sa newrep gnats:etal rlidwk

will give the following ACL:

Access list for newrep is
Normal rights:
 gnats:etal rlidwk
 system:administrators rlidwka
 system:anyuser l
 toto rli
 gnats rlidwka

In this example, the whole members of the gnats:etal group have the write ACL on the newrep directory. Using the fs setacl command could be boring when you want to replicate the ACL. The fs copyacl allows you to do it:

> mkdir newrep2
> fs copyacl -from newrep -to newrep2
> fs la newrep2
Access list for newrep2 is
Normal rights:
 gnats:etal rlidwk
 system:administrators rlidwka
 system:anyuser l
 toto rli
 gnats rlidwka  

To make an ACL change for a whole directory tree structure, like newrep3 for example:

find newrep3 -type d -exec fs sa {} dupont rlw ';'

This command allows you to give the "rlw" rights to the dupont user on all sub-directories of the newrep3 directory.

8. The quotas

AFS gives to the administrators, a mechanism to manage the disk quotas. In principle, this mechanism is able to avoid the classical file system full on Unix system that freeze all the users connected on the server. By default, each user has 1GB disk space available for its "home" directory on an AFS volume. This AFS volume is shared by many users with a given overbooking quota that allows the administrators to optimize the space usage. The fs list quota sub-command gives you the different percentage of disk space used. The output of the command gives the values in kilobytes.

> fs listquota ~gnats 
Volume Name Quota Used % Used Partition 
user.gnats 100000 5941 12% 24%  

In this example, the user gnats use 12% of its 100 megabytes. But the AFS volume where the home is stored, is used at 24%.

9. The link support under AFS

Like in a Unix file system, the hard links under AFS will concern only files (not directory). But, in AFS, the hard links are only between files in the same directory. Then, it is recomended to use only soft link in an AFS environment.

10. The users and groups

A given user is identified by its name ("userid") associated to a Unix uid and an AFS UID which will have the same numerical value at IN2P3. He will also be part of a group (or throng) indicating the experiment he works for. We can list these objects with the Unix id command, the AFS tokens command and the IN2P3 throng q command.

> id
uid=354(mirabito) gid=101(delphi) ...

> tokens

Tokens held by the Cache Manager:
User's (AFS ID 354) tokens for afs@in2p3.fr [Expires Sep12 16:07]
-- End of list --

> throng q
delphi

The userid (mirabito in this example), the Unix id (354) and the AFS UID (also 354) are equivalent concerning the identifiaction of the user. In fact, it is the UID which is kept in the AFS protection groups.

The group and the throng have also the same value (delphi). This is always the case. (The nostalgic of VM system will recognize the throng term inherit from SLAC batch system.)