Copyright 2000, International Business Machines Corporation and others.
All Rights Reserved.

This software has been released under the terms of the IBM Public
License.  For details, see the LICENSE file in the top-level source
directory or online at http://www.openafs.org/dl/license10.html

AFS Web Security Pack Version 1.0 for the Apache Web Server.

Release Notes

I. Introduction

AFS Web Security Pack is an extension available for selected Web servers 
that enables system administrators to provide secure access via a 
Web browser to documents stored in the AFS filespace. This document 
summarizes the changes made to AFS Web Security for this release, and 
provides installation and configuration instructions. 

Note: Due the long filenames and file extensions used for the AFS Web 
Security Pack distribution files, download of the AFS Web Security Pack
 product to a PC sometimes results in incorrect filenames. Note that all 
AFS Web Security Pack distribution files are g-zipped tar files, even if the 
*.tar.gz file extension is lost during the download process. 

II. Installation Prerequisites

Your system must meet the following software and disk space requirements 
to install this version of AFS Web Security Pack.

Operating system:	 Solaris 2.5.1, AIX 4.1, AIX 4.2, or AIX 4.2.1 
Web server:		 Apache 1.2.6 
AFS (client):		 AFS Client 3.4a 
Disk Space:		 650 KB 

Note: Due to security considerations, OpenAFS strongly recommends that 
AFS Web Security Pack be used only on a server enabled with Secure 
Sockets Layer (SSL).

III. New Features and Product Changes

The following list describes new features and changes that are included 
in this version of AFS Web Security Pack.

*  Configuration of AFS Web Security Pack is now easier and more flexible. The 
AFSMountPointDir and AFSLocation directives are no longer required. 
Instead, during configuration of AFS Web Security Pack, an authorization type 
(AFSAuthType) of AFS is now specified. (See the Installation and Configuration 
instructions that follow for additional details.)

*  The Log In dialog box that is displayed when users attempt to access 
the AFS file space via a web browser can now be customized adding the 
AFSLoginPrompt directive to the Apache server runtime configuration 
file. (See the Installation and Configuration instructions that follow for 
additional details.)



*  AFS Web Security Pack now provides the ability to log attempts to 
access AFS in which permission is denied. This logging can be used to 
determine if users are attempting to access information that they are not
 authorized to view. To configure this logging, you must add the
 SetAFSAccessLog directive to the Apache server runtime configuration file. 
(See the Installation and Configuration instructions that follow for 
additional details.)

*  AFS Web Security Pack now provides the ability to translate and access user 
directories that are specified with a special character such as a tilde (~), 
for example. http://www.yourcompany.com/~smith. To enable this feature, you 
must add the User Directory directive to the Apache server runtime 
configuration file. (See the Installation and Configuration instructions 
that follow for additional details.)

*  The previous version of AFS Web Security Pack did not correctly permit 
directory indexing of directories for which a user was assigned lookup 
permission. In addition, the Parent Link in directory indexes did not 
always work correctly. This version of AFS Web Security Pack corrects these 
problems.

*  This version of AFS Web Security Pack corrects a problem with the token cache 
that occasionally caused access to AFS to be incorrectly denied.

*  The previous version of AFS Web Security Pack did not accept AFS passwords 
that included a space. This version of AFS Web Security Pack corrects this problem.

*  This version of AFS Web Security Pack corrects a communication (pipe) problem 
that occasionally caused the message SERVER_ERROR to be returned. In 
addition, this version improves performance of AFS Web Security Pack.

IV. Known Defects and Limitations 

* Due to a preexisting problem in the AFS UNIX product, the Apache 
server Fancy Indexing option does not function as expected when AFS 
directories are displayed. If the Fancy Indexing option is enabled 
on the Apache server, when a user initially browses an ACL-protected 
directory (with "system:anyuser l" access), the user is able to see 
file details for directories and links, but not for files. Once the 
user selects a file and enters a username and password, details for 
the files are then displayed. This problem is not caused by AFS Web 
Security Pack or the Apache server, but is due to a defect in the UNIX-based 
AFS code. We are working to address this problem and will make an 
announcement when a corrected version is available. In the interim, 
please be aware of this limitation as you continue testing. 

V. Upgrade Instructions for AFS Web Security Pack for the Apache Web Server 

Note: Use the following instructions to upgrade AFS Web Security Pack on 
your Apache Web Server if Beta Version 1 or Beta Version 2 of the product 
is already installed. (If this is the first time you are installing AFS Web 
Security Pack, follow the instructions in the next section, Installing and 
Configuring AFS Web Security PAck 1.0 for the Apache Web Server.)

1. Replace the existing versions of the weblog, weblog_starter and 
libapacheafs.a files with the new files provided with this version 
of AFS Web Security Pack 1.0. Also, in the Apache src directory, 
replace the mod_afs.c or afs_module.c file with the new AFS Web Security Pack
Module, afs_module.c. 

2. In the Apache server Configuration file, change the line that 
references the AFS Web Security Pack module so that the line appears as 
follows:

    Module afs_module       afs_module.o

Note: If you want to enable AFS Web Security Pack to translate and access user
 home directories, you must include the userdir_module when you build 
the Apache server. For information on including modules when building 
the Apache server, consult you Apache server documentation.

3. In the Apache server src directory, run the Configure script to 
create a new configuration Makefile for your operating system. 

4. Stop the Apache server process (httpd). Then, issue the make 
command to compile the Apache server. 

5. In the Apache server runtime configuration file, remove (or comment 
out) the following two lines:

    SetAFSMountpointDir /afs_mountpoint_directory
    SetAFSLocation /afs_location

6. In the Apache server runtime configuration file, replace (or 
comment out) the SetHandler afs-authentication parameter with the 
AFSAuthType AFS parameter, so that the Location directive appears as 
follows:

    <Location /afs>
    AFSAuthType AFS
    </Location>

where /afs is the directory (or symbolic link to the directory) 
that contains the mount points to AFS to be used by the Apache 
server and AFS Web Security Pack. 

Note: You can specify AFSAuthType AFS for multiple locations to indicate 
that AFS Web Security Pack authentication must be used when a user attempts to
access a specific location. (In specifying a location, you can use wildcard 
characters if desired.)

7. (Optional) To customize the authorization dialog box that is 
displayed when users attempt to access the AFS file space via a 
web browser, add the following line within the Location directive:

    AFSLoginPrompt [Custom Text]

where [Custom Text] is the text that you want to appear in the dialog 
box that prompts users to enter a user name and password to access AFS 
filespace.

8. (Optional) To enable AFS Web Security Pack to access user directories, 
add the following lines to the Apache server runtime configuration 
file. This directive specifies the syntax used to access user 
directories and indicates that attempts to access user directories 
in the AFS filespace must be passed to AFS Web Security Pack:

    <Location /~*>
    AFSAuthtype AFS
    </Location>

Then, add the following line to the Apache server runtime configuration 
file to indicate the location of user directories in AFS:

    UserDir [Users Directory]

where Users Directory indicates the location of user's home directories.

Note: To enable user directory access in this manner, the Apache Server 
must include the UserDir module. For information on including this 
module when building the Apache server, consult you Apache server 
documentation.

9. (Optional) To enable logging of attempts to access AFS in which 
permission is denied, add the SetAFSAccessLog directive to the Apache 
server runtime configuration file as follows:

    SetAFSAccessLog [Access Log File]

where [Access Log File] is the full path log file in which failed access 
attempts are to be recorded. 

10. If necessary, rename the symbolic link to the AFS filespace in the 
Apache server's document root directory with the name specified in the 
Location directive for the AFS filespace in the server's runtime 
configuration file. 

VI. Installing and Configuring AFS Web Security Pack 1.0 for the Apache Web Server

This section provides brief installation and configuration instructions 
for Apache AFS Web Security Pack (Version 1.0 for Apache version 1.2.6 
and Apache version 1.3.1). See the product documentation for complete installation 
and configuration instructions and for details about using the configuration script to 
set up AFS Web Security Pack on the Apache server.

1. Uncompress and extract the files from the .tar.gz file, placing the 
files in the following locations, where Apache Installation Directory 
is the full pathname of the directory where the Apache Web server is 
installed:

-    Place both the weblog and weblog_starter files in one directory, 
for example, Apache Installation Directory/afswebsecurity. These files 
can be placed in any directory as long as they remain together. However, 
if the weblog and weblog_starter files are placed in a directory in AFS, 
ensure that either the user that the Apache Web server runs as, or the 
AFS group system:anyuser is designated as having read and lookup privileges 
on the directory's Access Control List (ACL). 

-    Place the libapacheafs.a file in any directory, for example, 
Apache Installation Directory/afswebsecurity. 

-    Place the afs_module.c file in the Apache src directory (Apache version 1.2.6)
or in the src/modules/extra directory (Apache version 1.3.1)
(generally located directly beneath the Apache Installation Directory). 

In addition, note the location of the AFS library file, libsys.a. This 
file is installed with the AFS client, and is generally located in the 
/usr/afsws/lib/afs directory. 

2. Modify the Apache Server Configuration File as follows.

Locate the EXTRA_LIBS line in the file, and add the paths to the 
libapacheafs.a and libsys.a libraries so that the line reads as follows: 

    EXTRA_LIBS=[full path to libapacheafs.a] [full path to libsys.a]

In the Module configuration section of the file, add a reference to the 
AFS Web Security Pack module. It is recommended that the AFS Web Security Pack 
module be the first Authentication module.
To add the AFS module to the list of Apache server modules, add the following line 
to the Configuration file: 

    Module afs_module         afs_module.o

Note: If you want the server to attempt to stop completely if AFS 
initialization fails, also add -DSHUTDOWN_IF_AFS_FAILS to the 
EXTRA_CFLAGS line in this file. Otherwise, on startup if the 
initialization procedure fails on startup, the Apache server 
will continue to run but AFS authentication will always fail.

3. Modify the Apache Server Runtime Configuration File (for example, 
httpd.conf) as follows.

Add the following lines to the runtime configuration file: 

    SetAFSDefault [Cell cellname]
    SetAFSCacheExpiration [cache_expiration]
    SetAFSTokenExpiration [token_expiration]
    SetAFSWeblogPath [weblog_starter_path]

where the arguments for these Apache server directives are as follows: 

[cellname] - The name of the default AFS cell to be accessed via the 
Apache server and AFS Web Security Pack.

[cache_expiration] -The maximum lifetime in seconds of an AFS token 
that is stored in the local cache. The default recommendation for 
this argument is 300 seconds (5 minutes). 

[token_expiration] -The maximum lifetime in seconds of an AFS token 
that is stored in the AFS kernel Cache Manager. The default 
recommendation for this argument is 60 seconds (1 minute). 

[weblog_starter_path] -The path to the AFS Web Security Pack weblog_starter program. 
Specify the full path or a path relative to the path set by the ServerRoot Apache
directive. 

Note: To enable logging of failed attempts to access AFS in which permission 
is denied, also add the directive:

    SetAFSAccessLog [Access Log File]

where [Access Log File] is the full path of the log file in which 
failed access attempts are to be recorded.

Then, add the following additional lines to the runtime configuration file:

    <Location /[afs]>
    AFSAuthType AFS
    </Location>

where [afs] is the request provided by users in combination with the 
server hostname and domain in order to access AFS filespace.

Note: This directive only works within Location (and LocationMatch for Apache 1.3.1)
tags and not in any other tags such as Directory or File.

Note: You can specify AFSAuthType AFS for multiple locations to indicate 
that AFS Web Security Pack authentication must be used when a user attempts to
access a specific location. (In specifying a location, you can use wildcard 
characters if desired.)

(Optional) To customize the authorization dialog box that is displayed 
when a user attempts to access the AFS file space via a web browser, 
add the follwing line to the Location directive added in the previous 
step. The Location directive then appears as follows: 

    AFSLoginPrompt [Custom Text]

where [Custom Text] is the text that you want to appear in the dialog box 
that prompts users to enter an AFS user name and password to access the 
AFS filespace. 

(Optional) To enable AFS Web Security Pack to access user directories, add the 
following additional Location directive to the Apache server runtime 
configuration file. 

    <Location /~*>
    AFSAuthType AFS
    </Location>

Then, also add the following additional line to the Apache server runtime 
configuration file to indicate the location of user directories in AFS. 

    UserDir [Users Directory]

where [Users Directory] indicates the location of user's home 
directories in AFS. The location is specified relative to the 
server document root directory. 

Note: To enable user directory access in this manner, the Apache 
server must include the User Dir module. 

Save and close the modified runtime configuration file. 

4.  Stop the Apache server process (httpd). Then, configure and make 
the Apache server and start it up with the new runtime configuration 
file.

5. Add the following to the shutdown or stopd file to shutdown the 
weblog_starter process BEFORE the kill -TERM for httpd.pid:

    kill -TERM `cat [path to httpd.pid].afs`

For example, if the httpd.pid file is in 
/local/stronghold/apache/logs/httpd.pid, then the stopd file should 
look something like this:

    kill -TERM `cat /local/stronghold/apache/logs/httpd.pid.afs`
    kill -TERM `cat /local/stronghold/apache/logs/httpd.pid` 

VII. AFS Web Security Pack Documentation

Postscript and HTML versions of the documentation for the initial 
Beta release AFS Web Security Pack are available in the doc directory. 

VIII. Additional Information about Apache and SSL

The following sites on the World Wide Web provide additional information 
about the Apache Web Server and SSL.

* Apache Home Page http://www.apache.org 
* Stronghold Home http://www.c2.net 
* Stronhold International http://www.int.c2.net 
* Apache-SSL Home http://www.apache-ssl.org 
* SSLeay FAQ http://www.psy.uq.edu.au:8080/~ftp/Crypto/
