Getting Started on Solaris Systems

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

Begin by running the AFS initialization script to call the modload program distributed by Sun Microsystems, which dynamically loads AFS modifications into the kernel. Then create partitions for storing AFS volumes, and install and configure the AFS-modified fsck program to run on AFS server partitions. 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 Solaris Kernel

The modload program is the dynamic kernel loader provided by Sun Microsystems for Solaris systems. Solaris does not support incorporation of AFS modifications during a kernel build.

For AFS to function correctly, the modload program must run each time the machine reboots, so the AFS initialization script (included on the AFS CD-ROM) invokes it automatically. In this section you copy the appropriate AFS library file to the location where the modload program accesses it and then run the script.

In later sections you verify that the script correctly initializes all AFS components, then create the links that incorporate AFS into the Solaris startup and shutdown sequence.

Unpack the OpenAFS Solaris distribution tarball. The examples below assume that you have unpacked the files into the /tmp/afsdist directory. If you pick a diferent location, substitute this in all of the following exmaples. Once you have unpacked the distribution, change directory as indicated.
```
   # cd  /tmp/afsdist/sun4x_56/dest/root.client/usr/vice/etc
```
Copy the AFS initialization script to the local directory for initialization files (by convention, /etc/init.d on Solaris machines). Note the removal of the .rc extension as you copy the script.
```
   # cp -p  afs.rc  /etc/init.d/afs
```
Copy the appropriate AFS kernel library file to the local file /kernel/fs/afs.
If the machine is running Solaris 11 on the x86_64 platform:
```
   # cp -p modload/libafs64.o /kernel/drv/amd64/afs
```
If the machine is running Solaris 10 on the x86_64 platform:
```
   # cp -p modload/libafs64.o /kernel/fs/amd64/afs
```
If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, its kernel supports NFS server functionality, and the nfsd process is running:
```
   # cp -p modload/libafs.o /kernel/fs/afs   
```
If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, and its kernel does not support NFS server functionality or the nfsd process is not running:
```
   # cp -p modload/libafs.nonfs.o /kernel/fs/afs   
```
If the machine is running the 64-bit version of Solaris 7, its kernel supports NFS server functionality, and the nfsd process is running:
```
   # cp -p modload/libafs64.o /kernel/fs/sparcv9/afs   
```
If the machine is running the 64-bit version of Solaris 7, and its kernel does not support NFS server functionality or the nfsd process is not running:
```
   # cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs
```
Run the AFS initialization script to load AFS modifications into the kernel. You can ignore any error messages about the inability to start the BOS Server or the Cache Manager or AFS client.
```
   # /etc/init.d/afs start   
```
When an entry called afs does not already exist in the local /etc/name_to_sysnum file, the script automatically creates it and reboots the machine to start using the new version of the file. If this happens, log in again as the superuser root after the reboot and run the initialization script again. This time the required entry exists in the /etc/name_to_sysnum file, and the modload program runs.
```
   login: root
   Password: root_password
   # /etc/init.d/afs start
```

Configuring the AFS-modified fsck Program on Solaris Systems

In this section, you make modifications to guarantee that the appropriate fsck program runs on AFS server partitions. The fsck program provided with the operating system must never run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data, it removes all of the data. To repeat:

Never run the standard fsck program on AFS server partitions. It discards AFS volumes.

Create the /usr/lib/fs/afs directory to house the AFS-modified fsck program and related files.
```
   # mkdir /usr/lib/fs/afs
   # cd /usr/lib/fs/afs  
```
Copy the vfsck binary to the newly created directory, changing the name as you do so.
```
   # cp  /tmp/afsdist/sun4x_56/dest/root.server/etc/vfsck  fsck
```

Working in the /usr/lib/fs/afs directory, create the following links to Solaris libraries:

   # ln -s /usr/lib/fs/ufs/clri  
   # ln -s /usr/lib/fs/ufs/df
   # ln -s /usr/lib/fs/ufs/edquota
   # ln -s /usr/lib/fs/ufs/ff
   # ln -s /usr/lib/fs/ufs/fsdb  
   # ln -s /usr/lib/fs/ufs/fsirand
   # ln -s /usr/lib/fs/ufs/fstyp
   # ln -s /usr/lib/fs/ufs/labelit
   # ln -s /usr/lib/fs/ufs/lockfs
   # ln -s /usr/lib/fs/ufs/mkfs  
   # ln -s /usr/lib/fs/ufs/mount
   # ln -s /usr/lib/fs/ufs/ncheck
   # ln -s /usr/lib/fs/ufs/newfs
   # ln -s /usr/lib/fs/ufs/quot
   # ln -s /usr/lib/fs/ufs/quota
   # ln -s /usr/lib/fs/ufs/quotaoff
   # ln -s /usr/lib/fs/ufs/quotaon
   # ln -s /usr/lib/fs/ufs/repquota
   # ln -s /usr/lib/fs/ufs/tunefs
   # ln -s /usr/lib/fs/ufs/ufsdump
   # ln -s /usr/lib/fs/ufs/ufsrestore
   # ln -s /usr/lib/fs/ufs/volcopy

Append the following line to the end of the file /etc/dfs/fstypes.
```
   afs AFS Utilities
```

Edit the /sbin/mountall file, making two changes.

Add an entry for AFS to the case statement for option 2, so that it reads as follows:

   case "$2" in
   ufs)    foptions="-o p"
           ;;
   afs)    foptions="-o p"
           ;;
   s5)     foptions="-y -t /var/tmp/tmp$$ -D"
           ;;
   *)      foptions="-y"
           ;;

Edit the file so that all AFS and UFS partitions are checked in parallel. Replace the following section of code:

   # For  fsck purposes, we make a distinction between ufs and
   # other file systems
   #
   if [ "$fstype" = "ufs" ]; then
        ufs_fscklist="$ufs_fscklist $fsckdev"
        saveentry $fstype "$OPTIONS" $special $mountp
        continue
   fi

with the following section of code:

   # For fsck purposes, we make a distinction between ufs/afs
   # and other file systems.
   #
   if [ "$fstype" = "ufs" -o "$fstype" = "afs" ]; then
        ufs_fscklist="$ufs_fscklist $fsckdev"
        saveentry $fstype "$OPTIONS" $special $mountp
        continue
   fi

Configuring Server Partitions on Solaris 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/vfstab, for each partition to be mounted on a directory created in the previous step. Note the value afs in the fourth field, which tells Solaris to use the AFS-modified fsck program on this partition.
```
   /dev/dsk/disk   /dev/rdsk/disk   /vicepxx   afs   boot_order  yes  
```
The following is an example for the first partition being configured.
```
   /dev/dsk/c0t6d0s1 /dev/rdsk/c0t6d0s1 /vicepa afs 3 yes
```
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 Solaris documentation for more information.
```
   # newfs -v /dev/rdsk/disk
```
Issue the mountall command to mount all partitions at once.
If you plan to retain client functionality on this machine after completing the installation, proceed to Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris Systems. Otherwise, proceed to Starting the BOS Server.

Enabling AFS Login on Solaris 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.

Explaining PAM is beyond the scope of this document. It is assumed that you understand the syntax and meanings of settings in the PAM configuration file (for example, how the other entry works, the effect of marking an entry as required, optional, or sufficient, and so on).

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. Current versions of Solaris come with a Kerberos v5 PAM module that will work, 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 in pam.conf:

Example 2.3. Solaris PAM session example

This example enables PAM authentication only for console login. You may want to add a similar line for the ssh service and for any other login service that you use, including possibly the other service (which serves as a catch-all). You may also want to add options to the AFS PAM session module (particularly retain_after_close, which is necessary for some versions of Solaris.

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 pam.conf manual page.

Sites which still require kaserver or external Kerberos v4 authentication should consult "Enabling kaserver based AFS Login on Solaris Systems" for details of how to enable AFS login on Solaris.

Proceed to Editing the File Systems Clean-up Script on Solaris Systems

Editing the File Systems Clean-up Script on Solaris Systems

Some Solaris distributions include a script that locates and removes unneeded files from various file systems. Its conventional location is /usr/lib/fs/nfs/nfsfind. The script generally uses an argument to the find command to define which file systems to search. In this step you modify the command to exclude the /afs directory. Otherwise, the command traverses the AFS filespace of every cell that is accessible from the machine, which can take many hours. The following alterations are possibilities, but you must verify that they are appropriate for your cell.
The first possible alteration is to add the -local flag to the existing command, so that it looks like the following:
```
   find $dir -local -name .nfs\* -mtime +7 -mount -exec rm -f {} \;   
```
Another alternative is to exclude any directories whose names begin with the lowercase letter a or a non-alphabetic character.
```
   find /[A-Zb-z]*  remainder of existing command   
```
Do not use the following command, which still searches under the /afs directory, looking for a subdirectory of type 4.2.
```
   find / -fstype 4.2     /* do not use */
```
Proceed to Starting the BOS Server (or if referring to these instructions while installing an additional file server machine, return to Starting Server Programs).