Sharing Files on RCS UNIX Systems (AFS)

Introduction

The Rensselaer Computing System (RCS) uses AFS (formerly called the Andrew File System), and acts like most other UNIX file systems in that, unless you have specifically placed files in your /public or /public_html directory (both of which are automatically created for you within your computer account), other users cannot read or use your files. However, the system also makes it easier for you to share files with others, both on-campus and at other AFS sites. Basically, RCS gives you the authority to share your files with others -- or keep them secure from others -- by allowing you to group your files into directories and then granting specific kinds of access to those directories. For example, you can set up a directory so that others can only read the files in it, like your public directory, or you can set up a directory so that others can both read and edit the files in it.

If you are unfamiliar with using basic UNIX commands, such as cd and ls, you may find it helpful to refer to Memo RPI.113, Using the UNIX Platform on the Rensselaer Computing System (RCS).

File Security

Unlike standard NFS UNIX file permissions, AFS uses Access Control Lists, or ACLs, to control permissions on a directory and the files contained in it; ACLs allow you to specify users who have permission to use a particular directory, as well those users' specific permissions to that directory.

(Refer to the Using chmod section of this document for an explanation of further differences between the NFS and AFS file systems.) Since ACLs are defined for directories rather than files, the permissions specified by a directory's ACL affect all the files in that directory, rather than affecting the individual files. For example, you can define an ACL that lets two users read and modify files in a directory, while a third user can only read them.

Current Setup

When you first log on with your Rensselaer userID and use the ls command to check to see what's in your home directory, you will discover that it includes the public and private subdirectories. The public directory gives all users lookup and read access; this means that other users can view the contents of your files in this directory, or copy files to their own directories for their own use. By contrast, other users have no access at all to the files contained within your private directory. Therefore, the easiest way for you to give others read access to your files is to copy the files into your public directory, and the easiest way to keep files hidden is to move them into your private directory.

You also have a yesterday directory within your computer account, and this contains copies of all your files as of the most recent system backup. However, since this directory does not use up any of the space in your disk quota allotment, do not try to change the permissions within this directory, or to delete files.

Please note that any new directories which you create with the mkdir command will have the same permission as their parent directories unless you change them, as outlined below.

Understanding File Permissions

Because the Rensselaer Computing System uses AFS, this means that RCS' file permission scheme is a little different from those on UNIX systems that do not use AFS. Specifically, rather than setting access controls on individual files, AFS requires you to set your controls on the directory level, and as a result, files which require the same set of access controls should be placed in the same directory. Every directory has an access control list, or ACL, and you can use these these ACLs to grant access rights to other users.

AFS allows for seven specific access rights to be set up, and you can use these ACLs to grant access to individuals or groups. There are two distinct groups of rights: directory and file rights.

Directory Rights (lookup, insert, delete, administer)

These rights apply to the directory itself. For example, if only the insert right has been granted for your userID, you cannot insert text directly into a specific file, but you can create (or insert) files in that particular directory.

lookup (l) -- Allows you to issue the ls command, examine the ACL for the directory, and access the directory's subdirectories (which are protected by their own ACLs). Users must have the lookup right before they can access files or directories.
insert (i) -- Allows users to add new files to the directory (by creating or copying) and gives them permission to create subdirectories, but they cannot change any existing files. The user who creates any new files will own them, and only they can change their chmod permissions.
delete (d) -- Allows you to delete files from the directory.
administer (a) -- Allows you to set the ACL for that directory. Users always have this right on any directory that they own, even if his or her right has been removed from the directory's ACL.

File Rights (read, write, lock)

These rights apply to individual files within a directory.

read (r) -- Allows you to read the contents of a file
write (w) -- Allows you to change the contents of a file
lock (k) -- Allows you to run programs that must ``lock" files in that directory. (For example, certain database programs may need to lock files to prevent more than one person from writing to the same file at the same time.)

Note that, even though other users can list the names of the files in your home directory, you are the only one who can actually read them and any files in subdirectories under it, except for those you specifically make ``public." Your public directory gives all users the ability to list names of files (lookup) and read and copy them; the private directory gives others no file permissions at all, and other users can't even list file names.

Shortcuts

Note that you may combine these file and directory access rights (rlidwka) in different ways, in a sort of ``shorthand" form. The shorthand for the four most common combinations appears below. (For example, instead of typing out rlidwk when you grant a user permisssion to a directory, you can just use the word write.)

Shortcut	Rights	Description/Action
write	rlidwk	Provides all rights except administer
read	rl	Provides read and lookup rights
all	rlidwka	Provides all rights, including administer
none	no rights	Removes user from the ACL entry

Accessing Files Permitted to You

If someone has permitted a file to you, you can read or print it simply by specifying the file's entire path in the command. For example, to read the file lab12 in lucez's public directory, you could enter the following command:
$\begin{alltt}\bf more \~{}lucez/public/lab12 \end{alltt}$

Checking File Permissions

To check the permissions of the current directory, use the fs listacl command. As shown below, you may also use the abbreviation la instead of listacl; think of it as standing for ``list access."
$\begin{alltt}\tt {\bf fs la} Access list for /home/60/ramabz is Normal rights: system:anyuser l ramabz rlidwka \end{alltt}$
This access control list tells you that the user ramabz has ALL permissions for her directory (rlidwka), while others can just list the files in her directory (anyuser l). In this example, the userid ramabz is the only name on the ACL for this directory. If other users had specific permissions, they would appear in this listing as well. Any subdirectories you create will inherit the default permissions of the parent directory. However, subsequently changing the default permissions of the parent will not automatically change the permissions of the subdirectories.

Changing File Permissions: Working With ACLs

Adding a User to an ACL

To add a user to an ACL, first use the UNIX cd command to move to the parent directory of the directory to which you wish to change the file permissions, and then issue a command having the format:
$\begin{alltt} {\bf fs setacl}{\it directory userid access-rights} \end{alltt}$
where

directory: refers to the name of the directory in which you want to add someone to the ACL
userid: refers to the Rensselaer userID of the person you want to add to the ACL
access-rights: may consist of any combination of the seven access privileges (rlidwka)

If you wish, you can also use the abbreviation sa in place of setacl; think of it as standing for ``set access."

Rights issued with the setacl command will replace any pre-existing rights for a person or group.

Examples

To give user ramabz read access to your math directory, you would use the command:
$\begin{alltt}\bf fs sa math ramabz rl \end{alltt}$
To give user healyj write access (rldiwk) to the same directory:
$\begin{alltt}\bf fs sa math healyj write \end{alltt}$
To give user tartom list access to the same directory:
$\begin{alltt}\bf fs sa math tartom l \end{alltt}$
To perform the three previous commands all at once:
$\begin{alltt}\bf fs sa math ramabz read healyj write tartom l \end{alltt}$
Let's suppose that your own userid is doej2. Now, if you were to look at the ACL for your math directory after setting the permissions above, it would appear as follows:
$\begin{alltt} {\bf fs la math} {\tt Access list for math is Normal rights: doej2 rlidwka tartom l healyj rlidwk ramabz rl } \end{alltt}$

Adding All Users to an ACL

If you wish, you may permit a directory to any user with AFS access by using a group called system:anyuser in the fs sa command, instead of a specific userid. This group contains anyone using AFS. A group called system:authuser also exists; this group contains only the people who have used valid userIDs and passwords to log into RCS. (Please refer to the section Working With Groups for more information about groups.)

For example, to give everyone read access (rl) to the directory named math, make sure you are in math's parent directory, and then type:

$\begin{alltt} {\bf fs sa math system:anyuser read} \end{alltt}$

If you look at the ACL for your public directory, you will notice that system:anyuser has rl permission, meaning that anyone logged into AFS can read the files in that directory.

Removing an ACL Entry

To remove a user from an ACL, use the following command format:
$\begin{alltt} {\bf fs sa}{\it directory userid}{\bf none} \end{alltt}$
For example, to remove all of user healyj's permissions within the math directory:
$\begin{alltt}\bf fs sa math healyj none \end{alltt}$
If you then checked the ACL list, it would appear as follows:
$\begin{alltt} {\bf fs la math} {\tt Access list for math is Normal rights: doej2 rlidwka tartom l ramabz rl } \end{alltt}$

Denying a User Access

If a user would by default receive certain permissions based on his or her group membership (for example, system:authuser), and you don't want to allow that person to have such permission, you can use the -negative option before the userid. This indicates that the user is specifically not to have the permissions listed, no matter what else is set, and places them on the negative ACL list. As an example, suppose we had the following:

$\begin{alltt} {\bf fs la /home/60/firstz/public} {\tt Access list for /home/60... ...rmal rights: system:backup l system:authuser rl firstz rlidwka } \end{alltt}$

However, let's suppose that you don't want user whitez to have permission to list or read any of the files in the directory (which he or she would have received by default as a member of the group system:authuser). In this case, you could type:

$\begin{alltt}\bf fs sa /home/60/firstz/public -negative whitez rl \end{alltt}$

Your directory would then have an access list of:

$\begin{alltt} {\bf fs la /home/60/firstz/public} {\tt Access list for /home/60... ... system:authuser rl firstz rlidwka Negative rights: whitez rl } \end{alltt}$

Note: Negative ACLs are complex, in that setting one for a user does not necessarily prevent them from ever accessing that directory. For example, a directory that also has permissions set for the group system:anyuser can still allow the user some access to the directory; that person can use the unlog program and still have access as a member of system:anyuser. As a result, you should probably restrict use of negative ACLs to those directories that have permissions for system:authuser or another group that has limited membership that you control. (See the section Working With Groups for more information about groups.)

Using the chmod Command

chmod

(change mode), the traditional file permission command, has limited capabilities in AFS. You can use chmod to reduce access to a particular file in a directory; that is, you can give the file more limited access than the directory itself. You can also use it to make a file executable, which is appropriate for a file containing UNIX commands. For example, you can use chmod to remove write access to a file in a directory that permits write access to all its files. However, you cannot use the chmod command to give write access to a file in a directory that does not permit write access to any of its files. Using the ls -l command will display all the files in a directory, with their related chmod permissions appearing on the left, as shown below.
$\begin{alltt} {\bf ls -l} {\tt total 2048 -rw-rw-rw- 1 doylez user 1451 Dec 1... ...6 15:31 Initial.dt drwxrwxrwx 5 doylez user 2048 Jan 20 09:11 News} \end{alltt}$

The command chmod has nine permission settings, with the chmod permission bits appearing to the left, and filenames to the right. AFS uses only the first three - read (r), write(w), and execute(x) bits and ignores the other bits. The first entry can be a dash (-), indicating a regular file, d, indicating a directory, or l, indicating a link. If the second entry appears as an r, anyone who has ACL read and lookup access to the directory can read that particular file. If the r bit does not appear, no one, including the owner, can read that file. If the third entry appears as a w, anyone who has ACL read, lookup, and write access to the directory can change that file. If the fourth entry appears as an x, anyone who has ACL read and lookup access to the directory can execute that program file. To set chmod permissions, use the command format
$\begin{alltt} {\bf chmod} {\it w}{\bf +}{\it p filename} \end{alltt}$
where

w: indicates that you want to permit the file to a particular user. Currently, the only valid AFS option is u, or ``user."
p: represents the chmod permission mode bits: r,w,x
+: means add permissions. You can also have a - here, which means to remove the indicated permissions.
filename: refers to the file for which you want to set permissions or access

Example: To add execute permission to the file article:
$\begin{alltt} {\bf chmod u+x article} \end{alltt}$
More detailed information is available via the chmod man page; to access it, type the following command from a UNIX window:

: man chmod

Working With Groups

See also: AFS Groups from the AFS User Guide

AFS also allows you to create groups, or defined lists of users on which you can place an ACL, for easy filesharing among several people. For example, if you're working on a project with a group of Rensselaer colleagues, you can place all of their Rensselaer userIDs in a group, and then grant or deny them the same directory access rights all at the same time. This saves you the trouble of having to change each group member's ACL entry individually. If you wish, you can use a group for your own convenience, without telling people that they are in a group. In this way, you can control the group's access to files in a directory, and the other users only know that they can or cannot access certain files. However, users can always list group members. On the other hand, you can also create a group and then inform its members that you have included them in that group. In turn, the group members can add the group's name to their own ACLs to allow all the group members file access. However, if you are in a group that someone else has created, and you have added the group to an ACL, you should know that the group's owner can add other people to the group without informing you. These new group members will automatically have the same access to your files that the other group members do. When you create a group, you are the owner, and this means that only you can administer the group; that is, you are the only one who can add or remove members, rename or delete the group, etc. However, anyone can see that a group exists, since it will appear in the ACL whenever they issue an fs la command. (By default, anyone can list the members of a group.) More information about groups and protecting group information follows. To use a group, you must:

1.: create a group
2.: assign members to the group
3.: set an ACL entry for the group

Creating a Group

In order to work with a group, the first thing you need to do is create one. Most of the group-related commands use the pts command, which tells AFS to use the protection server to check directory access permitted to group members. As an example, suppose you want to create a group with your project team members in it. The basic command format to use is:
$\begin{alltt} {\bf pts creategroup}{\it yourid:groupname} \end{alltt}$
where

yourid refers to your own Rensselaer userID
groupname refers to the name you wish to give the group

As a general rule, group names have two parts, separated by a colon, with the first part containing the owner's name, and the second part containing the group's name. All letters must be lowercase; you can include numbers and punctuation, except for the colon. The total name (userID and group name) may contain as many as 63 characters. As an example, suppose your own userid is doej2. To create a group called doej2:team, you would enter the pts command shown below:
$\begin{alltt} {\bf pts creategroup doej2:team} {\tt group doej2:team has id -300} \end{alltt}$
Each group is assigned an id-number.

Adding Users to a Group

It's important to note that a newly-created group is empty, so, once you have created a group, your next step is to add users to it. To add users to a group, use the following command format:
$\begin{alltt} {\bf pts adduser -user}{\it userid1 userid2 userid3}{\bf -group}{\it yourid:groupname} \end{alltt}$
where

useridi1, userid2, and userid3 refer to the Rensselaer userIDs of the users you want to add to the group
yourid refers to your own Rensselaer userID
groupname refers to the name of the group to which you want to add members

As an example, to add three members to the group team, you would enter the following command:
$\begin{alltt} {\bf pts adduser -user ramabz healyj tartom -group doej2:team} \end{alltt}$

Setting an ACL Entry for a Group

Setting the ACL entry for a group gives the members specified access to the files in that directory. The command for setting a group ACL entry, which is very similar to that for an individual user, uses the following format:
$\begin{alltt} {\bf fs sa}{\it directory yourid:groupname rights} \end{alltt}$
where

directory refers to the directory to which you want to give the group access
yourid refers to your own Rensselaer userID
groupname refers to the name of the group
rights may consist of any combination (or shortcut) of rlidwka access rights

For example, to give the group team write access to the math directory, first make sure you're in math's parent directory, and then issue the following command:
$\begin{alltt} {\bf fs sa math doej2:team write} \end{alltt}$
You can then use the following fs la command to check the results:
$\begin{alltt} {\bf fs la math} {\tt Access list for math is Normal rights: doej2:team rlidwk system:anyuser rl doej2 rlidwka} \end{alltt}$

Listing Group Members

To list group members, use the following command format:
$\begin{alltt} {\bf pts membership}{\it yourid:groupname} \end{alltt}$
If you wish, you may use the abbreviation mem instead of membership. For example, to see the members of doej2:team, enter the following command:
$\begin{alltt} {\bf pts mem doej2:team} {\tt Members of doej2:team (id: -300) are: ramabz healyj tartom} \end{alltt}$

Listing the Groups to Which You Belong

To see a list of the groups to which you belong, use the following command format:
$\begin{alltt} {\bf pts mem}{\it yourid} \end{alltt}$

Example:
$\begin{alltt} {\bf pts mem ramabz} {\tt Groups ramabz (id: 00060) is a member of: doej2:team doej2:dept its:consultants healyj:neatstuff} \end{alltt}$

In addition to the groups listed, you are always a member of system:anyuser and, if you are logged on, a member of system:authuser.

Removing a User From a Group

To remove a user from a group, use the following command format:

$\begin{alltt} {\bf pts removeuser -user}{\it userid}{\it yourid:groupname} \end{alltt}$

If you want to remove a person from more than one group, add the -group option just after the userID of the person you want to remove, and add other group names to the end of the command. Examples: To remove the member ramabz from the group team:

$\begin{alltt} {\bf pts removeuser -user ramabz doej2:team} \end{alltt}$

To remove the member ramabz from the groups team and dept:

: pts removeuser -user ramabz -group doej2:team doej2:dept

Removing a Group

Removing a group requires two separate actions: you must first delete the group, and then remove its ACL reference. To delete a group, use the following command format:
$\begin{alltt} {\bf pts delete}{\it yourid:groupname} \end{alltt}$
To then remove the group's ACL reference:
$\begin{alltt} {\bf fs cleanacl}{\it directory} \end{alltt}$
where directory refers to the directory containing the ACL from which you want to remove the group. The system will automatically show you an updated ACL for the directory. For example, to delete the group doej2:team, you would enter the command:
$\begin{alltt} {\bf pts delete doej2:team} \end{alltt}$
To then remove the group from the math directory's ACL:
$\begin{alltt} {\bf fs cleanacl math} \end{alltt}$
The system will then show you an updated ACL like this:
$\begin{alltt} {\tt Access list for math is now Normal rights: doej2 rlidwka} \end{alltt}$

Getting Help

To see a list of fs commands, enter the following command from a UNIX window:
$\begin{alltt} {\bf fs help} \end{alltt}$
To see a list of pts commands, enter the following command from a UNIX window:
$\begin{alltt} {\bf pts help} \end{alltt}$

Last modified: January 23, 2009

Sharing Files on RCS UNIX Systems (AFS)

Contents

Introduction

Understanding File Permissions

Accessing Files Permitted to You

Checking File Permissions