Install Arla

This document is of historical value only, if that, see the arla web page for current info

Basically, there are two major components you need to install, Arla and KTH-krb.

Kerberos

AFS relies on kerberos authentication. OS X comes with a version of kerberos, but it's not compatible with AFS (AFS uses version 4 and OS X comes with version 5). The folks at Arla recommend use of the KTH-krb implementation (you can find a lot of documentation on Kerberos there), and they've also provided a binary for use with Darwin 1.3 (which is the core of OS X). You can use other kerberos implementations, see the Arla web pages for more information.

Installing Athena

Here's what you do:

Configuring Kerberos

Athena should work as is for most users, so you can skip this section and test the installation if you like.

Athena looks for kerberos services on a machine named kerberos in the domain of the same name as the realm (for example, if your realm is CS.UNC.EDU, athena will look for kerberos.cs.unc.edu for kerberos services). So if your DNS service is set up this way, athena will just work. If it's not, or if you're using some of the other kerberos clients, you may need to make some modifications to the krb.conf and krb.realms files.

Testing the installation

Now you'll want to test the installation to make sure that everything's working ok. Exit root, and cd to /usr/athena/bin and type:

./kauth username@kerberos.realm

where username is your id and kerberos.realm is the system you wish to authenticate against. You should be prompted for a password, and see something like:

[localhost:/usr/athena/bin] hays% ./kauth hays@cs.unc.edu
hays@CS.UNC.EDU's Password: 
kerberos-iv/udp unknown service, using default port 750

Don't worry about the unknown service message, we'll fix that later. If you get an error, you may be able to troubleshoot it at the KTH-krb documentation troubleshooting section.

Now try ./klist, you should get something like this:

[localhost:/usr/athena/bin] hays% ./klist
Ticket file:    /tmp/tkt501
Principal:      hays@CS.UNC.EDU
   
  Issued           Expires          Principal
Apr 18 19:43:40  Apr 19 05:43:40  krbtgt.CS.UNC.EDU@CS.UNC.EDU

This show that you have a ticket from the kerberos server, and when it will expire. So kerberos is working.

Arla

Make sure you take a look at the main page for the Arla project for updates and additional information before you start.

Configuring Arla

Set ThisCell to your local AFS cell

There's a file named ThisCell in /usr/arla/etc that contains the name of the cell your machine will use as a starting point. For performance reasons, you'll want this set to your home cell.

Trim the CellServDB file

Also in /usr/arla/etc you'll find a CellServDB file. This contains the names and server data for all known AFS cells. You'll need to check this file to make sure it has the entries for the cells you want to use

Here's an example of what a CellServDB entries for someone accessing the Isis afs cell:

>isis.unc.edu # University of North Carolina Project Isis 
152.2.1.5 #db0.isis.unc.edu 
152.2.1.6 #db1.isis.unc.edu 
152.2.1.7 #db2.isis.unc.edu 

Users of the UNC CH Computer Science cell would have this in the CellServDB file:

>cs.unc.edu          # University of North Carolina at Chapel Hill
152.2.128.1          #crow.cs.unc.edu
152.2.128.2          #falcon.cs.unc.edu
152.2.128.8          #thrush.cs.unc.edu

A note for cs.unc.edu users

The cs.unc.edu has static links to other cells, and this affects performance adversely since Finder wants to stat each and every directory. There are two ways to get around this.

  1. You can trim the CellServDB file down to only those cells you'll want to access. This is a good option if you only access a few cells, such as cs.unc.edu and isis.unc.edu
  2. You can use a full CellServDB file, but set the ThisCell file to isis.unc.edu. This works fine, and doesn't prevent you from accessing the cs.unc.edu cell.

Testing the Arla configuration

If you've gotten all of the files edited, you're ready to start Arla. This is a manual procedure--Arla's already configured to start on boot, but we might as well test it out right away.

As root, type:

/usr/arla/sbin/startarla
/usr/sbin/disktool -a xfs /afs 0

You should see something like:

[localhost:/usr/arla/bin] root# /usr/arla/sbin/startarla
[localhost:/usr/arla/bin] root# /usr/sbin/disktool -a xfs /afs 0
SUCCESS: DiskArbStart()
sizeof( mach_msg_header_t ) = 24
sizeof( mach_msg_trailer_t ) = 8
sizeof( mach_msg_empty_rcv_t ) = 32
SUCCESS: msgSendBufPtr = malloc(44)
xfs afp mount will be mounted ...
[localhost:/usr/arla/bin] root#

After you run these commands, Finder should open a new window and then be very busy for a quite a while (5-20 minutes, depending on the speed of your network connection) as it checks the /afs tree for servers looking for content files. Give it plenty of time.....

While you're waiting, you can try authenticating and use terminal to verify you can browse the afs cell. Exit root if you haven't already, and type (as you did before when testing kerberos):

/usr/athena/bin/kauth username@kerberos.realm

Kauth is what you use if you on a machine in a different domain from your AFS cell (for example, if you're using an ISP and are trying to reach a cell that's not part of that ISP). It will also work if you are in the same domain, but if you are, you can also use kinit instead. You should see:

[localhost:/afs/cs.unc.edu] hays% /usr/athena/bin/kauth hays@cs.unc.edu
hays@CS.UNC.EDU's Password: 
kerberos-iv/udp unknown service, using default port 750

Then type:

/usr/athena/bin/afslog

No errors? So far, so good. Now type:

/usr/arla/bin/klog username@afs.cell

where username is your id on the AFS system, and afs.cell is the name of your AFS cell. You should see something like:

[localhost:/afs/cs.unc.edu] hays% /usr/arla/bin/klog hays@cs.unc.edu
Unable to find service afs3-fileserver/udp, using port 7000
Unable to find service afs3-callback/udp, using port 7001
Unable to find service afs3-prserver/udp, using port 7002
Unable to find service afs3-vlserver/udp, using port 7003
Unable to find service afs3-kaserver/udp, using port 7004
Unable to find service afs3-volser/udp, using port 7005
Unable to find service afs3-errors/udp, using port 7006
Unable to find service afs3-bos/udp, using port 7007
Unable to find service afs3-update/udp, using port 7008
Unable to find service afs3-rmtsys/udp, using port 7009
hays@cs.unc.edu's Password:
kerberos-iv/udp unknown service, using default port 750
[localhost:/afs/cs.unc.edu] hays%

Don't worry about the Unable to service messages, we'll fix that in a minute. Now type:

cd /afs/your.cell.here

and then do a listing to see if you can see the root of your cell.

Note: with AFS the CLI is much more responsive and supports more functionality than the Finder at this point. I recommend you use the CLI instead of Finder for AFS access. Also, each time you boot, it will take Finder some time to go through the AFS cell data, so be prepared for that. In my experience, this is not a major problem since I don't reboot OS X often.

By this time Finder should have settled down. If it doesn't, you'll want to make sure to disable Arla from starting up automatically on bootup. To do this:

Once this is done, you can safely reboot, and play around with the configuration some more, using the manual procedure for starting Arla listed above.

Updating NetInfo

The last thing you'll need to do is update the NetInfo services list so you won't get those annoying messages. You can do this via the GUI with NetInfo manager, but it's a bit painful and time consuming (I know, that's how I did it the first time).

The Arla package doesn't include a /conf/services file, so you'll make your own. Create a plain text file named services with the following lines (the last one is a service statement for kerberos, we'll put that in so we can do this in one sweep).

#
# AFS Services
#
afs3-fileserver         7000/udp        # Fileserver
afs3-callback           7001/udp        # Callback server
afs3-prserver           7002/udp        # Protection server
afs3-vlserver           7003/udp        # Volumelocation server
afs3-kaserver           7004/udp        # Kerberos authenication server
afs3-volser             7005/udp        # Volume server
afs3-errors             7006/udp        # Error server ?
afs3-bos                7007/udp        # Basic over-see server ?
afs3-update             7008/udp        # ?
afs3-rmtsys             7009/udp        # ?
kerberos-iv             750/udp         # kerberos, kdc

Now, as root type:

niload services . <services

Updating the path

The last thing you'll want to do is update the path information so you will be able to type just the command instead of including the full path. The way I did this was to include a .cshrc file in my home directory that has the following path statement in it:

set path = (${home}/bin /usr/local/bin /usr/local/etc /bin /usr/bin 
/etc /usr/etc /sbin /usr/sbin /usr/arla/bin /usr/arla/etc /usr/athena/bin .)

(Don't cut and paste this one! I've wrapped it for readability, and you don't want an LF or CR in the path statement!).

Finally, you may want to set a softlink from your home directory on your OS X machine to your home directory in AFS, this makes navigation easier.

Ok, if you've gotten all of this done, you probably want to reboot and see what that's like. Good luck!

Matching UIDs

At this point you should be able to perform most all operations from the CLI. But if you try to copy files to and from AFS space from Finder, you may encounter errors. This is probably due to a mismatch in the UID for your accounts. Ideally, you'll want not only your usernames on both your OS X machine and your AFS account to match, but also the UIDs for each.

By default, Mac OS X will start assigning UIDs at 501, so it's most likely that that's what your UID is. If, in a terminal window, you cd to your AFS home space, and do an "ls -l" you'll likely see something like this:

[localhost] hays% cd /afs/cs.unc.edu/home/hays
[localhost:cs.unc.edu/home/hays] hays% ls -l
total 211
drwxr-xr-x  3 5420    1003     2048 Jul 24  2000 DesktopFolderDB
-rw-r--r--  1 5420    1003    32768 Sep  7  2000 Fall200Scheduler.doc
drwxrwxr-x  3 daemon  1003    10240 Feb 12 10:48 autoremedy
drwxr-xr-x  2 5420    daemon   2048 Jul 25  2000 bin
drwxr-xr-x  2 5420    1003     2048 Sep 21  2000 bin-hp700_hpux

In the listing above, the number 5420 represents the UID in use by hays in AFS space. If you try to copy files via Finder, Finder sees that the local UID and the UID in AFS space do not match, and generates an error.

You can also find out what your UID is on most unix servers that support afs by using the command:

pts examinw your_username

In order to fix this, you need to change your local UID to match the UID in the AFS cell.

Making access easier

You won't want to have to navigate the entire cell's tree regularly, so you'll want to make access easier. There are a couple of things you can do.

  1. If you want to use your afs space as your home directory, you can set up your mac to do that, see ATN's document .
  2. If you want to use your local HD as your home directory, you can set up a softlink to your afs space or other afs directories in your home account space. From the terminal window:
    ln -s /afs/your.cell.here/path/to/your/afs/space/ /Users/yourlogin/your_choice
    

Acknowledgements

Although I'm willing to take the blame for this document, I got a lot of help from a lot of people. Special thanks to Murray Anderegg, Simon Spero, Magnus Ahltorp, Harald Barth and Brian Biswas.

And please send me comment, suggestions, etc.