Kerberos-OpenAFS client

Here, MIT Kerberos V and OpenAFS client software is installed on a host running Debian 5.0 (lenny). If followed properly, this step-by-step process should produce a new client that will authenticate to either of two previously installed Kerberos-OpenAFS servers: kas1.example.com, or kas2.example.com. At a minimum, the former will be required for the installation process. The system also relies heavily on timestamps, so reasonably accurate time synchronization among all participating hosts is essential.

To be sure, Kerberos only provides encryption and a method for secure storage of, and access to, pairs of names and passwords, referred to as principals; it does not store other critical Unix-style account information. In this case, AFS is used to store the rest of the meta-data; it does a reasonable job, although with limitation (no GID data). A more efficient solution is to use OpenLDAP for this purpose, but that will be the subject of another set of articles. The interesting part is that the user's home directory will reside on an AFS volume and be cached locally for speed.

Before the actual Kerberos and OpenAFS installation process can begin, it will first be necessary to install Debian lenny on a new client host, called kac1.example.com. A DNS server must also be available on the network with a zone file to which forward and reverse mappings can be added for this host. After the initial installation of the operating system has been completed for each host, make sure these packages are installed as well:

~# apt-get install ssh ntp ntpdate nmap

After that, on both systems, edit /etc/ntp.conf so that the client synchronizes to a common NTP server (preferably a local one) and edit /etc/default/ntpdate to use the same NTP server also. Now the installation process for the Kerberos-OpenAFS client can begin:

On both of the new client machines, start by installing these three packages:

~# apt-get install krb5-{config,user} libpam-krb5

A total of four packages are installed as a result, including one dependency:

krb5-config              1.22                         Configuration files for Kerberos Version 5
krb5-user                1.6.dfsg.4~beta1-5lenny1     Basic programs to authenticate using MIT Kerberos
libkadm55                1.6.dfsg.4~beta1-5lenny1     MIT Kerberos administration runtime libraries
libpam-krb5              3.11-4                       PAM module for MIT Kerberos

During the installation, the krb5-config package will automatically have the default realm set to EXAMPLE.COM, but a few questions have to be answered for it as well:

Kerberos servers for your realm: kas1.example.com kas2.example.com 
Administrative server for your Kerberos realm: kas.example.com

These settings, along with the default realm, are saved in /etc/krb5.conf.

Regarding the set of servers used for the realm, it is recommended that a predefined set of DNS hostname aliases (CNAME records) be used to refer to the realm's various KDCs (not just for the administration server). In this manner, if a KDC has to be replaced, only its DNS entry will need to be changed. This is preferable to modifying the list of KDCs in /etc/krb5.conf on every client on the network every time a KDC entry is added or changed in the DNS.

Edit the Kerberos realm configuration file, /etc/krb5.conf. This file is initially created by the Debian installer and contains information about the realms of a number of famous institutions, but none of that is necessary in this case. Instead, replace its contents with this:

[libdefaults]
        default_realm = EXAMPLE.COM
        forwardable = true
        proxiable = true

[realms]
        EXAMPLE.COM = {
                kdc = kas1.example.com
                kdc = kas2.example.com
                admin_server = kas.example.com
        }

[domain_realm]
        .example.com = EXAMPLE.COM
        example.com = EXAMPLE.COM

See this section for a more detailed explanation of this file.

Regarding the list of KDCs that are specified here, it is often recommended to use a predetermined set of DNS hostname aliases (CNAME records) to refer to the Kerberos servers on a network. However, it is also possible to omit the KDC entries in /etc/krb5.conf and instead rely on SRV DNS resource records to do the same job. See DNS discovery for MIT Kerberos V for information on how to do that.

Use kadmin to create a host principal and a local keytab file by issuing a few commands:

~# kadmin -p admin
Authenticating as principal sysadmin with password.
Password for sysadmin@EXAMPLE.COM: xanthina
kadmin:  addprinc -randkey host/kac1.example.com
WARNING: no policy specified for host/kac1.example.com@EXAMPLE.COM; 
defaulting to no policy
Principal "host/kac1.example.com@EXAMPLE.COM" created.
kadmin:  ktadd host/kac1.example.com
Entry for principal host/kac1.example.com with kvno 3, encryption type 
AES-256 CTS mode with 96-bit SHA-1 HMAC added to keytab 
WRFILE:/etc/krb5.keytab.
Entry for principal host/kac1.example.com with kvno 3, encryption type 
ArcFour with HMAC/md5 added to keytab WRFILE:/etc/krb5.keytab.
Entry for principal host/kac1.example.com with kvno 3, encryption type 
Triple DES cbc mode with HMAC/sha1 added to keytab 
WRFILE:/etc/krb5.keytab.
Entry for principal host/kac1.example.com with kvno 3, encryption type 
DES cbc mode with CRC-32 added to keytab WRFILE:/etc/krb5.keytab.
kadmin:  q
~# _

The -randkey switch is used because a machine cannot enter a password. By default, Kerberos saves its keys in /etc/krb5.keytab. To list the keys in this file, use the klist -ke command. A host principal and keytab file should be created for and saved on all of the various client machines that are part of a Kerberos realm.

At this point it would be necessary to build and install the OpenAFS kernel module from source. If kac1 were to require a Linux kernel that is different from the one used on kas1, then there would be no choice but to do that. However, to avoid repetition, it is assumed that the kernel used here is the same, which allows time to be saved by using the already compiled package from that system on this one. So, simply copy the package from kas1:

~# scp kas1:/usr/src/openafs-modules*.deb /usr/src/

Following that, install it:

~# dpkg -i /usr/src/openafs-modules*.deb

After that, test the OpenAFS kernel module by loading it:

~# modprobe openafs

Again, this it what it looks like when the module has been loaded:

~# lsmod |grep afs
openafs               473948  0 
~#

From this point on, a more detailed level of questioning will be required from debconf. To achieve this, run the following command:

~# dpkg-reconfigure debconf

Answer the questions as follows:

Interface to use: Dialog
Ignore questions with a priority less than: low

Install the OpenAFS client. Now install these two packages:

~# apt-get install openafs-{client,krb5}

Only these two packages are installed as a result:

openafs-client                1.4.7.dfsg1-6+lenny2     AFS distributed filesystem client support
openafs-krb5                  1.4.7.dfsg1-6+lenny2     AFS distributed filesystem Kerberos 5 integration

Following the installation process, debconf will ask a few questions regarding the openafs-client package. Answer them as follows:

AFS cell this workstation belongs to: example.com
Size of AFS cache in kB: 50000
Run Openafs client now and at boot? Yes
Look up AFS cells in DNS? Yes
Encrypt authenticated traffic with AFS fileserver? No
Dynamically generate the contents of /afs? Yes
Use fakestat to avoid hangs when listing /afs? Yes
DB server host names for your home cell: kas1 kas2

Regarding the AFS cache, the default size is about 50 MB and is located in the /var/cache/openafs/ directory. Often, the cache is increased to around 512 MB, but usually less than 1 GB; larger cache sizes may lengthen the startup time, as all files within the cache must be prechecked with the servers. It is vital that OpenAFS is never in danger of running out of cache space, since it is not designed to handle such situations gracefully. A requirement is also that an ext2 or ext3 file system is used for the cache directory; a file containing such a file system, or a dedicated partition can be used for this purpose, but its even possible to use a memory-based cache, which offers signifigant performance benefits.

Regarding the list of AFS DB server host names that are specified here, one strategy to manage large numbers of client machines would be to use a predetermined set of DNS hostname aliases (CNAME records) to refer to the AFS DB servers on a network. However, it is also possible to omit the AFS DB entries and instead rely on SRV DNS resource records to do the same job. See DNS discovery for OpenAFS for information on how to do that.

Start by installing the Name Service Cache Daemon:

~# apt-get install nscd

This is the only package that gets installed as a result:

nscd                          2.7-18lenny2             GNU C Library: Name Service Cache Daemon

Edit /etc/nscd.conf, locate each of the following three lines and modify them as follows:

        persistent              passwd          no

        persistent              group           no

        persistent              hosts           no

The next task is install a package, called libnss-afs, which must be compiled in advance. To be able to do that, these packages must be installed first:

~# apt-get install dpkg-dev debhelper

A total of 43 packages are installed as a result, including 41 dependencies:

binutils                      2.18.1~cvs20080103-7     The GNU assembler, linker and binary utilities
build-essential               11.4                     Informational list of build-essential packages
bzip2                         1.0.5-1                  high-quality block-sorting file compressor - utilities
cpp-4.3                       4.3.2-1.1                The GNU C preprocessor
cpp                           4:4.3.2-2                The GNU C preprocessor (cpp)
debhelper                     7.0.15                   helper programs for debian/rules
dpkg-dev                      1.14.28                  Debian package development tools
g++-4.3                       4.3.2-1.1                The GNU C++ compiler
g++                           4:4.3.2-2                The GNU C++ compiler
gcc-4.2-base                  4.2.4-6                  The GNU Compiler Collection (base package)
gcc-4.3                       4.3.2-1.1                The GNU C compiler
gcc-4.3-base                  4.3.2-1.1                The GNU Compiler Collection (base package)
gcc                           4:4.3.2-2                The GNU C compiler
gettext                       0.17-4                   GNU Internationalization utilities
gettext-base                  0.17-4                   GNU Internationalization utilities for the base system
html2text                     1.3.2a-5                 advanced HTML to text converter
intltool-debian               0.35.0+20060710.1        Help i18n of RFC822 compliant config files
libc6-dev                     2.7-18lenny2             GNU C Library: Development Libraries and Header Files
libcompress-raw-zlib-perl     2.012-1lenny1            low-level interface to zlib compression library
libcompress-zlib-perl         2.012-1                  Perl module for creation and manipulation of gzip files
libdigest-hmac-perl           1.01-7                   create standard message integrity checks
libdigest-sha1-perl           2.11-2+b1                NIST SHA-1 message digest algorithm
libfile-remove-perl           1.42-1                   remove files and directories, accepts wildcards
libgmp3c2                     2:4.2.2+dfsg-3           Multiprecision arithmetic library
libgomp1                      4.3.2-1.1                GCC OpenMP (GOMP) support library
libio-compress-base-perl      2.012-1                  Base Class for IO::Compress modules
libio-compress-zlib-perl      2.012-1                  Perl interface to zlib
libio-stringy-perl            2.110-4                  Perl modules for IO from scalars and arrays
libmail-box-perl              2.082-2                  Manage a message-folder
libmail-sendmail-perl         0.79-5                   Send email from a perl script
libmailtools-perl             2.03-1                   Manipulate email in perl programs
libmime-types-perl            1.24-1                   Perl extension for determining MIME types and Transfer Encodin
libmpfr1ldbl                  2.3.1.dfsg.1-2           multiple precision floating-point computation
libobject-realize-later-perl  0.18-1                   Delayed creation of objects
libstdc++6-4.3-dev            4.3.2-1.1                The GNU Standard C++ Library v3 (development files)
libsys-hostname-long-perl     1.4-2                    Figure out the long (fully-qualified) hostname
libtimedate-perl              1.1600-9                 Time and date functions for Perl
liburi-perl                   1.35.dfsg.1-1            Manipulates and accesses URI strings
libuser-identity-perl         0.92-2                   manages different identities/roles used by a physical person
linux-libc-dev                2.6.26-21lenny3          Linux support headers for userspace development
make                          3.81-5                   The GNU version of the "make" utility.
makedev                       2.3.1-88                 creates device files in /dev
nscd                          2.7-18lenny2             GNU C Library: Name Service Cache Daemon
po-debconf                    1.0.15                   manage translated Debconf templates files with gettext

Although none of these packages have to be configured, there is one more package that must be downloaded separately as a backport from Debian lenny: libopenafs-dev. But, instead of adding lenny backports to the host's apt configuration, just download it separately from this page. After that, install it:

~# dpkg -i libopenafs-dev_1.4.1*_i386.deb

Now a package called libnss-afs must be installed. Visit the homepage for it, download the tgz of the stable version and save it in the /usr/src directory. Unpack and compile it with:

~# cd /usr/src
~# tar -xzf libnss-afs-refs_heads_stable.tar.gz
~# cd libnss-afs
~# dpkg-buildpackage

Install the new package after it has successfully compiled:

~# dpkg -i /usr/src/libnss-afs_1.*_i386.deb

Finally, look for three lines in /etc/nsswitch.conf and modify them to look like this:

passwd:         afs files
group:          afs files
shadow:         files

Save the file and restart the Name Service Cache Daemon:

~# /etc/init.d/nscd restart

Altering the client machine's Linux-PAM configuration will make it possible for users to authenticate using either a Unix or a Kerberos password. However, as PAM is both a relatively complex subject and a recurring theme, it was decided to create a dedicated page for it. Those unfamiliar with its workings are advised to read it. Otherwise, make the modifications described below, which are followed by a few explanations.

Install the PAM modules for AFS:

~# apt-get install libpam-afs-session

Just this one package gets installed as a result:

libpam-afs-session            1.7-1                    PAM module to set up a PAG and obtain AFS tokens

Edit /etc/pam.d/common-auth and change it to:

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

Edit /etc/pam.d/common-account and change it to:

account     sufficient    pam_unix.so
account     sufficient    pam_krb5.so
account     required      pam_deny.so

Edit /etc/pam.d/common-password and change it to:

password    sufficient    pam_unix.so          nullok obscure md5
password    sufficient    pam_krb5.so          use_first_pass
password    required      pam_deny.so

Edit /etc/pam.d/common-session and change it to:

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

In this modified PAM configuration, three new modules are introduced:

In /etc/pam.d/common-auth, an argument is used for the pam_krb5.so module: use_first_pass. This forces it to use a password that was used for the previous module in the stack so that it does not prompt the user. The module will fail only if the password is absent or invalid.

Using sufficient instead of required for pam_krb5.so and pam_unix.so in the first three of these configuration files creates a situation where success is possible if only one of the two modules succeeds. However, it also means that the stack is no longer capable of producing a return status to indicate failure. To remedy this, the pam_deny.so module is added with required to the end of the stack to ensure that the entire process will still return a failure in case neither of the previous modules returns a success.

At this point it should be possible to login to kac1 as user ccolumbus (password NewWorld), e.g. with ssh or at a console. Once there, run a few tests:

~$ id ccolumbus
uid=20001(ccolumbus) gid=65534(nogroup) groups=65534(nogroup)
~$ _

The account looks normal, except that its GID is set to 65534 (nogroup). This is a limitation of the AFS PTS database: it is simply not possible to store all of the usual account information in it (a better solution is to store account information in OpenLDAP: see Integrated Kerberos-OpenLDAP-OpenAFS provider).

~$ getent passwd ccolumbus
ccolumbus:x:20001:65534:ccolumbus:/afs/example.com/user/c/cc/ccolumbus:/bin/bash
~$ _

From this it is apparent that the account's home directory is already set to its AFS mount point. With this configuration, users can login to any AFS client machine and always expect to be greeted by their own personal environment − wherever you go, there you are!

• Kerberos-OpenAFS master
• Kerberos-OpenAFS slave
• PAM configuration guide for Debian
• DNS discovery for MIT Kerberos V
• DNS discovery for OpenAFS

• Eastlake D, Panitz A. 1999. RFC2606 − Reserved Top Level DNS Names. The Internet Society. HTML at the Internet FAQ Archives.
• Kohl J, Neuman C. 1993. RFC1510 − The Kerberos Network Authentication Service (V5). HTML at the Internet FAQ Archives.
• Samar V, Schemers R. 1995. RFC 86.0 − Unified Login with Pluggable Authentication Modules (PAM). Open Software Foundation. Text at The Open Group.
• Wilkinson S. 2008. OpenAFS, FOSDEM 2008. Video (15:30 minutes) at YouTube.

• Campbell R. 1998. Managing AFS: The Andrew File System. Prentice Hall. ISBN 0-13-802729-3. 479 pp.
• Garman J. 2003. Kerberos, The Definitive Guide. O'Reilly & Associates, Inc. ISBN-13 978-0-596-00403-3. 253 pp.
• Massachusetts Institute of Technology. 1985-2007. Kerberos V5 System Administrator's Guide. HTML at the Massachusetts Institute of Technology (MIT).
• Milicchio F, Gehrke WA. 2007. Distributed Services with OpenAFS. Springer-Verlag. ISBN-13 978-3-540-36633-1. 395 pp.
• Morgan AG. 2001. Pluggable Authentication Modules (PAM). Open-PAM working group. Text at The Kernel Archives.
• Morgan AG, Kukuk T. 2010. The Linux-PAM System Administrator's Guide. HTML at The Kernel Archives..
• Ocelic D. 2006-2010. Debian GNU: Setting up MIT Kerberos 5. HTML at Spinlock Solutions.
• Ocelic D. 2006-2010. Debian GNU: Setting up OpenAFS 1.4.x. HTML at Spinlock Solutions.
• OpenAFS. 2000-2009. Documentation. HTML at OpenAFS.