=head1 NAME

mod_speedycgi - SpeedyCGI Apache module

=head1 DESCRIPTION

mod_speedycgi is a module for the Apache web server that interfaces to
SpeedyCGI.  mod_speedycgi is B<not> required in order to run SpeedyCGI
under Apache -- it's only a performance improvement.  mod_speedycgi
saves the web-server from having to fork/exec the speedy binary for
each request.

mod_speedycgi only replaces the front-end portion of SpeedyCGI.  The
back-end (where perl runs) remains the same.  No
perl code runs within the web server itself - each perl cgi-bin continues
to run in its own separate process.

=head1 INSTALLATION

You will need to have:

=over 4

=item *

The SpeedyCGI sources, already compiled and installed (do not run
S<"make clean">).

=item *

The Apache 1.3.6 sources

=back

A script is provided ("make_apache.pl") to do the apache build for you.
Type "perl make_apache.pl" to use it.

If you want to install manually, do the following:

=over 4

=item 1

Locate the path for:

    SpeedyCGI sources              (referred to as "/speedy_src")
    Apache sources                 (referred to as "/apache_src")
    Apache installation	directory  (referred to as "/apache_inst")

=item 2

Make the speedycgi modules directory:

    mkdir /apache_src/src/modules/speedycgi

=item 3

Create a Makefile.tmpl file in /apache_src/src/modules/speedycgi
directory that contains these lines:

    EXTRA_INCLUDES=-I/speedy_src/libspeedy

    #Dependencies

    $(OBJS) $(OBJS_PIC): Makefile

    # DO NOT REMOVE

=item 4

Extract the libspeedy.a object files into the apache sources:
Make a note of the object files that were extracted -- you will
need this list in step-7 below.

    cd /apache_src/src/modules/speedycgi
    ar xv /speedy_src/libspeedy/blib/arch/auto/libspeedy/libspeedy.a


=item 5

Copy over the mod_speedycgi.c source code:

    cp /speedy_src/apache/mod_speedycgi.c .

=item 6

Configure Apache:

    cd /apache_src
    ./configure --prefix=/apache_inst \
	--activate-module=src/modules/speedycgi/libspeedycgi.a \
	--disable-shared=speedycgi

=item 7

Fix the speedycgi Makefile.

    Edit /apache_src/src/modules/speedycgi/Makefile and change the "OBJS="
    line so it contains "mod_speedycgi.o", plus all the .o files that
    were extracted in step 4 above.


=item 8

Run "make" to build apache.

    cd /apache_src
    make

=item 9

If all looks good, install Apache with:

    make install

=back

=head1 CONFIGURATION

You can configure mod_speedycgi to either use a certain path on the web
server (similar to the way /cgi-bin works) or use files with a certain
extension (similar to the way .cgi files work).

=head2 Path Configuration

In this example, the /speedy path will be setup so that
scripts run under that path will use SpeedyCGI.

Add these lines near the B<top> of your httpd.conf ("/apache_inst" is
the Apache installation directory):

    Alias /speedy/ "/apache_inst/cgi-bin/"
    <Location /speedy>
	SetHandler speedycgi-script
	Options ExecCGI
	allow from all
    </Location>

If you still have the "printenv" cgi-bin script that was shipped with
Apache, you should be able to test with

    http://yourwebsite/speedy/printenv

You may have to "chmod a+x printenv" to make it executable.


=head2 File Extension Configuration

In the example below, all scripts ending with ".speedy" will be set
up to run under SpeedyCGI:

Add these lines near the B<top> of your httpd.conf:

    AddHandler speedycgi-script .speedy
    <Location />
        Options ExecCGI
    </Location>

You can test by creating a small "test.speedy" script in your htdocs
directory.  That file should contain:

    print "Content-type: text/html\n\nMy pid is $$\n";

Make sure to "chmod a+x test.speedy", then test with the URL

    http://yourwebsite/test.speedy


=head2 Options

SpeedyCGI options can also be added to httpd.conf file.
Type S<"perldoc CGI::SpeedyCGI"> for details.


=head2 Warning

Following the above instructions may compromise the security of your web site.
The security risks associated with SpeedyCGI are similar to those
of regular CGI.  If you don't understand the security implications of the
changes above then don't make them.
