Merge 1.8.0~pre4 packaging into master

[pkg-k5-afs_openafs.git] / src / afsweb / README.BETA2

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 following 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
* Stronghold 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/