Since this guide was originally written, the procedure for starting OpenAFS has diverged significantly between different Linux distributions. The instructions that follow are appropriate for both the Fedora and RedHat Enterprise Linux packages distributed by OpenAFS. Additional instructions are provided for those building from source.
Begin by running the AFS client startup scripts, which call the modprobe program to dynamically load the AFS modifications into the kernel. Then create partitions for storing AFS volumes. You do not need to replace the Linux fsck program. If the machine is to remain an AFS client machine, incorporate AFS into the machine's Pluggable Authentication Module (PAM) scheme.
The modprobe program is the dynamic kernel loader for Linux. Linux does not support incorporation of AFS modifications during a kernel build.
For AFS to function correctly, the modprobe program must run each time the machine reboots, so your distribution's AFS initialization script invokes it automatically. The script also includes commands that select the appropriate AFS library file automatically. In this section you run the script.
In later sections you verify that the script correctly initializes all AFS components, then activate a configuration variable, which results in the script being incorporated into the Linux startup and shutdown sequence.
The procedure for starting up OpenAFS depends upon your distribution
OpenAFS provides RPMS for all current Fedora and RedHat Enterprise Linux (RHEL) releases prior to EL7 on the OpenAFS web site and the OpenAFS yum repository.
where VERSION is the latest stable release of
OpenAFS for Unix. Download the
file for Fedora systems or the
file for RedHat-based systems.
Install the downloaded RPM file using the following command:
# rpm -U openafs-repository*.rpm
Install the RPM set for your operating system using the yum command as follows:
# yum -y install openafs-client openafs-server openafs-krb5 kmod-openafs
Alternatively, you may use dynamically-compiled kernel modules if you have the kernel headers, a compiler, and the dkms package from EPEL installed.
To use dynamically-compiled kernel modules instead of statically compiled modules, use the following command instead of the kmod-openafs as shown above:
# yum install openafs-client openafs-server openafs-krb5 dkms-openafs
OpenAFS is available as binary packages from the Debian linux distribution and its derivatives such as Ubuntu.
Install the client and server packages using the following command:
# apt-get install openafs-client openafs-modules-dkms openafs-krb5 \ openafs-fileserver openafs-dbserver
You will be prompted by debconf to select your cell name and the size of your local cache.
The Debian package also includes helper scripts
which can automate much of the remainder of this document.
If you are running a system where you have built the system from source yourself, you need to install the relevant components by hand:
Unpack the distribution tarball. The examples below assume that you have extracted and built OpenAFS in the /tmp/afsdist directory. If you pick a different location, substitute this in all of the following examples. Once you have compiled the distribution, change to the source directory as indicated.
# cd /tmp/afsdist
Copy the AFS kernel library files to the local /usr/vice/etc/modload directory.
The filenames for the libraries have the format libafs-
version indicates the kernel build level. The string .mp in
version indicates that the file is appropriate for machines running a multiprocessor
# mkdir -p /usr/vice/etc/modload # cp -rp src/libafs/*.ko /usr/vice/etc/modload
Copy the AFS initialization script to the local directory for initialization files (by convention, /etc/rc.d/init.d on Linux machines). Note the removal of the .rc extension as you copy the script.
# cp -p src/afsd/afs.rc.linux /etc/rc.d/init.d/afs
Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
server partition is mounted at a directory named /vicep
xx is one or two lowercase letters. The /vicep
xx directories must reside in the file server machine's root
directory, not in one of its subdirectories (for example, /usr/vicepa is not an acceptable
directory location). For additional information, see Performing Platform-Specific Procedures.
Create a directory called /vicep
xx for each AFS server
partition you are configuring (there must be at least one). Repeat the command for each partition.
# mkdir /vicep
Add a line with the following format to the file systems registry file, /etc/fstab, for each directory just created. The entry maps the directory name to the disk partition to be mounted on it.
xxext2 defaults 0 2
The following is an example for the first partition being configured.
/dev/sda8 /vicepa ext2 defaults 0 2
Create a file system on each partition that is to be mounted at a /vicep
xx directory. The following command is probably appropriate, but
consult the Linux documentation for more information.
# mkfs -v /dev/
Mount each partition by issuing either the mount -a command to mount all partitions at once or the mount command to mount each partition in turn.
If you plan to remove client functionality from this machine after completing the installation, skip this section and proceed to Starting the BOS Server.
At this point you incorporate AFS into the operating system's Pluggable Authentication Module (PAM) scheme. PAM integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for authenticated access to and from the machine.
You should first configure your system to obtain Kerberos v5 tickets as part of the authentication process, and then run an AFS PAM module to obtain tokens from those tickets after authentication. Many Linux distributions come with a Kerberos v5 PAM module (usually called pam-krb5 or pam_krb5), or you can download and install Russ Allbery's Kerberos v5 PAM module, which is tested regularly with AFS. See the instructions of whatever PAM module you use for how to configure it.
Some Kerberos v5 PAM modules do come with native AFS support (usually requiring the Heimdal Kerberos implementation rather than the MIT Kerberos implementation). If you are using one of those PAM modules, you can configure it to obtain AFS tokens. It's more common, however, to separate the AFS token acquisition into a separate PAM module.
The recommended AFS PAM module is Russ Allbery's pam-afs-session module. It should work with any of the Kerberos v5 PAM modules. To add it to the PAM configuration, you often only need to add configuration to the session group:
If you also want to obtain AFS tokens for scp
and similar commands that don't open a session, you will also need to
add the AFS PAM module to the auth group so that the PAM
setcred call will obtain tokens. The
pam_afs_session module will always return success
for authentication so that it can be added to the auth group only for
setcred, so make sure that it's not marked as
Example 2.2. Linux PAM auth example
auth [success=ok default=1] pam_krb5.so
auth [default=done] pam_afs_session.so
auth required pam_unix.so try_first_pass
This example will work if you want to try Kerberos v5 first and
then fall back to regular Unix authentication.
success=ok for the Kerberos PAM module followed by
default=done for the AFS PAM module will cause a
successful Kerberos login to run the AFS PAM module and then skip the
Unix authentication module.
default=1 on the
Kerberos PAM module causes failure of that module to skip the next
module (the AFS PAM module) and fall back to the Unix module. If you
want to try Unix authentication first and rearrange the order, be sure
The PAM configuration is stored in different places in different
Linux distributions. On Red Hat, look in
/etc/pam.d/system-auth. On Debian and
derivatives, look in
For additional configuration examples and the configuration options of the AFS PAM module, see its documentation. For more details on the available options for the PAM configuration, see the Linux PAM documentation.
Sites which still require the deprecated kaserver or external Kerberos v4 authentication should consult Enabling kaserver based AFS Login on Linux Systems for details of how to enable AFS login on Linux.