# Appendix B. Configuring Legacy Components

This chapter describes how to configure a number of deprecated components in OpenAFS. Whilst these components are not recommended for sites performing new installations, it is recognised that there are a number of installations which have not yet transitioned from using these, for whom continued provision of installation instructions my be useful

## kaserver and Legacy Kerberos 4 Authentication

This section contains instructions for installing server and client machines in sites which use either the deprecated AFS kaserver or legacy Kerberos 4 authentication systems

This should be used in conjuction with the installation instructures in earlier chapters, whose format it mirrors.

### Background

As detailed in the OpenAFS "No more DES" roadmap, OpenAFS is moving away from the single DES based security models of both kaserver and external Kerberos 4 KDCs, in favour of using external, Kerberos 5 KDCs for authentication.

AFS version 3 was designed and implemented during the late 80s and early 90s when the state of the art in distributed computer authentication and data security was Kerberos 4 and single DES. The RXKAD security class was specified to use a single DES key and the kauth authentication protocol is a derivative of MIT's Kerberos 4 protocol.

For the better part of the last decade there has been concern regarding the cryptographic strength of the DES cipher when used as a building block within systems intended to prove authentication and/or data integrity and privacy. Kerberos 4 and RXKAD are not extensible and cannot negotiate non-DES key types. As a result efforts to migrate away from Kerberos 4 based authentication at higher risk organizations have been underway since the mid to late 90s. Ken Hornstein issued the first of his Kerberos 5 migration kits for AFS in May 1999.

In March 2003, the continued use of single DES and kauth as the basis for OpenAFS security became a real-world threat when a significant Kerberos 4 crossrealm vulnerability was published. The OpenAFS community was notified in security advisory OPENAFS-SA-2003-001 which can be found at http://www.openafs.org/security.

As a result of the mounting concerns regarding the strength of DES, NIST announced in May 2003 the withdrawal of FIPS 43-3 "Data Encryption Standard (DES)" as well as the associated FIPS 74 and FIPS 81. In other words, NIST announced that DES and its derivatives could no longer be used by the United States Government and should no longer by those that trust its lead.

In July 2003 MIT announced the end of life of the Kerberos 4 protocol which is distributed for backward compatibility as part of the MIT Kerberos 5 distribution.

### Using this Appendix

This appendix should be read in conjunction with the instructions contained in the earlier chapters. It contains additions and in some cases, modifications, to the directions contained in those chapters. It is organised into 3 main sections, corresponding to the topics of the earlier chapters.

1. Installing the First AFS Machine

2. Installing Additional Server Machines

3. Installing Additonal Client Machines

There is an additional section on installing AFS login functionality, which is relevant to all machines which are operating as AFS clients

In addition, some general substitions should be made

- References to kinitand aklog should be replaced with a single call to klog

  For example

         # kinit admin
         Password:  admin_passwd
         # aklog

  becomes

         # klog admin
         Password:  admin_passwd

### Installing the First AFS machine

This section details changes to the installation procedure for the first AFS machine which are required in order to use kaserver for authentication. As detailed above, new sites are strongly discouraged from deploying kaserver.

The structure of this section follows the structure of the earlier chapter.

#### Overview: Installing Server Functionality

In adddition to the items described, you must also create the Authentication Server as a database server process. The procedure for creating the initial security mechanisms is also changed.

#### Starting the kaserver Database Server Process

In addition to the database server processes described, you must also use the bos create command to create an entry for the following process, which runs on database server machines only:

- The Authentication Server (the kaserver process) maintains the Authentication Database

The following instructions include the -cell argument on all applicable commands. Provide the cell name you assigned in Defining Cell Name and Membership for Server Processes. If a command appears on multiple lines, it is only for legibility. The following commands should run before any of the bos create commands detailed in Starting the Database Server Processes.

1. Issue the bos create command to start the Authentication Server. The current working directory is still /usr/afs/bin.

          # ./bos create <machine name> kaserver simple /usr/afs/bin/kaserver  \
                         -cell <cell name>  -noauth

   You can safely ignore the messages that tell you to add Kerberos to the /etc/services file; AFS uses a default value that makes the addition unnecessary. You can also ignore messages about the failure of authentication.

2. Return to Starting the Database Server Processes and follow the remaining instructions

#### Initialising Cell Security with kaserver

The following instructions should be followed in place of those in Initializing Cell Security

Begin by creating the following two initial entries in the Authentication Database:

- A generic administrative account, called admin by convention. If you choose to assign a different name, substitute it throughout the remainder of this document.

  After you complete the installation of the first machine, you can continue to have all administrators use the admin account, or you can create a separate administrative account for each of them. The latter scheme implies somewhat more overhead, but provides a more informative audit trail for administrative operations.

- The entry for AFS server processes, called afs. No user logs in under this identity, but the Authentication Server's Ticket Granting Service (TGS) module uses the associated key to encrypt the server tickets that it grants to AFS clients for presentation to server processes during mutual authentication. (The chapter in the OpenAFS Administration Guide about cell configuration and administration describes the role of server encryption keys in mutual authentication.)

  In Step 7, you also place the initial AFS server encryption key into the /usr/afs/etc/KeyFile file. The AFS server processes refer to this file to learn the server encryption key when they need to decrypt server tickets.

You also issue several commands that enable the new admin user to issue privileged commands in all of the AFS suites.

The following instructions do not configure all of the security mechanisms related to the AFS Backup System. See the chapter in the OpenAFS Administration Guide about configuring the Backup System.

1. Enter kas interactive mode. Because the machine is in no-authorization checking mode, include the -noauth flag to suppress the Authentication Server's usual prompt for a password.

          # kas  -cell <cell name> -noauth
          ka>

2. Issue the kas create command to create Authentication Database entries called admin and afs.

   Do not provide passwords on the command line. Instead provide them as `afs_passwd` and `admin_passwd` in response to the kas command interpreter's prompts as shown, so that they do not appear on the standard output stream.

   You need to enter the `afs_passwd` string only in this step and in Step 7, so provide a value that is as long and complex as possible, preferably including numerals, punctuation characters, and both uppercase and lowercase letters. Also make the `admin_passwd` as long and complex as possible, but keep in mind that administrators need to enter it often. Both passwords must be at least six characters long.

          ka> create afs
          initial_password:  afs_passwd
          Verifying, please re-enter initial_password: afs_passwd
          ka> create admin
          initial_password: admin_passwd
          Verifying, please re-enter initial_password: admin_passwd

3. Issue the kas examine command to display the afs entry. The output includes a checksum generated by encrypting a constant with the server encryption key derived from the `afs_passwd` string. In Step 8 you issue the bos listkeys command to verify that the checksum in its output matches the checksum in this output.

          ka> examine afs
          User data for afs
           key (0) cksum is checksum . . .

4. Issue the kas setfields command to turn on the `ADMIN` flag in the admin entry. This enables the admin user to issue privileged kas commands. Then issue the kas examine command to verify that the `ADMIN` flag appears in parentheses on the first line of the output, as shown in the example.

          ka> setfields admin -flags admin
          ka> examine admin
          User data for admin (ADMIN) . . .

5. Issue the kas quit command to leave kas interactive mode.

          ka> quit

6. Issue the bos adduser command to add the admin user to the /usr/afs/etc/UserList file. This enables the admin user to issue privileged bos and vos commands.

          # ./bos adduser <machine name> admin -cell <cell name> -noauth

7. Issue the bos addkey command to define the AFS server encryption key in the /usr/afs/etc/KeyFile file.

   Do not provide the password on the command line. Instead provide it as `afs_passwd` in response to the bos command interpreter's prompts, as shown. Provide the same string as in Step 2.

          # ./bos addkey <machine name> -kvno 0 -cell <cell name>  -noauth
          Input key: afs_passwd
          Retype input key: afs_passwd

8. Issue the bos listkeys command to verify that the checksum for the new key in the KeyFile file is the same as the checksum for the key in the Authentication Database's afs entry, which you displayed in Step 3.

          # ./bos listkeys <machine name> -cell <ce
       ll name> -noauth
          key 0 has cksum checksum

   You can safely ignore any error messages indicating that bos failed to get tickets or that authentication failed.

   If the keys are different, issue the following commands, making sure that the `afs_passwd` string is the same in each case. The `checksum` strings reported by the kas examine and bos listkeys commands must match; if they do not, repeat these instructions until they do, using the -kvno argument to increment the key version number each time.

          # ./kas  -cell <cell name> -noauth
          ka> setpassword afs -kvno 1
          new_password: afs_passwd
          Verifying, please re-enter initial_password: afs_passwd
          ka> examine afs
          User data for afs
           key (1) cksum is checksum . . .
          ka> quit
          # ./bos addkey <machine name> -kvno 1 -cell <cell name> -noauth
          Input key: afs_passwd
          Retype input key: afs_passwd
          # ./bos listkeys <machine name> -cell <cell name> -noauth
          key 1 has cksum checksum

9. Proceed to Initializing the Protection Database to continue with the installation process

### Installing Additional Server Machines

#### Starting the Authenticxation Service

In addition to the instructions in the main guide, you must also start the Authentication Server on the new database machine, as detailed below

1. Start the Authentication Server (the kaserver process).

          % bos create <machine name> kaserver simple /usr/afs/bin/kaserver

2. Return to starting the backup server

### Enabling AFS login with kaserver

The authentication system of every machine should be modified so that users obtain an AFS token as they log into the local file system. Using AFS is simpler and more convenient for your users if you make the modifications on all client machines. Otherwise users must perform a two step login procedure (login to the local system, and then issue the klog command.

For convenience, the following sections group this procedure by system type. Proceed to the appropriate section.

- Enabling AFS Login on AIX Systems

- Enabling AFS Login on HP-UX Systems

- Enabling AFS Login on IRIX Systems

- Enabling AFS Login on Linux Systems

- Enabling AFS login on Solaris Systems

### Enabling kaserver based AFS login

Now incorporate AFS into the AIX secondary authentication system.

1. Issue the ls command to verify that the afs_dynamic_auth and afs_dynamic_kerbauth programs are installed in the local /usr/vice/etc directory.

          # ls /usr/vice/etc

   If the files do not exist, unpack the OpenAFS Binary Distribution for AIX (if it is not already), change directory as indicated, and copy them.

          # cd /tmp/afsdist/rs_aix42/dest/root.client/usr/vice/etc
          # cp  -p  afs_dynamic*  /usr/vice/etc

2. Edit the local /etc/security/user file, making changes to the indicated stanzas:

   - In the default stanza, set the `registry` attribute to DCE (not to AFS), as follows:

            registry = DCE

   - In the default stanza, set the `SYSTEM` attribute as indicated.

     If the machine is an AFS client only, set the following value:

            SYSTEM = "AFS OR (AFS[UNAVAIL] AND compat[SUCCESS])"

     If the machine is both an AFS and a DCE client, set the following value (it must appear on a single line in the file):

            SYSTEM = "DCE OR DCE[UNAVAIL] OR AFS OR (AFS[UNAVAIL]  \
                AND compat[SUCCESS])"

   - In the `root` stanza, set the `registry` attribute as follows. It enables the local superuser root to log into the local file system only, based on the password listed in the local password file.

            root:
                  registry = files

3. Edit the local /etc/security/login.cfg file, creating or editing the indicated stanzas:

   - In the `DCE` stanza, set the `program` attribute as follows.

     If you use the AFS Authentication Server (kaserver process):

            DCE:
                 program = /usr/vice/etc/afs_dynamic_auth

     If you use a Kerberos v4 implementation of AFS authentication:

            DCE:
                 program = /usr/vice/etc/afs_dynamic_kerbauth

   - In the `AFS` stanza, set the `program` attribute as follows.

     If you use the AFS Authentication Server (kaserver process):

            AFS:
                 program = /usr/vice/etc/afs_dynamic_auth

     If you use a Kerberos v4 implementation of AFS authentication:

            AFS:
                 program = /usr/vice/etc/afs_dynamic_kerbauth

4. Proceed to Starting the BOS Server, if you are installing your first file server machine; Starting Server Programs, if you are installing an additional file server machine; or Loading and Creating Client Files if you are installating a client

### Enabling kaserver based AFS Login on HP-UX systems

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

The following instructions explain how to alter the entries in the PAM configuration file for each service for which you wish to use AFS authentication. Other configurations possibly also work, but the instructions specify the recommended and tested configuration.

The instructions specify that you mark each entry as `optional`. However, marking some modules as optional can mean that they grant access to the corresponding service even when the user does not meet all of the module's requirements. In some operating system revisions, for example, if you mark as optional the module that controls login via a dial-up connection, it allows users to login without providing a password. See the OpenAFS Release Notes for a discussion of any limitations that apply to this operating system.

Also, with some operating system versions you must install patches for PAM to interact correctly with certain authentication programs. For details, see the OpenAFS Release Notes.

The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three attributes.

`try_first_pass`

- This is a standard PAM attribute that can be included on entries after the first one for a service; it directs the module to use the password that was provided to the first module. For the AFS module, it means that AFS authentication succeeds if the password provided to the module listed first is the user's correct AFS password. For further discussion of this attribute and its alternatives, see the operating system's PAM documentation.

`ignore_root`

- This attribute, specific to the AFS PAM module, directs it to ignore not only the local superuser root, but also any user with UID 0 (zero).

`setenv_password_expires`

- This attribute, specific to the AFS PAM module, sets the environment variable PASSWORD_EXPIRES to the expiration date of the user's AFS password, which is recorded in the Authentication Database.

Perform the following steps to enable AFS login.

1. Unpack the OpenAFS Binary Distribution for HP-UX into the /tmp/afsdist directory, if it is not already. Then change directory as indicated.

          # cd /usr/lib/security

2. Copy the AFS authentication library file to the /usr/lib/security directory. Then create a symbolic link to it whose name does not mention the version. Omitting the version eliminates the need to edit the PAM configuration file if you later update the library file.

   If you use the AFS Authentication Server (kaserver process) in the cell:

          # cp /tmp/afsdist/hp_ux110/dest/lib/pam_afs.so.1  .
          # ln -s  pam_afs.so.1  pam_afs.so

   If you use a Kerberos implementation of AFS authentication:

          # cp /tmp/afsdist/hp_ux110/dest/lib/pam_afs.krb.so.1   .
          # ln -s pam_afs.krb.so.1 pam_afs.so

3. Edit the `Authentication management` section of the HP-UX PAM configuration file, /etc/pam.conf by convention. The entries in this section have the value `auth` in their second field.

   First edit the standard entries, which refer to the HP-UX PAM module (usually, the file /usr/lib/security/libpam_unix.1) in their fourth field. For each service for which you want to use AFS authentication, edit the third field of its entry to read `optional`. The pam.conf file in the HP-UX distribution usually includes standard entries for the login and ftp services, for instance.

   If there are services for which you want to use AFS authentication, but for which the pam.conf file does not already include a standard entry, you must create that entry and place the value `optional` in its third field. For instance, the HP-UX pam.conf file does not usually include standard entries for the remsh or telnet services.

   Then create an AFS-related entry for each service, placing it immediately below the standard entry. The following example shows what the `Authentication Management` section looks like after you have you edited or created entries for the services mentioned previously. Note that the example AFS entries appear on two lines only for legibility.

          login   auth  optional  /usr/lib/security/libpam_unix.1
          login   auth  optional  /usr/lib/security/pam_afs.so      \
                try_first_pass  ignore_root  setenv_password_expires
          ftp     auth  optional  /usr/lib/security/libpam_unix.1
          ftp     auth  optional  /usr/lib/security/pam_afs.so      \
                try_first_pass  ignore_root
          remsh   auth  optional  /usr/lib/security/libpam_unix.1
          remsh   auth  optional  /usr/lib/security/pam_afs.so      \
                try_first_pass  ignore_root
          telnet  auth  optional  /usr/lib/security/libpam_unix.1
          telnet  auth  optional  /usr/lib/security/pam_afs.so      \
                try_first_pass  ignore_root  setenv_password_expires

4. If you use the Common Desktop Environment (CDE) on the machine and want users to obtain an AFS token as they log in, also add or edit the following four entries in the `Authentication management` section. Note that the AFS-related entries appear on two lines here only for legibility.

          dtlogin   auth  optional  /usr/lib/security/libpam_unix.1
          dtlogin   auth  optional  /usr/lib/security/pam_afs.so     \
                try_first_pass  ignore_root
          dtaction  auth  optional  /usr/lib/security/libpam_unix.1
          dtaction  auth  optional  /usr/lib/security/pam_afs.so     \
                try_first_pass  ignore_root

5. Proceed to Starting the BOS Server if you are installing your first file server; Starting Server Programs if you are installing an additional file server machine; or Loading and Creating Client Files. if you are installing a client.

### Enabling kaserver based AFS Login on IRIX Systems

The standard IRIX command-line login program and the graphical xdm login program both automatically grant an AFS token when AFS is incorporated into the machine's kernel. However, some IRIX distributions use another login utility by default, and it does not necessarily incorporate the required AFS modifications. If that is the case, you must disable the default utility if you want AFS users to obtain AFS tokens at login. For further discussion, see the OpenAFS Release Notes.

If you configure the machine to use an AFS-modified login utility, then the afsauthlib.so and afskauthlib.so files (included in the AFS distribution) must reside in the /usr/vice/etc directory. Issue the ls command to verify.

       # ls /usr/vice/etc

If the files do not exist, unpack the OpenAFS Binary Distribution for IRIX (if it is not already), change directory as indicated, and copy them.

       # cd /tmp/afsdist/sgi_65/dest/root.client/usr/vice/etc
       # cp  -p  *authlib*  /usr/vice/etc

After taking any necessary action, proceed to Starting the BOS Server if you are installing your first file server; Starting Server Programs if you are installing an additional file server machine; or Loading and Creating Client Files if you are installing a client.

### Enabling kaserver based AFS Login on Linux Systems

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

The following instructions explain how to alter the entries in the PAM configuration file for each service for which you wish to use AFS authentication. Other configurations possibly also work, but the instructions specify the recommended and tested configuration.

The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three attributes.

### Authentication Management

`try_first_pass`

- This is a standard PAM attribute that can be included on entries after the first one for a service; it directs the module to use the password that was provided to the first module. For the AFS module, it means that AFS authentication succeeds if the password provided to the module listed first is the user's correct AFS password. For further discussion of this attribute and its alternatives, see the operating system's PAM documentation.

`ignore_root`

- This attribute, specific to the AFS PAM module, directs it to ignore not only the local superuser root, but also any user with UID 0 (zero).

`ignore_uid` uid

- This option is an extension of the "ignore_root" switch. The additional parameter is a limit. Users with a uid up to the given parameter are ignored by pam_afs.so. Thus, a system administrator still has the opportunity to add local user accounts to his system by choosing between "low" and "high" user ids. An example /etc/passwd file for "ignore_uid 100" may have entries like these:

              .
              .
      afsuserone:x:99:100::/afs/afscell/u/afsuserone:/bin/bash
      afsusertwo:x:100:100::/afs/afscell/u/afsusertwo:/bin/bash
      localuserone:x:101:100::/home/localuserone:/bin/bash
      localusertwo:x:102:100::/home/localusertwo:/bin/bash
              .
              .

  AFS accounts should be locked in the file /etc/shadow like this:

              .
              .
      afsuserone:!!:11500:0:99999:7:::
      afsusertwo:!!:11500:0:99999:7:::
      localuserone:<thelocaluserone'skey>:11500:0:99999:7:::
      localusertwo:<thelocalusertwo'skey>:11500:0:99999:7:::
              .
              .

  There is no need to store a local key in this file since the AFS password is sent and verfied at the AFS cell server!

`setenv_password_expires`

- This attribute, specific to the AFS PAM module, sets the environment variable PASSWORD_EXPIRES to the expiration date of the user's AFS password, which is recorded in the Authentication Database.

`set_token`

- Some applications don't call pam_setcred() in order to retrieve the appropriate credentials (here the AFS token) for their session. This switch sets the credentials already in pam_sm_authenticate() obsoleting a call to pam_setcred(). Caution: Don't use this switch for applications which do call pam_setcred()! One example for an application not calling pam_setcred() are older versions of the samba server. Nevertheless, using applications with working pam session management is recommended as this setup conforms better with the PAM definitions.

`refresh_token`

- This options is identical to "set_token" except that no new PAG is generated. This is necessary to handle processes like xlock or xscreensaver. It is not enough to just unlock the screen for a user who reactivated his session by typing in the correct AFS password, but one may also need fresh tokens with a full lifetime in order to work on, and the new token must be refreshed in the already existing PAG for the processes that have been started. This is achieved using this option.

`use_klog`

- Activating this switch causes authentication to be done by calling the external program "klog". One program requiring this is for example kdm of KDE 2.x.

`dont_fork`

- Usually, the password verification and token establishment is performed in a sub process. Using this option pam_afs does not fork and performs all actions in a single process. Only use this option in cases where you notice serious problems caused by the sub process. This option has been developed in respect to the "mod_auth_pam"-project (see also mod_auth_pam). The mod_auth_pam module enables PAM authentication for the apache http server package.

### Session Management

`no_unlog`

- Normally the tokens are deleted (in memory) after the session ends. Using this option causes the tokens to be left untouched. This behaviour was the default in pam_afs until openafs-1.1.1!

`remainlifetime` sec

- The tokens are kept active for sec seconds before they are deleted. X display managers i.e. are used to inform the applications started in the X session before the logout and then end themselves. If the token was deleted immediately the applications would have no chance to write back their settings to i.e. the user's AFS home space. This option may help to avoid the problem.

Perform the following steps to enable AFS login.

1. Unpack the OpenAFS Binary Distribution for Linux into the /tmp/afsdist/ directory, if it is not already. Then change to the directory for PAM modules, which depends on which Linux distribution you are using.

   If you are using a Linux distribution from Red Hat Software:

          # cd /lib/security

   If you are using another Linux distribution:

          # cd /usr/lib/security

2. Copy the appropriate AFS authentication library file to the directory to which you changed in the previous step. Create a symbolic link whose name does not mention the version. Omitting the version eliminates the need to edit the PAM configuration file if you later update the library file.

   If you use the AFS Authentication Server (kaserver process):

          # cp /cdrom/i386_linux22/lib/pam_afs.so.1  .
          # ln -s pam_afs.so.1 pam_afs.so

   If you use a Kerberos implementation of AFS authentication:

          # cp /cdrom/i386_linux22/lib/pam_afs.krb.so.1   .
          # ln -s pam_afs.krb.so.1 pam_afs.so

3. For each service with which you want to use AFS authentication, insert an entry for the AFS PAM module into the `auth` section of the service's PAM configuration file. (Linux uses a separate configuration file for each service, unlike some other operating systems which list all services in a single file.) Mark the entry as `sufficient` in the second field.

   Place the AFS entry below any entries that impose conditions under which you want the service to fail for a user who does not meet the entry's requirements. Mark these entries `required`. Place the AFS entry above any entries that need to execute only if AFS authentication fails.

   Insert the following AFS entry if using the Red Hat distribution:

          auth  sufficient  /lib/security/pam_afs.so   try_first_pass  ignore_root

   Insert the following AFS entry if using another distribution:

          auth  sufficient  /usr/lib/security/pam_afs.so  try_first_pass  ignore_root

   Check the PAM config files also for "session" entries. If there are lines beginning with "session" then please insert this line too:

          session  optional  /lib/security/pam_afs.so

   or

          session  optional  /usr/lib/security/pam_afs.so

   This guarantees that the user's tokens are deleted from memory after his session ends so that no other user coincidently gets those tokens without authorization! The following examples illustrate the recommended configuration of the configuration file for several services:

   ### Authentication Management

   (/etc/pam.d/login)

4.        #%PAM-1.0
          auth      required   /lib/security/pam_securetty.so
          auth      required   /lib/security/pam_nologin.so
          auth      sufficient /lib/security/pam_afs.so try_first_pass ignore_root
          #                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          #This enables AFS authentication for every user but root
          auth      required   /lib/security/pam_pwdb.so shadow nullok
          account   required   /lib/security/pam_pwdb.so
          password  required   /lib/security/pam_cracklib.so
          password  required   /lib/security/pam_pwdb.so shadow nullok use_authtok
          session   optional   /lib/security/pam_afs.so
          #Make sure tokens are deleted after the user logs out
          session   required   /lib/security/pam_pwdb.so

(/etc/pam.d/samba)

-        auth       required     /lib/security/pam_afs.so ignore_uid 100 set_token
         #                                                ^^^^^^^^^^^^^^^^^^^^^^^^
         #Here, users with uid>100 are considered to belong to the AFS and users
         #with uid<=100 are ignored by pam_afs. The token is retrieved already in
         #pam_sm_authenticate() (this is an example pam config for a samba version
         #that does not call pam_setcred(), it also does no sense to include session
         #entries here since they would be ignored by this version of samba ).
         account    required     /lib/security/pam_pwdb.so

(/etc/pam.d/xscreensaver)

-        auth       sufficient   /lib/security/pam_afs.so ignore_uid 100 refresh_token
         #                                                               ^^^^^^^^^^^^^
         #Avoid generating a new PAG for the new tokens, use the already existing PAG and
         #establish a fresh token in it.
         auth       required     /lib/security/pam_pwdb.so try_first_pass

(/etc/pam.d/httpd)

-        auth       required   /lib/security/pam_afs.so ignore_uid 100 dont_fork
         #                                                             ^^^^^^^^^
         #Don't fork for the verification of the password.

### Session Management

(/etc/pam.d/su)

-        auth       sufficient   /lib/security/pam_afs.so ignore_uid 100
         auth       required     /lib/security/pam_pwdb.so try_first_pass
         account    required     /lib/security/pam_pwdb.so
         password   required     /lib/security/pam_cracklib.so
         password   required     /lib/security/pam_pwdb.so use_authtok
         session    required     /lib/security/pam_pwdb.so
         session    optional     /lib/security/pam_afs.so no_unlog
         #                                                ^^^^^^^^
         #Don't delete the token in this case, since the user may still
         #need it (for example if somebody logs in and changes to root
         #afterwards he may still want to access his home space in AFS).
         session    required     /lib/security/pam_login_access.so
         session    optional     /lib/security/pam_xauth.so

(/etc/pam.d/xdm)

-        auth       required     /lib/security/pam_nologin.so
         auth       required     /lib/security/pam_login_access.so
         auth       sufficient   /lib/security/pam_afs.so ignore_uid 100 use_klog
         auth       required     /lib/security/pam_pwdb.so try_first_pass
         account    required     /lib/security/pam_pwdb.so
         password   required     /lib/security/pam_cracklib.so
         password   required     /lib/security/pam_pwdb.so shadow nullok use_authtok
         session    optional     /lib/security/pam_afs.so remainlifetime 10
         #                                                ^^^^^^^^^^^^^^^^^
         #Wait 10 seconds before deleting the AFS tokens in order to give
         #the programs of the X session some time to save their settings
         #to AFS.
         session    required     /lib/security/pam_pwdb.so

- After taking any necessary action, proceed to Starting the BOS Server if you are installing your first file server; Starting Server Programs if you are installing an additional file server machine; or Loading and Creating Client Files if you are installing a client.

### Enabling kaserver based AFS Login on Solaris Systems

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

The following instructions explain how to alter the entries in the PAM configuration file for each service for which you wish to use AFS authentication. Other configurations possibly also work, but the instructions specify the recommended and tested configuration.

The instructions specify that you mark each entry as `optional`. However, marking some modules as optional can mean that they grant access to the corresponding service even when the user does not meet all of the module's requirements. In some operating system revisions, for example, if you mark as optional the module that controls login via a dial-up connection, it allows users to login without providing a password. See the OpenAFS Release Notes for a discussion of any limitations that apply to this operating system.

Also, with some operating system versions you must install patches for PAM to interact correctly with certain authentication programs. For details, see the OpenAFS Release Notes.

The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three attributes.

### Authentication Management

`try_first_pass`

- This is a standard PAM attribute that can be included on entries after the first one for a service; it directs the module to use the password that was provided to the first module. For the AFS module, it means that AFS authentication succeeds if the password provided to the module listed first is the user's correct AFS password. For further discussion of this attribute and its alternatives, see the operating system's PAM documentation.

`ignore_root`

- This attribute, specific to the AFS PAM module, directs it to ignore not only the local superuser root, but also any user with UID 0 (zero).

`setenv_password_expires`

- This attribute, specific to the AFS PAM module, sets the environment variable PASSWORD_EXPIRES to the expiration date of the user's AFS password, which is recorded in the Authentication Database.

Perform the following steps to enable AFS login.

1. Unpack the OpenAFS Binary Distribution for Solaris into the /cdrom directory, if it is not already. Then change directory as indicated.

          # cd /usr/lib/security

2. Copy the AFS authentication library file to the /usr/lib/security directory. Then create a symbolic link to it whose name does not mention the version. Omitting the version eliminates the need to edit the PAM configuration file if you later update the library file.

   If you use the AFS Authentication Server (kaserver process):

          # cp /tmp/afsdist/sun4x_56/dest/lib/pam_afs.so.1 .
          # ln -s pam_afs.so.1 pam_afs.so

   If you use a Kerberos implementation of AFS authentication:

          # cp /tmp/afsdist/sun4x_56/dest/lib/pam_afs.krb.so.1 .
          # ln -s pam_afs.krb.so.1 pam_afs.so

3. Edit the `Authentication management` section of the Solaris PAM configuration file, /etc/pam.conf by convention. The entries in this section have the value `auth` in their second field.

   First edit the standard entries, which refer to the Solaris PAM module (usually, the file /usr/lib/security/pam_unix.so.1) in their fourth field. For each service for which you want to use AFS authentication, edit the third field of its entry to read `optional`. The pam.conf file in the Solaris distribution usually includes standard entries for the login, rlogin, and rsh services, for instance.

   If there are services for which you want to use AFS authentication, but for which the pam.conf file does not already include a standard entry, you must create that entry and place the value `optional` in its third field. For instance, the Solaris pam.conf file does not usually include standard entries for the ftp or telnet services.

   Then create an AFS-related entry for each service, placing it immediately below the standard entry. The following example shows what the `Authentication Management` section looks like after you have you edited or created entries for the services mentioned previously. Note that the example AFS entries appear on two lines only for legibility.

          login   auth  optional  /usr/lib/security/pam_unix.so.1
          login   auth  optional  /usr/lib/security/pam_afs.so       \
                try_first_pass  ignore_root  setenv_password_expires
          rlogin  auth  optional  /usr/lib/security/pam_unix.so.1
          rlogin  auth  optional  /usr/lib/security/pam_afs.so       \
                try_first_pass  ignore_root  setenv_password_expires
          rsh     auth  optional  /usr/lib/security/pam_unix.so.1
          rsh     auth  optional  /usr/lib/security/pam_afs.so       \
                try_first_pass  ignore_root
          ftp     auth  optional  /usr/lib/security/pam_unix.so.1
          ftp     auth  optional  /usr/lib/security/pam_afs.so       \
                try_first_pass  ignore_root
          telnet  auth  optional  /usr/lib/security/pam_unix.so.1
          telnet  auth  optional  /usr/lib/security/pam_afs.so       \
                try_first_pass  ignore_root  setenv_password_expires

4. If you use the Common Desktop Environment (CDE) on the machine and want users to obtain an AFS token as they log in, also add or edit the following four entries in the `Authentication management` section. Note that the AFS-related entries appear on two lines here only for legibility.

          dtlogin   auth  optional  /usr/lib/security/pam_unix.so.1
          dtlogin   auth  optional  /usr/lib/security/pam_afs.so     \
                try_first_pass  ignore_root
          dtsession  auth  optional /usr/lib/security/pam_unix.so.1
          dtsession  auth  optional /usr/lib/security/pam_afs.so     \
                try_first_pass  ignore_root

5. Proceed to Editing the File Systems Clean-up Script on Solaris Systems in the server instructions if you are installing your first file server; Starting Server Programs if you are installing an additional file server machine; or Editing the File Systems Clean-up Script on Solaris Systems in the client instructions if you are installing a client.