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:
- Download the athena-1.0.5.tar.gz file. This should expand automagically with Stuffit Expander or OpenUP, leaving you a folder named usr with an athena folder inside.
- The Athena folder needs to be copied to /usr , and that directory cannot be seen in the Finder. So you'll need to open a terminal window and type "sudo /bin/tcsh" to act as root.
- Then change the directory to the /usr folder you downloaded (an easy way to do this if you don't know the entire path to that folder is to type "cd" followed by a space in the terminal window and then drag the /usr folder into the terminal--the drag will copy the path to the terminal).
- Confirm that you are in the correct usr directory by typing "ls". You should see a single directory named athena.
- Then copy the athena folder to /usr by typing:
cp -R * /usr/This will copy all of the files and directories for athena into /usr.
- Change directories to /usr ("cd /usr")to verify that you've copied the files to the correct location.
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.
- Type "sudo /bin/tcsh" to act as root.
- cd to /etc
- Use vi or another text editor to open the krb.conf file. This contains a list of kerberos realms and servers. You'll need to add the appropriate entries for the kerberos realm you wish to authenticate against (contact your system administrator if you don't have this information). For example, UNC users of Isis would add the following lines:
ISIS.UNC.EDU ISIS.UNC.EDU krb0.unc.edu admin server ISIS.UNC.EDU krb1.unc.edu ISIS.UNC.EDU krb2.unc.eduAnd CS affiliates at UNC would add:
CS.UNC.EDU CS.UNC.EDU kerberos.cs.unc.edu admin server CS.UNC.EDU kerberos-1.cs.unc.edu admin server CS.UNC.EDU kerberos-2.cs.unc.edu admin serverSave the file (it's marked read only, so in vi you'd use "w!" to override).
- You'll also need to add some lines to the krb.realms file. Isis users will add:
isis.unc.edu ISIS.UNC.EDU .isis.unc.edu ISIS.UNC.EDUand CS users would add:
cs.unc.edu CS.UNC.EDU .cs.unc.edu CS.UNC.EDUSave the file, and you're done.
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.realmwhere 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 750Don'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.EDUThis 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.
- Download the Arla 0.35.3 binary for OS X, it's in a .sit file.
- Once you've uncompressed the file you'll have a package named arla-0.35.3.pkg, doubleclick on this to start the installation. You'll be prompted for an administrative password, and go through a normal package installation procedure.
- Then in a terminal window, cd to /usr/arla and do an ls to make sure you have the arla directories in place:
bin cache etc include info lib libexec man sbinConfiguring 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.
- From a terminal window type "sudo /bin/tcsh" to act as root.
- cd to /usr/arla/etc
- Open the file ThisCell with a text editor such as vi. Replace the one line in that file with the name of the cell you wish to access as your local cell. For example, most UNC users would use isis.unc.edu, and CS users would use cs.unc.edu. Unlike the other configuration files described herein, you should have only one line in this file.
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.eduUsers 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.eduA 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.
- 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
- 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 0You 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.realmKauth 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 750Then type:
/usr/athena/bin/afslogNo errors? So far, so good. Now type:
/usr/arla/bin/klog username@afs.cellwhere 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.hereand 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:
- Type "sudo /bin/tcsh" to act as root.
- cd to /System/Library/StartupItems/Arla
- use vi to comment out the lines used to start Arla with a "#" sign, so that the file looks like:
#!/bin/sh ConsoleMessage "Starting Arla file system" #/usr/arla/sbin/startarla #/usr/sbin/disktool -a xfs /afs 0Once 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, kdcNow, as root type:
niload services . <servicesUpdating 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_hpuxIn 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_usernameIn order to fix this, you need to change your local UID to match the UID in the AFS cell.
- Type "cd" to go to your home directory.
- su to root. You may have to enable this function using NetInfo manager.
- Open NetInfo manager (if it's not already open). Under Domain, Security, use the Authenticate open to authenticate yourself.
- In the Directory Browser, go to /users and find your username and select it with the mouse.
- In the lower part of the window, find the Property "uid" and then click on the associated Value. Mostly likely it's set to 501. Change this to the UID you have in AFS space.
- Quit NetInfo Manager and save the changes
- Now in the terminal window where you are logged in as root, type:
%su
%find / -xdev -user <old Mac uid> -print -exec chown <AFS uid> {} \;Give this some time to run, it can take a while.
- Finally, log out and back in again, and try things out.
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.
- 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 .
- 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_choiceAcknowledgements
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.