Getting Started on Linux Systems

Getting Started on Linux Systems
	Chapter 2. Installing the First AFS Machine

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.

Loading AFS into the Linux Kernel

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

Fedora and RedHat Enterprise Linux

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.

Browse to http://dl.openafs.org/dl/openafs/VERSION, where VERSION is the latest stable release of OpenAFS for Unix. Download the openafs-repository-VERSION.noarch.rpm file for Fedora systems or the openafs-repository-rhel-VERSION.noarch.rpm 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
              
```

Debian and Ubuntu Linux

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 afs-newcell and afs-rootvol, which can automate much of the remainder of this document.

Systems built from source

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.o, where version indicates the kernel build level. The string .mp in the version indicates that the file is appropriate for machines running a multiprocessor kernel.
```
   # 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
```

Configuring Server Partitions on Linux Systems

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 /vicepxx, where xx is one or two lowercase letters. The /vicepxx 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 /vicepxx for each AFS server partition you are configuring (there must be at least one). Repeat the command for each partition.
```
   # mkdir /vicepxx
```
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.
```
   /dev/disk  /vicepxx  ext2  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 /vicepxx directory. The following command is probably appropriate, but consult the Linux documentation for more information.
```
   # mkfs -v /dev/disk
```
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 retain client functionality on this machine after completing the installation, proceed to Enabling AFS Login on Linux Systems. Otherwise, proceed to Starting the BOS Server.

Enabling AFS Login on Linux Systems

Note

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:

Example 2.1. Linux PAM session example

session required pam_afs_session.so

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 sufficient.

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 to use default=die instead.

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 /etc/pam.d/common-session and /etc/pam.d/common-auth.

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.

Proceed to Starting the BOS Server (or if referring to these instructions while installing an additional file server machine, return to Starting Server Programs).


Performing Platform-Specific Procedures		Getting Started on Solaris Systems