This document provides you with all neccessary steps to install an OpenAFS server on Gentoo Linux. Parts of this document are taken from the AFS FAQ and IBM's Quick Beginnings guide on AFS. Well, never reinvent the wheel. :)

AFS is a distributed filesystem that enables co-operating hosts (clients and servers) to efficiently share filesystem resources across both local area and wide area networks. Clients hold a cache for often used objects (files), to get quicker access to them.

AFS is based on a distributed file system originally developed at the Information Technology Center at Carnegie-Mellon University that was called the "Andrew File System". "Andrew" was the name of the research project at CMU - honouring the founders of the University. Once Transarc was formed and AFS became a product, the "Andrew" was dropped to indicate that AFS had gone beyond the Andrew research project and had become a supported, product quality filesystem. However, there were a number of existing cells that rooted their filesystem as /afs. At the time, changing the root of the filesystem was a non-trivial undertaking. So, to save the early AFS sites from having to rename their filesystem, AFS remained as the name and filesystem root.

An AFS cell is a collection of servers grouped together administratively and presenting a single, cohesive filesystem. Typically, an AFS cell is a set of hosts that use the same Internet domain name (for example, gentoo.org) Users log into AFS client workstations which request information and files from the cell's servers on behalf of the users. Users won't know on which server a file which they are accessing, is located. They even won't notice if a server will be located to another room, since every volume can be replicated and moved to another server without any user noticing. The files are always accessable. Well, it's like NFS on steroids :)

The main strengths of AFS are its: caching facility (on client side, typically 100M to 1GB), security features (Kerberos 4 based, access control lists), simplicity of addressing (you just have one filesystem), scalability (add further servers to your cell as needed), communications protocol.

Read the AFS FAQ.

OpenAFS main page is at www.openafs.org.

AFS was originally developed by Transarc which is now owned by IBM. You can find some information about AFS on Transarc's Webpage.

OpenAFS has great logging facilities. However, by default it logs straight into its own logs instead of through the system logging facilities you have on your system. To have the servers log through your system logger, use the -syslog option for all bos commands.

You can get the original IBM AFS Documentation. It is very well written and you really want read it if it is up to you to administer a AFS Server.

# emerge app-doc/afsdoc

You should adjust the two files CellServDB and ThisCell before you build the AFS client. (These files are in /usr/portage/net-fs/openafs/files)

CellServDB:
>netlabs        #Cell name
10.0.0.1        #storage

ThisCell:
netlabs       

CellServDB tells your client which server(s) it needs to contact for a specific cell. ThisCell should be quite obvious. Normally you use a name which is unique for your organisation. Your (official) domain might be a good choice.

# emerge net-fs/openafs

After successful compilation you're ready to go.

The following command will create the appropriate links to start your afs client on system startup.

# rc-update add afs default

The following command will install all necessary binaries for setting up an AFS Server and Client.

# emerge net-fs/openafs

You need to remove the sample CellServDB and ThisCell file first.

# rm /usr/vice/etc/ThisCell
# rm /usr/vice/etc/CellServDB

Next you will run the bosserver command to initialize the Basic OverSeer (BOS) Server, which monitors and controls other AFS server processes on its server machine. Think of it as init for the system. Include the -noauth flag to disable authorization checking, since you haven't added the admin user yet.

# /usr/afs/bin/bosserver -noauth &

Verify that the BOS Server created /usr/vice/etc/CellServDB and /usr/vice/etc/ThisCell

# ls -al /usr/vice/etc/
-rw-r--r--    1 root     root           41 Jun  4 22:21 CellServDB
-rw-r--r--    1 root     root            7 Jun  4 22:21 ThisCell

Now assign your cell's name.

Run the bos setcellname command to set the cell name:

# /usr/afs/bin/bos setcellname <server name> <cell name> -noauth

Next use the bos create command to create entries for the four database server processes in the /usr/afs/local/BosConfig file. The four processes run on database server machines only.

# /usr/afs/bin/bos create <server name> kaserver simple /usr/afs/bin/kaserver -cell <cell name> -noauth
# /usr/afs/bin/bos create <server name> buserver simple /usr/afs/bin/buserver -cell <cell name> -noauth
# /usr/afs/bin/bos create <server name> ptserver simple /usr/afs/bin/ptserver -cell <cell name> -noauth
# /usr/afs/bin/bos create <server name> vlserver simple /usr/afs/bin/vlserver -cell <cell name> -noauth

You can verify that all servers are running with the bos status command:

# /usr/afs/bin/bos status <server name> -noauth
Instance kaserver, currently running normally.
Instance buserver, currently running normally.
Instance ptserver, currently running normally.
Instance vlserver, currently running normally.

Now we'll initialize the cell's security mechanisms. We'll begin by creating the following two initial entries in the Authentication Database: The main administrative account, called admin by convention and an entry for the AFS server processes, called afs. No user logs in under the identity afs, but the Authentication Server's Ticket Granting Service (TGS) module uses the account to encrypt the server tickets that it grants to AFS clients. This sounds pretty much like Kerberos :)

Enter kas interactive mode

# /usr/afs/bin/kas -cell <cell name> -noauth
ka> create afs
initial_password:
Verifying, please re-enter initial_password:
ka> create admin
initial_password:
Verifying, please re-enter initial_password:
ka> examine afs

User data for afs
key (0) cksum is 2651715259, last cpw: Mon Jun  4 20:49:30 2001
password will never expire.
An unlimited number of unsuccessful authentications is permitted.
entry never expires.  Max ticket lifetime 100.00 hours.
last mod on Mon Jun  4 20:49:30 2001 by $lt;none>
permit password reuse
ka> setfields admin -flags admin
ka> examine admin

User data for admin (ADMIN)
key (0) cksum is 2651715259, last cpw: Mon Jun  4 20:49:59 2001
password will never expire.
An unlimited number of unsuccessful authentications is permitted.
entry never expires.  Max ticket lifetime 25.00 hours.
last mod on Mon Jun  4 20:51:10 2001 by $lt;none>
permit password reuse
ka>

Run the bos adduser command, to add the admin user to the /usr/afs/etc/UserList.

# /usr/afs/bin/bos adduser <server name> admin -cell <cell name> -noauth

Issue the bos addkey command to define the AFS Server encryption key in /usr/afs/etc/KeyFile.

# /usr/afs/bin/bos addkey  <server name> -kvno 0 -cell <cell name> -noauth
input key:
Retype input key:

Issue the pts createuser command to create a Protection Database entry for the admin user.

# /usr/afs/bin/pts createuser -name admin -cell <cell name> [-id <AFS UID>] -noauth

Issue the pts adduser command to make the admin user a member of the system:administrators group, and the pts membership command to verify the new membership

# /usr/afs/bin/pts adduser admin system:administrators -cell <cell name> -noauth
# /usr/afs/bin/pts membership admin -cell <cell name> -noauth
Groups admin (id: 1) is a member of:
system:administrators

Restart all AFS Server processes

# /usr/afs/bin/bos restart <server name> -all -cell <cell name> -noauth

Start the fs process, which consists of the File Server, Volume Server and Salvager (fileserver, volserver and salvager processes).

# /usr/afs/bin/bos create <server name> fs fs /usr/afs/bin/fileserver /usr/afs/bin/volserver /usr/afs/bin/salvager -cell <cell name> -noauth

Verify that all processes are running

# /usr/afs/bin/bos status <server name> -long -noauth
Instance kaserver, (type is simple) currently running normally.
Process last started at Mon Jun  4 21:07:17 2001 (2 proc starts)
Last exit at Mon Jun  4 21:07:17 2001
Command 1 is '/usr/afs/bin/kaserver'

Instance buserver, (type is simple) currently running normally.
Process last started at Mon Jun  4 21:07:17 2001 (2 proc starts)
Last exit at Mon Jun  4 21:07:17 2001
Command 1 is '/usr/afs/bin/buserver'

Instance ptserver, (type is simple) currently running normally.
Process last started at Mon Jun  4 21:07:17 2001 (2 proc starts)
Last exit at Mon Jun  4 21:07:17 2001
Command 1 is '/usr/afs/bin/ptserver'

Instance vlserver, (type is simple) currently running normally.
Process last started at Mon Jun  4 21:07:17 2001 (2 proc starts)
Last exit at Mon Jun  4 21:07:17 2001
Command 1 is '/usr/afs/bin/vlserver'

Instance fs, (type is fs) currently running normally.
Auxiliary status is: file server running.
Process last started at Mon Jun  4 21:09:30 2001 (2 proc starts)
Command 1 is '/usr/afs/bin/fileserver'
Command 2 is '/usr/afs/bin/volserver'
Command 3 is '/usr/afs/bin/salvager'

Your next action depends on whether you have ever run AFS file server machines in the cell.

If you are installing the first AFS Server ever in the cell create the first AFS volume, root.afs

# /usr/afs/bin/vos create <server name> <partition name> root.afs -cell <cell name> -noauth

If there are existing AFS file server machines and volumes in the cell issue the vos sncvldb and vos syncserv commands to synchronize the VLDB (Volume Location Database) with the actual state of volumes on the local machine. This will copy all necessary data to your new server.

If the command fails with the message "partition /vicepa does not exist on the server", ensure that the partition is mounted before running OpenAFS servers, or mount the directory and restart the processes using /usr/afs/bin/bos restart <server name> -all -cell <cell name> -noauth.

# /usr/afs/bin/vos syncvldb <server name> -cell <cell name> -verbose -noauth
# /usr/afs/bin/vos syncserv <server name> -cell <cell name> -verbose -noauth 

# /usr/afs/bin/bos create <server name> 
upserver simple "/usr/afs/bin/upserver 
-crypt /usr/afs/etc -clear /usr/afs/bin" 
-cell <cell name> -noauth

First you need to set some ACLs, so that any user can lookup /afs.

# /usr/afs/bin/fs setacl /afs system:anyuser rl

Then you need to create the root volume, mount it readonly on /afs/<cell name> and read/write on /afs/.<cell name>.

# /usr/afs/bin/vos create <server name><partition name> root.cell
# /usr/afs/bin/fs mkmount /afs/<cell name> root.cell 
# /usr/afs/bin/fs setacl /afs/<cell name> system:anyuser rl
# /usr/afs/bin/fs mkmount /afs/.<cell name> root.cell -rw

Finally you're done!!! You should now have a working AFS file server on your local network. Time to get a big cup of coffee and print out the AFS documentation!!!

OpenAFS is an extensive technology. Please read the AFS documentation for more information. We only list a few administrative tasks in this chapter.

To use AFS you need to authenticate against the KA Server if using an implementation AFS Kerberos 4, or against a Kerberos 5 KDC if using MIT, Heimdal, or ShiShi Kerberos 5. However in order to login to a machine you will also need a user account, this can be local in /etc/passwd, NIS, LDAP (OpenLDAP), or a Hesiod database. PAM allows Gentoo to tie the authentication against AFS and login to the user account.

You will need to update /etc/pam.d/system-auth which is used by the other configurations. "use_first_pass" indicates it will be checked first against the user login, and "ignore_root" stops the local superuser being checked so as to order to allow login if AFS or the network fails.

auth       required     pam_env.so
auth       sufficient   pam_unix.so likeauth nullok
auth       sufficient   pam_afs.so.1 use_first_pass ignore_root
auth       required     pam_deny.so

account    required     pam_unix.so

password   required     pam_cracklib.so retry=3
password   sufficient   pam_unix.so nullok md5 shadow use_authtok
password   required     pam_deny.so

session    required     pam_limits.so
session    required     pam_unix.so

In order for sudo to keep the real user's token and to prevent local users gaining AFS access change /etc/pam.d/su as follows:

# Here, users with uid > 100 are considered to belong to AFS and users with
# uid <= 100 are ignored by pam_afs.
auth       sufficient   /usr/afsws/lib/pam_afs.so.1 ignore_uid 100

auth       sufficient   /lib/security/pam_rootok.so

# If you want to restrict users begin allowed to su even more,
# create /etc/security/suauth.allow (or to that matter) that is only
# writable by root, and add users that are allowed to su to that
# file, one per line.
#auth       required     /lib/security/pam_listfile.so item=ruser \
#       sense=allow onerr=fail file=/etc/security/suauth.allow

# Uncomment this to allow users in the wheel group to su without
# entering a passwd.
#auth       sufficient   /lib/security/pam_wheel.so use_uid trust

# Alternatively to above, you can implement a list of users that do
# not need to supply a passwd with a list.
#auth       sufficient   /lib/security/pam_listfile.so item=ruser \
#       sense=allow onerr=fail file=/etc/security/suauth.nopass

# Comment this to allow any user, even those not in the 'wheel'
# group to su
auth       required     /lib/security/pam_wheel.so use_uid

auth       required     /lib/security/pam_stack.so service=system-auth

account    required     /lib/security/pam_stack.so service=system-auth

password   required     /lib/security/pam_stack.so service=system-auth

session    required     /lib/security/pam_stack.so service=system-auth
session    optional     /lib/security/pam_xauth.so

# Here we prevent the real user id's token from being dropped
session    optional     /usr/afsws/lib/pam_afs.so.1 no_unlog