OpenAFS installation on Debian

Posted by docelic on Mon 4 Aug 2008 at 10:58

The purpose of this article is to give you a straight-forward, Debian-friendly way of installing and configuring OpenAFS 1.4.x, the recommended production version of OpenAFS for UNIX. By the end of this guide, you will have a functional OpenAFS installation that will complete our solution for secure, centralized network logins with shared home directories.


The newest version of this article can be found at http://techpubs.spinlocksolutions.com/dklar/afs.html.

Table of Contents

Introduction
The role of AFS within a network
Glue layer: integrating AFS with system software
PAM
Conventions
OpenAFS server
OpenAFS kernel module
OpenAFS installation
Pre-configuration
Creating a new cell
Post-configuration
Accessing the files
Basic listing and information
Read and write paths, replication
Reading and writing
Creating users
Creating and mounting volumes
Setting permissions
Serving metadata
LDAP
libnss-afs
Metadata test
PAM configuration
/etc/pam.d/common-auth
/etc/pam.d/common-session
Conclusion
Links

Introduction

AFS distributed filesystem is a service that has been traditionally captivating system administrators' and advanced users' interest, but its high entry barrier and infrastructure requirements have been preventing many from using it.

AFS has already been the topic of numerous publications. Here, we will present only the necessary summary; enough information to establish the context and to achieve practical results.

You do not need to follow any external links; however, the links have been provided both throughout the article and listed all together at the end, to serve as pointers to more precise technical treatment of individual topics.

AFS was started at Carnegie Mellon University in the early 1980s, in order to easily share file data between people and departments. The system became known as the Andrew File System, or AFS, in recognition of Andrew Carnegie and Andrew Mellon, the primary benefactors of CMU. Later, AFS was supported and developed as a product by Transarc Corporation (now IBM Pittsburgh Labs). IBM branched the source of the AFS product, and made a copy of the source available for community development and maintenance. They called the release OpenAFS, which is practically the only "variant" of AFS used today for new installations.

The amount of important information related to AFS is magnitudes larger than that of, say, Kerberos or LDAP. It isn't possible to write a practical OpenAFS Guide without simply ignoring the majority of AFS concepts and without taking drastic shortcuts in reaching our final objective. However, this injustice will be compensated by hooking you up with the OpenAFS idea, helping you achieve practical results relatively quickly, and setting you underway to properly expanding your knowledge and network setup.

AFS relies on Kerberos for authentication. A working Kerberos environment is the necessary prerequisite, and the instructions on setting it up are found in another article from the series, the MIT Kerberos 5 Guide.

Furthermore, in a centralized network login solution, user metadata (Unix user and group IDs, GECOS information, home directories, preferred shells, etc.) need to be shared in a network-aware way as well. This metadata can be served using LDAP or libnss-afs. In general, LDAP is standalone and flexible, and covered in another article from the series, the OpenLDAP Guide. libnss-afs is simple and depends on the use of AFS, and covered in this Guide.

The role of AFS within a network

AFS' primary purpose is to serve files over the network in a robust, efficient, reliable and fault-tolerant way.

Its secondary purpose may be to serve user meta information through libnss-afs, unless you choose OpenLDAP for the purpose as explained in another article from the series, the OpenLDAP Guide.

While the idea of a distributed file system is not unique, let's quickly identify some of the AFS specifics:

You can find the complete AFS documentation at the OpenAFS website. After grasping the basic concepts, your most helpful resources will be quick help options supported in all commands, such as in fs help, vos help, pts help or bos help.

Glue layer: integrating AFS with system software

PAM

On all GNU/Linux-based platforms, Linux-PAM is available for service-specific authentication configuration. Linux-PAM is an implementation of PAM ("Pluggable Authentication Modules") from Sun Microsystems.

Network services, instead of having hard-coded authentication interfaces and decision methods, invoke PAM through a standard, pre-defined interface. It is then up to PAM to perform any and all authentication-related work, and report the result back to the application.

Exactly how PAM reaches the decision is none of the service's business. In traditional set-ups, that is most often done by asking and verifying usernames and passwords. In advanced networks, that could be Kerberos tickets and AFS tokens.

PAM will allow for inclusion of OpenAFS into the authentication path of all services. After typing in your password, it will be possible to verify the password against the Kerberos database and automatically obtain the Kerberos ticket and AFS token, without having to run kinit and aklog manually.

You can find the proper introduction (and complete documentation) on the Linux-PAM website. Pay special attention to the PAM Configuration File Syntax page. Also take a look at the Linux-PAM(7) and pam(7) manual pages.

Conventions

It's quite disappointing when you are not able to follow the instructions found in the documentation. Let's agree on a few points before going down to work:

OpenAFS server

OpenAFS kernel module

The only meaningful way to access data in AFS is through an AFS client. That means you will need the OpenAFS kernel module built and running on all AFS systems, including servers.

Building a kernel module through module-assistant is an extremely simple and elegant way to not have to deal with any of the complexities behind the scenes; after the following set of commands executes successfully, you will have the kernel module build as a Debian package and installed onto the system: 

sudo apt-get install module-assistant
sudo m-a prepare openafs
sudo m-a a-i openafs

OpenAFS installation

After the kernel module is installed, we can proceed with installing the rest of the OpenAFS server software: 

sudo apt-get install openafs-{fileserver,dbserver,client,krb5}

Debconf answers for reference: 

AFS cell this workstation belongs to: spinlock.hr
# (Your domain name in lowercase, matching the Kerberos realm in uppercase)

Size of AFS cache in kB? 4000000
# (Default value is 50000 for 50 MB, but you can greatly increase the
# size on modern systems to a few gigabytes, with 20000000 (20 GB) being
# the upper reasonable limit)

Run Openafs client now and at boot? No
# (It is important to say NO at this point, or the client will try to 
# start without the servers in place)

Look up AFS cells in DNS? Yes

Encrypt authenticated traffic with AFS fileserver? No
# (OpenAFS client can encrypt the communication with the fileserver. The
# performance hit is not too great to refrain from using encryption, but
# generally, disable it on local and trusted-connection clients, and enable
# it on clients using insecure channels)

Dynamically generate the contents of /afs? No

Use fakestat to avoid hangs when listing /afs? Yes

Cell this server serves files for: spinlock.hr

DB server host names for your home cell: afs1
# (Before continuing, make sure you've edited your DNS configuration or 
# /etc/hosts file as mentioned above in the section "Conventions", and that
# the command 'ping afs1' really does successfully ping your server)

Pre-configuration

Local cache

OpenAFS cache directory on AFS clients is /var/cache/openafs/. (Note that this includes your AFS servers too, as they all have AFS client software installed).

The cache directory must be on an Ext2 or Ext3 filesystem partition. In case it is, you just have to ensure there's enough disk space on the partition.

In case it is not, in case you're using a different filesystem for /var/ or /var/cache/, then you need to mount an Ext partition or file onto /var/cache/openafs/.

Kerberos principal

As Kerberos introduces mutual authentication of users and services, we need to create a Kerberos principal for our AFS service. (In general, the way it's done with Kerberos is by creating a separate principal for each of the server machines. But AFS shares the key among all AFS servers, and so we must create just one key).

The transcript below assumes you've set up Kerberos and created policy service as explained in the MIT Kerberos 5 Guide; if you did not, do so right now as Kerberos is the necessary prerequisite. 

sudo rm -f /tmp/afs.keytab

sudo kadmin.local

Authenticating as principal root/admin@SPINLOCK.HR with password.

kadmin.local:  addprinc -policy service -randkey -e des-cbc-crc:v4 afs
Principal "afs@SPINLOCK.HR" created.

kadmin.local:  ktadd -k /tmp/afs.keytab -e des-cbc-crc:v4 afs
Entry for principal afs with kvno 3, encryption type DES cbc mode with CRC-32 added to keytab WRFILE:/tmp/afs.keytab.

kadmin.local:  quit

Once the key's been created and exported to file /tmp/afs.keytab as shown, we need to load it into the AFS KeyFile. Note that the number "3" in the following command is the key version number, which has to match KVNO reported in the 'ktadd' step above. 

sudo asetkey add 3 /tmp/afs.keytab afs

To verify the key has been loaded and that there is only one key in the AFS KeyFile, run bos listkeys: 

sudo bos listkeys afs1 -localauth

key 3 has cksum 2035850286
Keys last changed on Tue Jun 24 14:04:02 2008.
All done.

In case there's something wrong and you want to remove keys from the KeyFile, run bos help for a list of available commands and bos help command for command-specific usage information.

AFS partitions

As we've hinted in the introduction, AFS works by using its own dedicated partitions. Each server can have up to 256 partitions which should be mounted to directories named /vicepXX/, where "XX" is the partition "number" going from 'a' to 'z' and from 'aa' to 'iv'.

In a simple scenario, we will have only one partition which you should format as Ext3 and mount onto /vicepa/.

In case you do not have a separate partition ready, simply creating the directory /vicepa/ in your root partition will do. Creating /vicepa/ in your existing partition is possible because AFS does not use its own low-level format for the partitions — it saves data to vice partitions using normal filesystem calls. (As said, that data is structured in a way meaningful only to AFS, but it is there in the filesystem and you are able to browse around it using cd and ls).

Creating a new cell

Now that we've installed the software components that make up the OpenAFS server and that we've taken care of the pre-configuration steps, we can create an actual AFS cell.

Important

The afs-newcell script, which is used to create a new cell, needs a simple fix in version 1.4.7.dfsg1-2 before it can be used to create a new cell (a bug about it has been open under BTS #488152).

Russ Allbery has promptly fixed the problem as usual, but to make sure there is no problem in your script, the following oneliner can be ran on any version of afs-newcell without adverse effects: 

sudo perl -pi -e 's/(-time never -general)(?! -localauth)/$1 -localauth/' /usr/sbin/afs-newcell

Let's run afs-newcell: 

sudo afs-newcell

                            Prerequisites

In order to set up a new AFS cell, you must meet the following:

1) .....

2) .....

3) .....

4) .....

5) .....

Do you meet these requirements? [y/n] y

If the fileserver is not running, this may hang for 30 seconds.
/etc/init.d/openafs-fileserver stop

What administrative principal should be used? root/admin

/etc/openafs/server/CellServDB already exists, renaming to .old
/etc/init.d/openafs-fileserver start
Starting OpenAFS BOS server: bosserver.
bos adduser afs.spinlock.hr root -localauth

Creating initial protection database.  This will print some errors
about an id already existing and a bad ubik magic.  These errors can
be safely ignored.

pt_util: /var/lib/openafs/db/prdb.DB0: Bad UBIK_MAGIC. Is 0 should be 354545
Ubik Version is: 2.0

bos create afs1.spinlock.hr ptserver simple /usr/lib/openafs/ptserver -localauth
bos create afs1.spinlock.hr vlserver simple /usr/lib/openafs/vlserver -localauth
bos create afs1.spinlock.hr fs fs -cmd '/usr/lib/openafs/fileserver -p 23 -busyat 600 \
  -rxpck 400 -s 1200 -l 1200 -cb 65535 -b 240 -vc 1200' -cmd /usr/lib/openafs/volserver \
  -cmd /usr/lib/openafs/salvager -localauth
bos setrestart afs1.spinlock.hr -time never -general -localauth
Waiting for database elections: done.
vos create afs1.spinlock.hr a root.afs -localauth
Volume 536870915 created on partition /vicepa of afs.spinlock.hr
/etc/init.d/openafs-client force-start
Starting AFS services: afsd.
afsd: All AFS daemons started.

Now, get tokens as root in the spinlock.hr cell.
Then, run afs-rootvol.

Now that our AFS cell is created, remember we've said volumes are the basic units accessible by AFS clients. By convention, each AFS cell creates the first volume called root.afs.

So according to the advice printed at the end of afs-newcell run, we need to obtain the AFS administrator token and then run afs-rootvol: 

kinit root/admin; aklog

Password for root/admin@SPINLOCK.HR: PASSWORD

afs-rootvol

                            Prerequisites

In order to set up the root.afs volume, you must meet the following
pre-conditions:

1) .....

2) .....

3) .....

4) The AFS client must be running pointed at the new cell.
Do you meet these conditions? (y/n) y

You will need to select a server (hostname) and AFS partition on which to
create the root volumes.

What AFS Server should volumes be placed on? afs1
What partition? [a] a

vos create afs1 a root.cell -localauth
Volume 536870918 created on partition /vicepa of afs1
fs sa /afs system:anyuser rl
fs mkm /afs/spinlock.hr root.cell -cell spinlock.hr -fast || true
fs mkm /afs/grand.central.org root.cell -cell grand.central.org -fast || true
.....
.....
.....
.....
.....
fs sa /afs/spinlock.hr system:anyuser rl
fs mkm /afs/.spinlock.hr root.cell -cell spinlock.hr -rw
fs mkm /afs/.root.afs root.afs -rw
vos create afs1 a user -localauth
Volume 536870921 created on partition /vicepa of afs1
fs mkm /afs/spinlock.hr/user user 
fs sa /afs/spinlock.hr/user system:anyuser rl
vos create afs1 a service -localauth
Volume 536870924 created on partition /vicepa of afs1
fs mkm /afs/spinlock.hr/service service 
fs sa /afs/spinlock.hr/service system:anyuser rl
ln -s spinlock.hr /afs/spinlock
ln -s .spinlock.hr /afs/.spinlock
vos addsite afs1 a root.afs -localauth
Added replication site afs /vicepa for volume root.afs1
vos addsite afs1 a root.cell -localauth
Added replication site afs1 /vicepa for volume root.cell
vos release root.afs -localauth
Released volume root.afs successfully
vos release root.cell -localauth
Released volume root.cell successfully

Woohoo! You've got yourself one helluva OpenAFS cell.

Post-configuration

If you remember, during the AFS installation phase, we've answered "No" to the question "Run OpenAFS client now and at boot?". AFS init script is such that it just won't run the client as long as the client startup is disabled in the config file — even if you invoke sudo invoke-rc.d openafs-client start manually. Therefore, we now have to enable the client in /etc/openafs/afs.conf.client by replacing AFS_CLIENT=false with AFS_CLIENT=true: 

sudo perl -pi -e's/AFS_CLIENT=false/AFS_CLIENT=true/' /etc/openafs/afs.conf.client
sudo invoke-rc.d openafs-client start

Finally, let's drop any tokens or tickets that we may have initialized, to continue with a clean slate: 

unlog; kdestroy

All set. You should now have the basic AFS environment working.

Accessing the files

While the whole point of AFS is in accessing files remotely, remember that all AFS servers are also regular AFS clients. So let's explain the AFS directory structure a bit and then use our just-installed server to look at the actual contents of the /afs/ directory.

As we've hinted in the section called “Introduction”, AFS uses a global namespace. That means all AFS sites are instantly accessible from /afs/ as if they were local directories, and all files have a unique AFS path. For example, file /afs/spinlock.hr/service/test will always be /afs/spinlock.hr/service/test, no matter the client, operating system, local policy or geographical location.

In order to avoid clashes in this global AFS namespace, by convention, each cell's "AFS root" starts in /afs/domain.name/.

Basic listing and information

Let's list /afs/ directory contents to verify what we've just said about AFS cells and their mount points: 

cd /afs

ls | head
1ts.org
acm-csuf.org
acm.uiuc.edu
ams.cern.ch
andrew.cmu.edu
anl.gov
asu.edu
athena.mit.edu
atlass01.physik.uni-bonn.de
atlas.umich.edu

ls | wc -l

189

The 189 directories were automatically created by the afs-rootvol script, but you can create additional and remove existing mount points (AFS mount points) at will.

With the above said, we can predict AFS has created our own directory in /afs/spinlock.hr/. This directory is only visible automatically within the local cell and is not seen by the world in ls /afs listing.

Now that we're in AFS land, we can quickly get some more AFS-specific information on /afs/spinlock.hr/: 

fs lsm /afs/spinlock.hr

'/afs/spinlock.hr' is a mount point for volume '#spinlock.hr:root.cell'

fs lv /afs/spinlock.hr

File /afs/spinlock.hr (536870919.1.1) contained in volume 536870919
Volume status for vid = 536870919 named root.cell.readonly
Current disk quota is 5000
Current blocks used are 4
The partition has 89573 blocks available out of 94030

Read and write paths, replication

Each time you mount a volume, you can mount it read-write or read-only.

Read-write mounts are simple — reads and writes are done through the same filesystem path, such as /afs/spinlock.hr/common/testfile, and are serviced by the volume's host server.

Read-only mounts make things interesting — volumes may have up to 8 read-only replicas and clients will retrieve files from the "best" source. However, that brings two specifics:
First, as the read-only mount is read-only by definition, there exists a different file path (prefixed with a dot) for accessing the data in a read-write fashion.
Second, data changes in the read-write tree don't show up in the read-only tree until you "release" volume contents with the vos release command.

As said, read-write paths for read-only mounts are prefixed by a leading dot. Let's verify this: 

lsm /afs/spinlock.hr

'/afs/spinlock.hr' is a mount point for volume '#spinlock.hr:root.cell'

lsm /afs/.spinlock.hr

'/afs/.spinlock.hr' is a mount point for volume '%spinlock.hr:root.cell'

Reading and writing

Equipped with the above absolute basics, let's visit /afs/spinlock.hr/, look around, and then try to read and write files. 

cd /afs/spinlock.hr

ls -al

total 14
drwxrwxrwx 2 root root 2048 2008-06-25 02:05 .
drwxrwxrwx 2 root root 8192 2008-06-25 02:05 ..
drwxrwxrwx 2 root root 2048 2008-06-25 02:05 service
drwxrwxrwx 2 root root 2048 2008-06-25 02:05 user

echo TEST > testfile

-bash: testfile: Read-only file system

cd ../.spinlock.hr

echo TEST > testfile

-bash: testfile: Permission denied

Good. Let's list access permissions (AFS ACL) for the directory, and then obtain AFS admin privileges that will allow us to write files. Note that we first establish our Kerberos identity using kinit, and then obtain the matching AFS token using aklog. Aklog obtains a token automatically and without further prompts, on the basis of the existing Kerberos ticket. 

cd /afs/.spinlock.hr

fs la .

Access list for . is
Normal rights:
  system:administrators rlidwka
  system:anyuser rl

kinit root/admin; aklog

Password for root/admin@SPINLOCK.HR: PASSWORD

klist -5

Ticket cache: FILE:/tmp/krb5cc_0
Default principal: root/admin@SPINLOCK.HR

Valid starting     Expires            Service principal
06/29/08 19:38:05  06/30/08 05:38:05  krbtgt/SPINLOCK.HR@SPINLOCK.HR
        renew until 06/30/08 19:38:05
06/29/08 19:38:12  06/30/08 05:38:05  afs@SPINLOCK.HR
        renew until 06/30/08 19:38:05

tokens

Tokens held by the Cache Manager:

User's (AFS ID 1) tokens for afs@spinlock.hr [Expires Jun 30 05:38]
   --End of list--

At this point, writing the file succeeds: 


echo TEST > testfile

cat testfile

TEST

Let's list volume data size quota and increase it from the default 5 MB to 100 MB: 

fs lq

Volume Name                   Quota      Used %Used   Partition
root.cell                      5000        28    1%         38% 

fs sq . 100000

fs lq

Volume Name                   Quota      Used %Used   Partition
root.cell.readonly           100000        28    1%         38%

Creating users

As seen in the previous chapter, you authenticate to Kerberos using kinit and then to AFS using aklog.

We're dealing with two separate authentication databases here — the Kerberos database and the AFS "Protection Database" or PTS.

That means all users have to exist in both Kerberos and AFS if they want to access AFS data space in an authenticated fashion. The only reason we did not have to add root/admin user to AFS PTS is because this was done automatically by the virtue of afs-newcell.

So let's add a regular AFS user. We're going to add user "mirko", which should already exist in Kerberos if you've followed the MIT Kerberos 5 Guide, section "Creating first unprivileged principal". Make sure you hold the administrator Kerberos ticket and AFS token, and then execute: 

pts createuser mirko 20000

User mirko has id 20000

You will notice that Kerberos and AFS do not require any use of sudo. (Actually, we do use sudo to invoke Kerberos' sudo kadmin.local, but that's only because we want to access the local Kerberos database directly on a file level). Kerberos and AFS privileges are determined solely by tickets and tokens one has obtained, and have nothing to do with traditional Unix privileges nor are tied to certain usernames or IDs.

Creating and mounting volumes

Now that we have a regular user "mirko" created in both Kerberos and AFS, we want to create an AFS data volume that will correspond to this user and be "mounted" in the location of the user's home directory in AFS.

Make sure you still hold the administrator Kerberos ticket and AFS token, and then execute: 

vos create afs1 a user.mirko 200000

Volume 536997357 created on partition /vicepa of afs1

vos examine user.mirko

user.mirko                        536997357 RW          2 K  On-line
    afs1.spinlock.hr /vicepa 
    RWrite  536997357 ROnly          0 Backup          0 
    MaxQuota     200000 K 
    Creation    Sun Jun 29 18:06:43 2008
    Copy        Sun Jun 29 18:06:43 2008
    Backup      Never
    Last Update Never

    RWrite: 536997357
    number of sites -> 1
       server afs1.spinlock.hr partition /vicepa RW Site

Having the volume, let's mount it to a proper location. We will use a "hashed" directory structure with two sublevels, so that the person's home directory will be in /afs/spinlock.hr/user/p/pe/person/ (instead of directly in user/person/). Follow this AFS convention and you will be able to use libnss-afs and 3rd party management scripts without modification. 

cd /afs/spinlock.hr/user

mkdir -p m/mi

fs mkm m/mi/mirko user.mirko -rw

Let's view volume and directory information: 

fs lsm m/mi/mirko

'm/mi/mirko' is a mount point for volume '#user.mirko'

fs lv m/mi/mirko

File m/mi/mirko (536997357.1.1) contained in volume 536997357
Volume status for vid = 536997357 named user.mirko
Current disk quota is 200000
Current blocks used are 2
The partition has 85448567 blocks available out of 140861236

Setting permissions

Let's view the permissions on the new directory and allow user full access: 

fs la m/mi/mirko

Access list for m/mi/mirko is
Normal rights:
  system:administrators rlidwka

fs sa  m/mi/mirko mirko all

fs la !:2

Access list for m/mi/mirko is
Normal rights:
  system:administrators rlidwka
  mirko rlidwka

Now switch to user mirko and verify you've got access to the designated home directory: 

unlog; kdestroy

kinit mirko; aklog

Password for mirko@SPINLOCK.HR: PASSWORD

cd /afs/spinlock.hr/user/m/mi/mirko

echo IT WORKS > test

cat test

IT WORKS

Serving metadata

The material covered so far in the MIT Kerberos 5 Guide and this OpenAFS Guide has gotten us to a point where we can create users in Kerberos and AFS, create and mount users' data volumes, authenticate using kinit and aklog, and read and write files in the users' volumes with full permissions.

In other words, it smells as if we're a step away from our goal — a true networked and secure solution for centralized logins with exported home directories.

There's one final thing missing, and it's the support for serving user "metadata". As explained in the section called “Introduction”, metadata will come from either LDAP or libnss-afs.

If you've followed and implemented the setup described in the OpenLDAP Guide, you already have the metadata taken care of. However, let's say a few words about it anyway to broaden our horizons.

Metadata is the information traditionally found in system files /etc/passwd, /etc/group and /etc/shadow.

Metadata necessary for a successful user login includes four elements: Unix user ID, Unix group ID, home directory and shell.

Let's take a look at a complete list of user metadata, with a list of software components that handle them in parentheses:

You may notice LDAP seems like a "superset" of libnss-afs. And it really is, which can be an advantage or a disadvantage, depending on the situation.

LDAP is a standalone solution that can be used to create network infrastructures based on the "magic trio" — Kerberos, LDAP and AFS. It is flexible and can serve arbitrary user and system information besides the necessary metadata. Can you think of a few examples how this would be useful? For example, on a lower level, you could use LDAP to store extra group membership information or per-user host access information; on a higher level, you could use LDAP to store a person's image, birth date, or a shared calendar available to all user applications. However, this flexibility comes at a cost of administering yet another separate database (Kerberos, AFS and LDAP all have their own database, and you have to keep them synchronized).

libnss-afs, on the other hand, is an AFS-dependent module that serves the metadata out of the AFS PTS database. It is simple, and limited. Structure of the PTS is such that you can only save certain information in there, and nothing else. For fields that cannot be represented in PTS, libnss-afs outputs a "one size fits all" default value. For example, as there is no space for GECOS information in the PTS, everyone's GECOS is set to their username; as there is no group ID, everyone's group ID is set to group 65534 (nogroup), and as there is no home directory, everyone's homedir is set to /afs/cell.name/user/u/us/user/. libnss-afs may suit those who prefer simplified administration over flexibility.

In this Guide, both LDAP and libnss-afs approach will be explained. Moving from libnss-afs to LDAP is easy, so if in doubt, pick libnss-afs.

LDAP

A complete LDAP setup is explained in another article from the series, the OpenLDAP Guide. If you have followed and implemented the procedure, especially the part about modifying /etc/nsswitch.conf, there's only one thing that should be done here — you should modify users' entries in LDAP to make their home directories point to AFS instead of to /home/.

Actually, you can symlink /home/ to AFS, and then no change in LDAP will be necessary. One benefit of this approach is that /home/ looks familiar to everyone. One drawback is that you need to symlink that directory to AFS on all machines where users will be logging in.

To create the symlinks, use: 

sudo mv /home /home,old
sudo ln -sf /afs/.spinlock.hr/user /home
sudo ln -sf /afs/spinlock.hr/user /rhome

To literally change users' home directories in LDAP (to point to /afs/spinlock.hr/user/u/us/user/), construct a LDIF file and use ldapmodify to apply the LDIF file.

Here's an example for user mirko (which should already exist in your LDAP directory if you've followed the OpenLDAP Guide Guide). Save the following as /tmp/homechange.ldif: 

dn: uid=mirko,ou=people,dc=spinlock,dc=hr
changetype: modify
replace: homeDirectory
homeDirectory: /afs/spinlock.hr/user/m/mi/mirko

And apply using: 

ldapmodify -c -x -D cn=admin,dc=spinlock,dc=hr -W -f /tmp/homechange.ldif

libnss-afs

As said, libnss-afs is an AFS-dependent approach to serving metadata, so it only makes sense to describe it in the context of the OpenAFS Guide.

Adam Megacz created libnss-afs on the basis of Frank Burkhardt's libnss-ptdb, which in turn was created on the basis of Todd M. Lewis' nss_pts. The primary motivation for libnss-afs has been the use at HCoop, the first non-profit corporation offering public AFS hosting and accounts.

Good. Let's move onto the technical setup:

It is strongly recommended to run libnss-afs in combination with nscd and cache the replies from the AFS ptserver, so let's install nscd first and change one of its config options to work around a known bug in nscd: 

sudo apt-get install nscd

sudo perl -pi -e '/^\s*enable-cache\s+hosts\s+yes\s*/ and $_ = "enable-cache hosts no\n"' /etc/nscd.conf

sudo invoke-rc.d nscd restart

Now let's install libnss-afs itself, which is — interestingly enough — accessible in AFS, in the cell hcoop.net. You should have a working AFS client by now to access the files.

What we've covered so far should be enough to allow you understand what will be going on in the following transcript. In short, we will need to create /afs/hcoop.net/ before we can access the files in the cell, and the procedure will be a bit longer then normal mount because our AFS root is read-only. In any case, our goal here is just accessing the libnss-afs repository, so copy-paste our working example don't spend too much time deciphering the procedure. 

unlog; kdestroy

kinit root/admin; aklog

Password for root/admin@SPINLOCK.HR: PASSWORD

sudo sh -c 'echo -e ">hcoop.net\n69.90.123.67 # deleuze.hcoop.net" >> /etc/openafs/CellServDB'

cd /afs/spinlock.hr/service

fs mkm tmp root.afs -rw

cd tmp

fs mkm hcoop.net root.cell -cell hcoop.net -fast

cd ..

vos release root.cell

fs rmm tmp

Now /afs/hcoop.net/ will exist and we can access the libnss-afs package: 

cd /afs/hcoop.net/user/m/me/megacz/public/libnss-afs

sudo dpkg -i libnss-afs*deb

The directory contains libnss-afs sources as well. In case you need to recompile them and build Debian packages yourself, here's a guideline: 

cp -a /afs/hcoop.net/user/m/me/megacz/public/libnss-afs/libnss-afs /tmp

cd /tmp/libnss-afs

dpkg-buildpackage -uc -us

sudo dpkg -i ../libnss-afs*deb

After libnss-afs is installed, let's modify the existing lines in /etc/nsswitch.conf to look like the following: 

passwd:  afs files
group:   afs files
shadow:  files

Metadata test

We are ready to test metadata retrieval: 

sudo nscd -i passwd

id mirko

uid=20000(mirko) gid=65534(nogroup) groups=65534(nogroup)

getent passwd mirko

mirko:x:20000:65534:docelic:/afs/hcoop.net/user/m/mi/mirko:/bin/bash

PAM configuration

The final step in this article pertains to integrating OpenAFS into the system authentication procedure. We want Kerberos ticket and OpenAFS token to be issued for users as they log in, without the need to run kinit and aklog manually after login.

Let's install the necessary OpenAFS PAM module: 

sudo apt-get install libpam-afs-session

Let's configure Linux-PAM. PAM configuration is quite fragile, so use the provided examples that have been verified to work. For any modifications, you will want to look at PAM Configuration File Syntax and pay special attention to seemingly insignificant variations — with PAM, they often make a whole world of difference.

To minimize the chance of locking yourself out of the system during PAM configuration phase, ensure right now that you have at least one root terminal window open and a copy of the files available before starting on PAM configuration changes. To do so, execute the following in a cleanly started shell and leave the terminal open: 

sudo su -
cd /etc
cp -a pam.d pam.d,orig

Note

If you break logins with an invalid PAM configuration, the above will allow you to simply revert to a known-good state by using the open root terminal and executing: 

cp -a pam.d,orig/* pam.d/

After you've edited your PAM configuration as shown below, restart the services you will be connecting to. This isn't strictly necessary, but it ensures that the services will re-read the PAM configuration and not use any cached information.

/etc/pam.d/common-auth

auth    sufficient        pam_unix.so nullok_secure
auth    sufficient        pam_krb5.so use_first_pass
auth    optional          pam_afs_session.so program=/usr/bin/aklog
auth    required          pam_deny.so

/etc/pam.d/common-session

session required pam_limits.so
session optional pam_krb5.so
session optional pam_unix.so
session optional pam_afs_session.so program=/usr/bin/aklog

Conclusion

At this point, you have a functional AFS site. Users, once created in the system, can log in and access their files anywhere on the network.

You can rely on either system login or manually running kinit; aklog in obtaining Kerberos ticket and AFS token.

Once the token is obtained, you can access the protected AFS data space.

Note that you've just started with OpenAFS. With a good foundation we've built, you're advised to expand your knowledge using other available resources.

The newest version of this article can always be found at http://techpubs.spinlocksolutions.com/dklar/afs.html.

Davor Ocelic
http://www.spinlocksolutions.com/


Copyright (C) 2008 Davor Ocelic, <docelic@spinlocksolutions.com>
Spinlock Solutions, http://www.spinlocksolutions.com/

This documentation is free; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

This article can be found online at the Debian Administration website at the following bookmarkable URL (along with associated comments):

This article is copyright 2008 docelic - please ask for permission to republish or translate.