Skip to main content

Table of Contents


AFS Introduction

Introduction to the AFS file system in the Computer Science Department.

Reviewed by John Sopko 6/17/2014

The Computer Science Department uses the AFS file system for UNIX home directories, research space, and most of our web space.  Our default Linux and Windows installations include AFS client software.  Below is some general information on using AFS in this department.  You can also go to our help pages and search for AFS; there are several more specific pages.

There are several important reasons why we use AFS as a file system instead of the native file systems on Linux and Windows.  The Linux file system security model allows anyone that has a a root account or sudo access to change their login id to that of another user and gain access to that user’s files.  AFS does not allow root users to gain access to other files.  Microsoft Windows’ native NTFS file systems has a much better security model then Linux.  The advantage of running the Open AFS client on Windows is to allow you to access the same AFS file space from both Linux and Windows.  Currently there is not a good alternative for AFS.

AFS is a distributed file system.  It uses the client/server model, where all the files are stored on file server machines.  Files are transferred to client machines as necessary and cached on local disk.  The server part of AFS is called the AFS File Server, and the client part of AFS is called the AFS Cache Manager.  AFS provides Access Control Lists (ACLs) which provide for more control and flexibility than standard Linux file permissions.

AFS provides transparent access to local and remote files by using a consistent name space.  All files in AFS are found under the Linux directory /afs.  Under the /afs directory are the various sites which run AFS and make their file-system available to the Internet community.  These sites are called AFS Cells.  The Computer Science cell name is the same as our Internet name, cs-old.sites.unc.edu.  Thus all files and directories under /afs/cs-old.sites.unc.edu are in the Computer Science AFS file space.  The UNC campus AFS cell name is located at /afs/isis.unc.edu.

Any file located under /afs is located on an AFS file server.  If a remote cell that you wish to access is not listed, please email help@cs-old.sites.unc.edu and tell us the cell you wish to access, and we will configure the cell into AFS.

The campus help site has some information on accessing AFS on the campus isis.unc.edu cell and other general AFS information.

Changing your AFS password

Use the  https://www.cs-old.sites.unc.edu/webpass URL to change your Computer Science AFS password.  This will change your AFS, Linux, and Windows passwords at the same time.  This password is NOT the same as your Onyen password, though of course you can use the same password in both places.

Using AFS

The OpenAFS User Guide is the best resource on how to use AFS.  If you need assistance or have questions please emailhelp@cs-old.sites.unc.edu.  In general, if you are using a Computer Science provided Windows or Linux machine, you will have the AFS client installed for you.  When you login you will automatically be authenticated to AFS as described in chapter 2 of the OpenAFS User Guide.  See also the Computer Science AFS Aklog information for specifics on authenticating to our cs-old.sites.unc.edu AFS cell.

Accessing AFS on a Linux system

For Linux users, files in AFS are accessed much the same as files in the native linux file system.  The big difference is that AFS directory permissions take precedence over Linux file permissions.  The same is true of using AFS on Windows machines.

Accessing AFS on a Windows system

The recommended way to access AFS from a Windows machine is to use the Windows UNC (Uniform Naming Convention) path.  For example, to access your home directory you can make a Windows shortcut to the following location or enter the UNC path in the Windows Run… command box:

\\afs\cs-old.sites.unc.edu\home\login

Where “login” is your Computer Science login name.  AFS file permissions take precedence over Windows file permissions.  You can create a shortcut with the UNC path name pointing to the AFS folder you wish to access.  You could also use the Windows Explorer to enter in the \\afs\cs-old.sites.unc.edu\some_path_name to access AFS file space from your Windows machine.

You can access the Windows Users guide on your Windows 7 machine under this menu:

Start->All Programs->OpenAFS->Documentation->User Guide.

Your AFS home directory space

Most users with a Computer Science account receive a home directory located at:

/afs/cs-old.sites.unc.edu/home/login

Where “login” is your Computer Science login name.  Quotas are described here.

Important file restoration tip

We take a nightly online snapshot of AFS space starting at 2am.  If you accidentally delete a file that existed during the last snapshot, you can restore your file without going through Computer Services.  To see the nightly snapshot of your home directory, go to the following location:

/afs/cs-old.sites.unc.edu/home/last_backup/login

This is a read only copy of your home directory as it was when the last backup snapshot was taken.

Further information

The department is running OpenAFS, whose main page is:  http://www.openafs.org/.  Documentation on OperAFS is athttp://docs.openafs.org/index.html.  In particular, see the AFS Users’s Guide, which is an excellent manual for beginners.

Note that AFS is strictly open source and we have no support for the product other then the www.openafs.org web site.


AFS Volumes

Information on AFS volumes and mount point.

Reviewed by John Sopko 6/17/2014

This is one of several AFS help pages.  To get started with AFS see the AFS Introduction. Click on the AFS tag above to list all AFS related help pages.

Linux divides disks into physical disk partitions.  AFS further divides partitions into objects called volumes.  Linux partitions are containers for AFS volume objects.  A volume houses a subtree of related files and directories.  Normally, volumes are smaller than traditional file systems.  For example, each user’s home directory would normally be stored in a separate volume.  Each major sub-directory of /afs/cs-old.sites.unc.edu/project and /afs/cs-old.sites.unc.edu/pkg would also be stored in a separate volume. Large sub-directories are further sub-divided.

AFS keeps a database of which file servers have which volumes. AFS automatically determines which file server to get files from.  You do not need to know which file server houses any volume.  Indeed, it may move during its lifetime. If you wish to know on which file server a file is currently stored, you can use the command “fs whereis”:

% fs whereis /afs/unc/home/user1 
 File /afs/unc/home/user1 is on host grouse

Volumes can have a size limit, or quota. Y ou may receive error messages if the volume you are writing into exceeds its quota.  Home directory volumes here at UNC Computer Science Department have different quota levels, depending on the account category.  Other volumes may have quotas as set by research groups.  To see the quota and partition info for a particular directory, you can use the AFS command “fs listquota”, assuming you have sufficient permissions on the directory:

% fs listquota /afs/unc/home/user1 
 Volume Name        Quota    Used    % Used   Partition 
 D0.home.user1     150000    17        0%        41%

Access to volumes is provided through mount points. Mount points appear in the file system as directories.  When you cd into a directory, you may be crossing a mount point and accessing a new volume, which may be stored on a different AFS file server machine.  To see all of the details about mount points, quota, etc. for a given directory, you can use the “fs examine” command.

% fs examine /afs/unc/home/user1 
 Volume status for vid = 536870983 named D0.home.user1 
 Current disk quota is 150000 
 Current blocks used are 17 
 The partition has 78222 blocks available out of 133602

In general you shouldn’t need to worry about volume information, but realizing that underneath the directory structure is a volume structure can be helpful when restoring and moving files. See AFS File Restoration.

Backups of your home directory are made Monday – Friday starting at 2 a.m. A copy of your files is made at that time, and it is accessible to you until the next backup runs. This means that if you delete or modify a file that existed at the time of the last backup, you can probably restore this instantly, without sending mail to help.

Backup volumes are accessible at /afs/cs-old.sites.unc.edu/home/Last_Backup/login.

To restore your file, cd into the appropriate Last_Backup directory.  You will find your entire directory structure available.  Simply copy the file from its location under Last_Backup/login to your regular home directory.Backup volumes exist for other AFS volumes that receive daily backups

If you are working in project space, for example, you may be able to
get an instant restoration there as well:

1. Make sure you are authenticated to AFS (i.e. use the token command)
2. Cd into the directory from which you lost the file. Execute:

% fs exam

This will print information about the volume such as the name. Here is sample output:

Volume status for vid = 536873139 named D0.prj.test1
Current disk quota is unlimited
Current blocks used are 119
The partition has 16420 blocks available out of 133602

In this output, the name of the volume is D0.prj.test1.

3. Mount the backup copy of this volume:

% fs mkmount afs_location volume_name.backup

For example:

% fs mkmount /afs/unc/home/user1/tempmount D0.prj.test1.backup

If you get an error from your command you probably do not have permissions to the volume.  Email help@cs.unc.edu for assistance.

4. If the command succeeds, cd into the name given as the mount  point, and copy the file back into project space. T hen cd out of the backup volume and type

% fs rmmount afs_location

to remove the mount point.

You only have until the next AFS backup runs to do this restoration.  After that, the backup will not have the old file.  If you encounter any problems, send mail to help@cs-old.sites.unc.edu asking for the restoration.

Running out of disk space in AFS

See the disk usage help page on how to determine how much space you are using and controlling your disk usage.

If you run out of space in your AFS home directory or a project directory and you don’t get a message about exceeding your quota, then the problem is that the physical partition has filled up. Computer Services monitors disk usage, so this rarely occurs. Your home directory volume is in a physical partition with other volumes. Please email help@cs-old.sites.unc.edu about this issue.

You can delete any file you have created that day. That space will be reclaimed and be immediately available. Deleting older files will reclaim space after the next backup runs. For an explanation of why this is, please see How AFS backup volumes work below. Don’t let this dissuade you from deleting old files; you’ll appreciate it tomorrow.

If you need assistance email help@cs-old.sites.unc.edu.

How AFS backup volumes work

Volumes whose names end in .backup are the copies that the backup software creates. The AFS backup process locks the volume while the backup is run, so to minimize the loss of access, these backup volumes are created early in the morning and the backup software backs them up instead of the original volume.

Backup volumes are identical to the original volume when they are created.  Over the course of the day, they get further away from the original, as the owner modifies files.  When created, they actually occupy very little space, just the amount needed to point to the same data blocks that the original does.  When a user modifies a file in UNIX, the operating system uses a technique called “copy on write”.  The modified blocks are written to a different location.  If the file is outside of AFS, the old block is then freed for reuse.  But when an AFS backup volume exists, that block can’t be freed because there is still a valid reference to it.  So as files change, the backup volume gradually occupies more space in the partition.  The next night, the two are synchronized and those blocks are reclaimed.  When you look at a “/usr/afsws/etc/vos listvol” listing, it looks like the backup copies are occupying as much space as the original, but the actual amount will depend on how different the backup and original volumes are.

From this discussion, you can see that the way you use your disk space will affect how much space you have through the day. If, as a matter of course, you throw away a 200 MB directory and copy it over from elsewhere every day, you are effectively occupying 400 MB within that space, 200 for the old one (pointed to by the backup volume), and 200 MB for the new copy. This type of usage can cause significant inconvenience to the others who share your AFS partition.

Finding which file server holds your files

With AFS, it is not obvious which file server actually holds your volume.  The quick way to find what AFS server holds your files is to cd to
the directory in question and execute the “fs whereis” command:

% fs whereis
File . is on host waxwing.cs-old.sites.unc.edu

To find out what the volume name and partition a volume resides on:

First get the volume name, cd to the directory in question and execut the “fs exam” command:

% pwd
/afs/cs-old.sites.unc.edu/project/mip
% fs exam .
Volume status for vid = 536878268 named T0.prj.mip
Current disk quota is 2000000
Current blocks used are 25
The partition has 298726 blocks available out of 7615957

Then use the “vos” command to get server and partition info:

% vos exam T0.prj.mip
T0.prj.mip                        536878268 RW         25 K  On-line
 falcon.cs-old.sites.unc.edu /vicepd 
 RWrite  536878268 ROnly          0 Backup  536878270 
 MaxQuota    2000000 K 
 Creation    Wed Sep  8 07:06:02 1993
 Last Update Fri Jun 14 12:01:36 2002
 556 accesses in the past day (i.e., vnode references)
RWrite: 536878268     Backup: 536878270 
 number of sites -> 1
 server falcon.cs-old.sites.unc.edu partition /vicepd RW Site
The volume T0.prj.mip resides on the server waxwing partition /vicepd.

AFS Playpen Space

How to use and request AFS playpen space

Reviewed by John Sopko 6/17/2014

Please read the following notes on how to use the public UNC Comp Sci AFS playpen space before you start inserting data there.  If you are not familiar with the AFS filesystem please see the AFS introduction.

In general, anything on UNIX systems located in a playen directory is NOT backed up to tape.  There is a 24 hour online snapshot of all files in AFS playpen space; if you delete files and they were there during the last online backup you can restore the files as described below.  The afs snapshot takes place at 2am and usually finishes by 2:20am.

To use the AFS playpen space, you first need to email help@cs-old.sites.unc.edu and request that a directory be set up for you under /afs/cs-old.sites.unc.edu/playpen.  An AFS volume will be created for you and a directory mount point will be placed in /afs/unc/playpen/loginwhere “login” is your login name.   For example, /afs/cs-old.sites.unc.edu/playpen/aardvark would be the playpen space for user aardvark.

You will be given full AFS permissions on your directory, which will have an initail 8 GB quota.  If you need more you can request an additional 8GB added to your quota.  Computer services will periodically contact users to clean up space if the space gets filled up, but please keep track of your own space and clear out data you don’t need.  There are currently 260 GB available in playpen space, and a lot of folks use this space.  Also, note that /afs/unc is a link to /afs/cs-old.sites.unc.edu, so you can access the above playpen directory as /afs/unc/playpen/aardvark.

You can make a Linux softlink in your AFS home directory to your AFS playpen space if you wish. For example to make a linkecalled “playpen” in your home directory to link to your AFS playpen space:

cd (change to your home directory)

ln -s /afs/cs-old.sites.unc.edu/playpen/login playpen

So accessing /afs/cs-old.sites.unc.edu/home/login/playpen will land in your AFS playpen space. If you want to make space that is accessible under your home web page:

cd
cd public_html
ln -s /afs/cs-old.sites.unc.edu/playpen/login/files files

This will make a link from your public_login/files to your AFS playpen login/files directory. You can access this space via the web server https://cs-old.sites.unc.edu/wp-login.php

How to get back a file you deleted

A snapshot of the directories/volumes located in /afs/cs-old.sites.unc.edu/playpen is taken nightly starting at 2:00 am.  If your files were present at that time, they will be available as read only files until the next 2am snapshot is taken.   That is, a copy of your read/write files is placed in the read only backup volume at the time of each snapshot.  The read only copy of these files is located at: /afs/unc/playpen/last_backup/login.  Simply go to the directory where your files are located and copy them to the read/write directory.   Remember, a snapshot is taken every night and your files will be lost if you do not get them back before the next snapshot.  For instance, say you create a file Monday morning and work on it all day.  Tuesday at 2:00am a backup volume is created that contains all the data at the time of the backup.   You then accidently delete the file Tuesday at 3:00pm.   Simply go to the last_backup/* location to get a copy of your file.


AFS File Security

Information on AFS directory and file security.

Reviewed by John Sopko 6/17/2014

This page gives information on AFS tokens, access control lists (ACLs), protection groups, and home directory permissions.  AFS does not use Unix/Linux user IDs, since any Linux machine can give a user a particular User ID.  Instead, AFS provides its own user ID’s which are managed  at the AFS cell level.  To get an AFS ID which identifies you to an AFS cell you must log in and have an account on that AFS cell. The Computer Science AFS cell name is cs-old.sites.unc.edu.

Tokens

AFS’s authentication is based on Kerberos, a computer network authentication protocol, which allows nodes communicating over a non-secure network to prove their identity to one another in a secure manner.  When you log on successfully to an AFS cell, your local machine’s AFS cache manager will hold a “token” for you.  Once you have an AFS token, you can access AFS directories that have their permissions set to allow your AFS User ID access.  Tokens contain a time stamp and are valid for a pre-set amount of time.  The default lifetime of a token at UNC is one week.  The AFS Cache Manager will notify you via the console when tokens on your machine expire.  You can use the AFS command aklog to extend the life of a token or to get a new token if your original token expires.

Tokens are the mechanism of authentication.  Tokens provide security because in order for an application to ask for the token, it must know  an encryption key, and in order to understand that a token has been granted, it must also have an encryption key.  This makes it very difficult for someone outside the application to intercept the password, or to even ask for a token.  All AFS commands and file requests check with the cache manager to see whether or not you’ve been authenticated to AFS.  If the cache manager holds a token for you, you are considered authenticated to AFS.

You get a token by logging in.  We have set up the login process to authenticate your password within AFS.  To see that this has happened, you can type the tokens command:

% tokens

Tokens held by the Cache Manager:

User’s (AFS ID 3903) tokens for afs@cs-old.sites.unc.edu [Expires Mar 29 09:03]

This output says that the cache manager holds for you a token for the cell cs-old.sites.unc.edu as AFS ID 3903.  You may hold additional tokens for different cells, but you may not have more than one token for a particular cell.  Tokens are specific to a machine, so authenticating on one machine does not give you a token for another workstation.

Tokens expire after some period of time and need to be renewed.  The default lifetime at UNC Computer Science is one week.  Also, tokens do not automatically go away when you log out, so that when you run programs overnight the background programs can use the tokens to access files.  You can remove a token by using the unlog command:

% unlog
% tokens

Tokens held by the Cache Manager:

–End of list–

Please see AFS Aklog for information on how to renew your AFS tokens from the command line.  The AFS “klog” command is based on kerberos version 4 which is no longer supported.

Access control lists and UNIX/Linux file protections

An access control list (ACL) is a list of permissions attached to an object.  An ACL specifies which users or system processes are granted access to objects, as well as what operations are allowed on given objects.  In AFS, an access control list is provided for each AFS directory.  File protections do not work the same way in AFS as they do in UNIX.  The most important point to bear in mind is that only directories have ACLs in AFS, whereas UNIX has controls on both files and directories.  Access to files in AFS is controlled by the ACL of the containing directory. As a result, when you move files between directories, you may have changed the permissions.  AFS ACLs provide a much broader range of security features than the file permission mechanism in UNIX.

When you create a new subdirectory, it automatically inherits the ACL that the parent had at the time it was created.  Changing the parent ACL in the future will not change the child’s ACL.

The Unix/Linux mode bits set on a directory have no effect in AFS and may be safely ignored.  However, the first three bits (the user bits) of a file’s mode bits do have a meaning in AFS.  The file bits may be used to further restrict access to a file that the ACL allows access to.  For example, if the AFS ACL allows write access to a directory, but the Linux file bits look like -r–??????, where “?” means anything,  then the user will not be allowed to  write to the file.

Remember, however, that the user bits are applied to anyone who has access to the file; the owner of the file is irrelevant.  Also, anyone who has write access to the file through the ACL will be allowed to change the protection bits on the file using chmod.

AFS acls can be complicated.  If you are not sure your AFS acls are set correctly PLEASE email help@cs-old.sites.unc.edu and we will be glad to assist you. This is especially true of directories where you plan to house sensitive information.  For example, if you have files in your www.cs-old.sites.unc.edu web space that you plan to protect with a user login and password, the ACLs must be configured properly!  If your AFS ACLs are not configured properly, search engines like Google can find your pages, catalog them, and keep cached copies of them.  See the Web Server FAQ for information on how to protect your web pages.

How to decode an ACL

You may use the command “fs la” or “fs listacl” to examine the access control list that applies to a directory.  For example:

% fs la /afs/unc/home/user1
Access list for /afs/unc/home/user1 is
Normal rights:
system:anyuser l
user1 rlidwka

Every ACL implicitly contains “system:administrators a”; this entry allows the AFS system administrator to administer the directory, similar to root privileges in UNIX.  The system:anyuser is any user with access to the AFS system, whether or not he has been authenticated to your AFS cell.  The above ACL says that anyone can list the contents of this directory.  The user user1 may read, lookup, insert files into the directory, delete files from the directory, write to a file in the directory, can flock files in the directory, and may change the ACLs for the directory.

Unlike UNIX, which has only three basic rights that may be controlled, AFS has seven different rights which may be individually controlled:

l (lookup) – list files in the directory (but subdirectories are controlled by their own ACLs)

i (insert) – create files in the directory

d (delete) – remove files and subdirectories from the directory

a (administer) – change the ACL for the directory

r (read) – read files in the directory

w (write) – modify files in the directory and modify their UNIX mode bits with the chmod command

k (lock) – run programs that need to “flock” files in the directory

Changing the ACL of a directory

The ACL of a directory may be changed using the “fs setacl” command (which can be abbreviated as “fs sa”).  By default, “fs sa” adds to or alters the existing ACL, rather than replacing it entirely.  So, for example, if you wish to give user joe the right to insert and delete files in a directory, use the “fs sa” command:

% fs sa /afs/unc/home/user1/foo joe ldi

NOTE: The ‘l’ right is needed for every other right to be effective.

In addition to accepting any combination of the seven valid AFS rights as an argument, “fs sa” also accepts the following shorthand notations:

write – All rights except administer (a) (i.e., rlidwk);

read – Read and lookup rights (rl);

all – All seven rights (rlidwka);

none – No rights, this removes the user’s entry from the ACL entirely.

So, if you wish to remove user1 from an ACL and allow user2 to read files, you could say:

% fs sa /afs/unc/home/user1/foo user1 none user2 read

Protection groups

AFS also provides groups of users.  An AFS protection group is a similar concept to a UNIX user group.  An AFS group is used exclusively for file protection in access control lists.  These groups are managed by the distributed database component of AFS, and may be modified from any AFS client in the cell.  There may be some short latency for the permissions to take effect while the database is distributed among the AFS file servers.

AFS allows individual users to create and maintain their own groups, which can then be used by any user on any ACL.  This allows users to grant read/write permissions in a more controlled way than UNIX.

There are two types of groups in AFS: user groups and system groups.  All user groups must begin with the user’s name, followed by a colon, followed by a lower case name with no colons in it.  Only administrators create system groups, such as “somegroup”, which have no true owner.

The command to create a group is:

% pts creategroup user:name owner

where user is your login, name is the name you want to give the group, and owner is the person or group with administration rights over the group.  The owner can be your login, the group itself, or another group you own.  If the group is to be owned by your login, you can omit it from the “pts creategroup” command.  “pts creategroup” can be shortened to “pts cg”.  For example:

% pts creategroup -name yourlogin:friends
group yourlogin:friends has id -205

To see which groups you own or belong to, use the command “pts listowned”.  For example:

% pts listowned login
Groups owned by login (id: 2857) are:
user1:friends

To add users to a group, you must be an owner of the group, be the system  administrator, or have been given permission by the group owner.  The command to add users to a group is:  “pts adduser user group”.  For example:

% pts adduser user2 login:friends

You can use the “pts membership” command to see who belongs to a given group or which groups a user belongs to:

% pts membership login:friends
Members of user1:friends (id: -205) are:
login
user2

% pts membership user2
Groups user2 (id: 2857) is a member of:
user1:friends

Finally, you can delete users from a group with the command:  “pts remove user”.

Two important groups that are always available in AFS are system:anyuser and system:authuser.  “system:anyuser” is any person with access to the AFS file system, who may or may not have been authenticated to AFS, so this is basically anyone from anywhere.  “system:authuser” is any person who has been authenticated by the local AFS cell.

Using groups in large projects

Each user and research group can create and administer their own groups without mailing to help.  If you have a large, active group, it is useful to spread out the administration among several people, so the change can be made quickly.  For this situation, you can set up an administrative group to own the research group.  For example, the group “jbs:colab” replaced the old UNIX group “textlab”.  This group is owned by “jbs:colab-admin”, whose members are people authorized to make changes to the group “jbs:colab”.  To set this up, the owner of the group (in this case “jbs”) issues these commands:

% pts creategroup jbs:colab-admin
% pts creategroup -name jbs:colab -owner jbs:colab-admin

Home directory permissions

When you get your AFS home directory, it will be set up to provide you security by default.  Your top level directory permissions will be set up like this:

% fs la /afs/unc/home/user1
Access list for /afs/unc/home/user1 is
Normal rights:
user1 rlidwka
system:anyuser l
system:administrators rlidwka

This means that anyone can do an ls in your directory and see the names of your files, but cannot read any of them.  There will also be two special sub-directories in your AFS home directory with the following permissions:

% fs la /afs/unc/home/user1/public
Access list for /afs/unc/home/user1/public is
Normal rights:
user1 rlidwka
cs-machines rl
system:administrators rlidwka

% fs la /afs/unc/home/user1/private
Access list for /afs/unc/home/user1/private is
Normal rights:
user1 rlidwka

These permissions allow anyone with AFS access to read things in ~user1/public, and allows no one except the owner to run ls or read files in ~user1/private.

Note the special group “cs-machines”.  This group contains a block of IP addresses allocated to Computer Science.  This special group allows machines AFS access to your files without having an AFS token.  Using this group means any machine or person logged into a CS machine has cs-machines access to your files.  The cs-machines group is more restrictive then the system:anyuser group but needs to be used with caution.

You will also notice that two files have been moved from your main home directory into ~/public and symbolic links left in their original locations.  These files, calendar and .plan, must be readable by everyone for the utility that uses them to run.  (This is the same in NFS.)  The calendar file, for example, must be read by the reminder service program on one of our servers, and this program does not have a token to read your home directory.

All your sub-directories have inherited the ACL of your main directory at the time of creation, except for ~/public and ~/private.

You are free to relax this security, but remember that AFS permissions work on the directory level, not the file level.  If you make files in a directory readable, all the files in that directory are readable, regardless of the UNIX “group” and “other” mode bits.  If you want to protect some files in a directory, move them into a protected directory and put symbolic links to the original directory.

Resources on AFS

See http://docs.openafs.org/ for the OpenAFS online manuals.  The “AFS Users’s Guide”, which is on this page, is an excellent manual for beginners and covers all of the above information and more.


AFS for Macintosh OS X

Reviewed by bil 2018.05.05

How to setup AFS for OS X

Installing and setting up openAFS on OS X is pretty straightforward. You need to install the AFS client, configure it for our cell.

Auristor is the company that has taken over development of the afs client, the installer can be found here:
https://www.auristor.com/openafs/client-installer/

You will have to scroll through their terms and conditions and also register in advance before you can download the client When you run the installer, you will be prompted for the name of our cell, that is cs-old.sites.unc.edu.

Once you have installed the client, open a terminal and run:

kinit your-cs-id@CSX.UNC.EDU

aklog

If you login successfully, you can see your Kerberos tickets with

klist

And your afs tokens:

tokens

To get to AFS in the terminal run

open /afs/cs-old.sites.unc.edu

And to open your home dir:

open /afs/cs-old.sites.unc.edu/home/your-cs-id

AFS Tips

Various AFS tips

Reviewed by bil Hays 2020-04-20

Resources on AFS

See the AFS Introduction page for more information on getting started with AFS, or click on the “filed under” AFS tag at the top of the page.

Note that this page is directed to users of linux and MacOS, Windows users are encouraged to use Filezilla if they need to access AFS.

The pagsh command

The pagsh command creates a PAG, or Process Authentication Group, structure into which the ticket is stored.  All children of the pagsh (the shell you type as the next command) have access to that ticket.  If you omit the pagsh, commands such as lpr that don’t run under your userid will not be able to access your ticket and your files.  When you log in at the console or via ssh the PAG structure is already set up for you.

If you use ssh public keys to login to our systems you need to run the following to get an afs token:

pagsh
/usr/kerberos/bin/kinit
aklog

See “man pagsh” and the AFS aklog help page for more information.

Write on close

Network filesystems often have semantic differences from local filesystems, and OpenAFS is no exception.  For OpenAFS, the big difference for developers is that it does not implement write on commit semantics but rather write on close.  In other words, when a client issues a write request, that request does not necessarily cause other clients reading the data to be aware of the new contents.  Instead, OpenAFS will write on the closing of the file (or an fsync() call).  While this is not necessarily specific to OpenAFS, it is a subtlety of networked filesystems that many developers may not be aware of, so they need to be more careful about checking the return status of file close() calls, and they also need to be aware of the differences so that they can properly handle cross-system coordination if based on contents of files.

Renew kerberos tickets and afs tokens

If you have long-running jobs that exceed your token lifetime, or you need to keep a token alive, you can use the krenew command to extend you AFS token to a maximum of two weeks.  Before you can do this, you must set the KINIT_PROG environment variable.  In bash shell, to this:

% export KINIT_PROG=/usr/bin/aklog

In the csh/tcsh shell, do this:

% setenv KINIT_PROG /usr/bin/aklog

The  krenew command renews your Kerberos 5 TGT and AFS token up to the maximum of 14 days, to renew every 60 minutes execute:

% krenew -K 60 -t -b

See “man krenew” for more information.

Cron and at jobs

Cron and at jobs don’t work with AFS because you aren’t there to authenticate as yourself.  Thus the cron or at job has no afs token with which to modify your files.

If you need to a job just once, similar to an “at” job, you can start the job in a script and use the “sleep” command to execute your job in the future.  It is possible to run cron jobs using the “k5start” command.  See man k5start for more information.  This requires a special account that uses Kerberos5 keytabs.

Changing multiple ACLs at once

If you wish to change the ACL on an entire subtree of your directory, you can use the find command:

1. Set the permissions the way you want on the top of the subtree, using ‘fs sa’.

2. Execute a find command to change everything in and below subtree:

% find subtree -type d -exec fs copyacl subtree {} \;

There MUST be a space between the right bracket and backslash “} \;” at the end of the line!

How do I use ‘su’?

Su only runs as the UNIX user, not the AFS user.  If someone runs ‘su’ in one of your windows, they do not get a token for that user.  This is one of the security benefits of AFS.  Someone cannot su and get to your AFS protected files.

Making your files accessible to others

There are several ways to make files available to external researchers. In increasing degrees of privacy, these are:

1. You can making files in a directory available to all users on AFS by adding

system:anyuser rl

to the acl for that directory. You will also have to have

system:anyuser l

on every path above the shared directory. It is already on /afs and/afs/cs-old.sites.unc.edu.

2. To make files accessible to all users on a remote machine (e.g.,, the researcher’s workstation), send mail to help specifying the Internet number of the workstation.  A “user” for that machine will be created that can then be added to your acl.


Disk Usage

Monitoring and controlling UNIX disk space use

Reviewed by John Sopko 11/13/2019

Your home directory is the directory you find yourself in when you log in on virtually any Linux machine in the department. All users’ home directories can be accessed by the path /home/login the actual directory will be in a partition (a part of a disk) of some AFS file server. Note that /home/login is a symbolic link to your AFS space in our cell /afs/cs-old.sites.unc.edu/home/login.

1. To find out how much AFS space you are using execute the commands:

cd (this takes you to your home directory)
fs exam .

File . (536884167.1.1) contained in volume 536884167
Volume status for vid = 536884167 named D3.home.frog
Current disk quota is 4000000
Current blocks used are 2051002
The partition has 71458102 blocks available out of 129319696

 

The “Current disk quota” and “Current blocks used” are given in 1k blocks, so, for example, “Current blocks used are 2051002” indicates you are using 2051 MegaBytes or 2.051GigaBytes of space and the quote is 4GB. The partition space is the amount of space on the physical disk partition also in 1k blocks.

2. The disk space of any file or directory can be determined using the Linux “du”, (disk usage), command. You can use this at the top level of your home directory to learn how much space that directory takes. The numbers provided are in kilobytes; see “man du” for details. For example, the following du command gives a summary of the size of all directories in your home directory:

cd
du -s .??* *

The results are given in kilobytes. You can use the “-h” (human readable) option to have larger files and directories listed in megabytes or gigabytes. From the output of the du command you can see which directories are taking the most room and cd to those directories and repeat the command to isolate where all your space is being used.

NOTE: If you have any volumes mounted under your home directory or sub-directories the du command will include those in your total. Use the “fs ls *” comand in a directory to see if any volumes mounted in a directory. Most users do not mount volumes in there home directory and this is not an issue.

3. For information on the total space available on the partition where your home directory currently resides, execute the following afs command:

cd
fs df

SUGGESTIONS FOR LIMITING FILE SPACE

If you have a Computer Science google account you can move files into your google drive space. Currently there is no space limit in your departments google drive.

To reduce your disk space use, you can either remove, truncate, or compress some files. Here are some specific methods:

  1. Simply remove files you are sure you don’t need any more.
  2. Copy files you will not need for a good while to DVD. You can buy them at the Student Stores.
  3. An option for files-I’m-going-to-need-soon-but-not-today is to “tar” and “compress” them. Example: You have a “working copy” of a directory called “bigdir”:

 

% cd bigdir
 % make clean (.o files don't compress well)
 cd ..
 % tar cf bigdir.tar bigdir
 % gzip -v bigdir.tar (creates bigdir.tar.gz)
 % rm -rf bigdir

 

Compression is usually 50-60% for text files but can be as high as 90%.

 

TO GET IT BACK

 

% cd to-where-you-want-the-software
% tar zxf bigdir.tar.gz

AFS Aklog

AFS tokens and kerberos information

Reviewed by John Sopko 12/25/2019

The AFS klog command is no longer supported on the Computer Science departments linux machines for obtaining AFS tokens to the cs-old.sites.unc.edu AFS file server cell.  The klog command is based on Kerberos version 4 which is no longer being developed. The klog command can still be used to obtain AFS tokens to other cells that have not yet converted to use Kerberos version 5. The main campus AFS isis.unc.edu cell supports Kerberos 5, you should use the method described below to obtain AFS tokens instead of using the klog command.  At some point the klog command will not work for you.

The Computer Science department’s linux AFS clients are configured to automatically obtain AFS tokens from the department’s Kerberos 5 servers. If you login to a Red Hat linux desktop machine or if you use ssh to login to the departments servers you automatically get an AFS token that is valid for 7 days. You can still use the AFS “tokens” command line utility to view the remaining lifetime of your AFS tokens.  Below is detailed information on how to manually obtain an AFS token to any AFS cell that supports AFS Kerberos 5 including our cs-old.sites.unc.edu cell.

Instead of using the “klog” command you now use the following 2 commands:

/usr/bin/kinit -l7d
/usr/bin/aklog

Note on Red Hat 5.x systems the kerberos commands are kept in /usr/kerberos/bin.  On Red Hat 6.x systems and Ubuntu systems the kerberos commands are located at in /usr/bin. Execute “lsb_release -d” to print the operating system information for the system you are logged into.

You can make a shell command alias to simulate the deprecated AFS klog command, for example to
create an alias called “ka”:

csh or tcsh alias command:

alias ka ‘/usr/bin/kinit -l7d; /usr/bin/aklog’

bash alias command:

alias ka=’/usr/bin/kinit -l7d; /usr/bin/aklog’

The kinit and aklog commands without arguments will default to getting tickets and afs tokens for our cs-old.sites.unc.edu AFS cell.

The Kerberos 5 “kinit” command takes several options.  The “-l7d” option will give you a Kerberos 5 ticket good for our configured maximum time of 7 days.  Without this option you will get a token for whatever the default kinit command is compiled with, usually 24 hours.

To obtain an afs token to another AFS cell besides the default cs-old.sites.unc.edu cell use the following commands. For example to obtain an AFS tokens to the campus AFS cell:

/usr/bin/kinit -l7d onyen@ISIS.UNC.EDU
/usr/bin/aklog -cell isis.unc.edu

Note the “ISIS.UNC.EdU” is the Kerberos 5 REALM for campus and needs to be specified in upper case letters.  By convention Kerberos 5 REALMs are in upper case to distinguish them from DNS domains.

Our Computer Science Linux Kerberos 5 REALM is “CS.UNC.EDU”.  We use this Kerberos REALM name because the “CS.UNC.EDU” realm is what our Windows Active Directory Server uses for its Kerberos REALM name.

The “kinit” command obtains your Kerberos 5 credentials.  The technical term is a ticket granting ticket or TGT.  The Open AFS “aklog” command generates an AFS token for you based on your TGT.

Here is another example.  Some remote user who used to use the klog command wants to obtain an AFS token to our cs-old.sites.unc.edu cell. The remote user would use:

kinit -l7d compsci_login@CS.UNC.EDU
aklog -cell cs-old.sites.unc.edu

The remote user will have to have these utilities located on their machine.  The aklog command comes with the Open AFS client software and the kinit command with the Kerberos software.

Another Kerberos command line utility that will list your Kerberos ticket granting tickets is:

/usr/bin/klist

Kerberos ticket granting tickets have an initial lifetime and a renew lifetime. This is listed in the klist output. Our CS.UNC.EDU and the campus ISIS.UNC.EDU has a maximum renew time of 14days.  You can renew your Kerberos TGT and afs tokens up to the renew time without entering a password.  Use the “-R” option to renew a kerberos ticket:

/usr/bin/kinit -R
aklog

Renew kerberos tickets and afs tokens

If you have long-running jobs that exceed your token lifetime, or you need to keep a token alive, you can use the krenew command to extend you AFS token to a maximum of two weeks.  Before you can do this, you must set the KINIT_PROG environment variable.  In bash shell set the following:

% export KINIT_PROG=/usr/bin/aklog

In the csh/tcsh shell set:

% setenv KINIT_PROG /usr/bin/aklog

You can place these commands in your .cshrc or .bashrc shell startup files.

The  krenew command renews your Kerberos 5 TGT and AFS token up to the maximum of 14 days, to renew every 60 minutes execute:

% /usr/bin/krenew -K 60 -t -b

You can make a command alias to renew your tokens:

bash alias command:

alias kr=’/usr/bin/krenew -K 60 -t -b’

csh or tcsh alias command:

alias kr ‘/usr/bin/krenew -K 60 -t -b’

See “man krenew” for more information.

If you really need to maintain a token indefinitely email help@cs-old.sites.unc.edu. There is a method for doing so using the k5start command but should not be used unless absolutely necessary.