NAME
    Interchange::Link -- mod_perl 1.99/2.0 module for linking to Interchange

VERSION
    $Revision: 1.1.2.1 $

SYNOPSIS
      <Location /foundation>
        SetHandler perl-script
         PerlResponseHandler  Interchange::Link
         PerlOptions +GlobalRequest
         PerlSetVar InterchangeServer /var/run/interchange/socket
         PerlSetVar OrdinaryFileList "/foundation/images/ /foundation/dl/"
      </Location>

DESCRIPTION
    Interchange::Link is designed to replace the vlink and tlink programs
    that come with Interchange. The Interchange link protocol has been
    implemented via an Apache mod_perl modules which saves us the (small)
    overhead of the execution of a CGI program.

    In addition, it will deliver downloadable files in a streaming fashion
    without keeping Interchange open, which cuts overhead dramatically for
    large downloadable files. See FileDeliveryBase.

    Note that this module is not compatible with Apache 1.

PREREQUISITES
    You must have mod_perl 1.99 or higher installed on your Apache. On a Red
    Hat-style Linux system, it is as simple as:

        rpm -i mod_perl-1.99.XX-X.rpm
        service httpd restart

    Installation of mod_perl will vary from system to system. Consult the
    mod_perl documentation. Sometimes it is as easy as

        perl -MCPAN -e 'install ModPerl::Registry'

    but often it is not.

    Usually you can download the package from http://perl.apache.org/ and
    follow those instructions.

INSTALLATION
    You must specify that Apache use mod_perl, and you must tell it where to
    find the Perl modules you want to use.

    On a Red Hat Linux system you might copy this file to
    /usr/lib/httpd/perl/ via this procedure:

        mkdir -p /usr/lib/httpd/perl/Interchange
        cp Link.pm /usr/lib/httpd/perl/Interchange

    Then you provide a startup script that tells mod_perl where its
    libraries are:

        cd /usr/lib/httpd/perl
        echo "use lib qw(/usr/lib/httpd/perl);1;" > startup.pl

    Then you can put in your /etc/httpd/conf/httpd.conf:

        PerlModule Apache2
        PerlRequire /usr/lib/httpd/perl/startup.pl

    Finally, you specify a location like:

      <Location /foundation>
        SetHandler perl-script
         PerlResponseHandler  Interchange::Link
         PerlOptions +GlobalRequest
         PerlSetVar InterchangeServer /var/run/interchange/socket
         PerlSetVar OrdinaryFileList "/foundation/images/ /foundation/dl/"
      </Location>

    Note: The Apache <Location> path should not contain a dot (.) or any
    other characters except A-Z, a-z, 0-9 or a hyphen (-), so:

        <Location /shop.name> is invalid, whereas:
        <Location /shop-name> is valid.

    The specifics of the configuration are discussed in the next section.

CONFIGURATION
    The module understands directives set via the mod_perl "PerlSetVar"
    directive.

    InterchangeServer
        This specifies the way to contact the primary and possibly
        additionial Interchange servers. The InterchangeServer directive
        takes either a pathname to the Interchange UNIX socket or a
        host:port specification if you want to use INET mode.

        Normally this takes the form of:

             PerlSetVar InterchangeServer /var/run/interchange/socket

        If you want to specify more than one so that a backup server can
        provide request support in case of failure:

            PerlSetVar InterchangeServer  "/var/run/interchange/socket 10.1.1.1:7786"

        The optional InterchangeServerBackup directive takes the same
        arguments, but should obviously point to a different Interchange
        server than the primary. The InterchangeServerBackup directive is
        only of any use if you have multiple Interchange servers configured
        in a clustered environment.

        If you want to randomly select from a series of clustered servers,
        do:

            PerlSetVar InterchangeServer "10.1.1.1:7786 10.1.1.2:7786 10.1.1.3:7786"
            PerlSetVar RandomServer 1

        Note: The Apache <Location> path should not contain a dot (.) or any
        other characters except A-Z, a-z, 0-9 or a hyphen (-), so:

            <Location /shop.name> is invalid, whereas:
            <Location /shop-name> is valid.

        Example of a UNIX mode local connection:

            <Location /shop>
            SetHandler perl-script
            PerlResponseHandler Interchange::Link
            PerlSetVar InterchangeServer /opt/interchange/etc/socket
            </Location>

        Example of INET mode local connection:

            <Location /shop>
            SetHandler perl-script
            PerlResponseHandler Interchange::Link
            PerlSetVar InterchangeServer localhost:7786
            </Location>

        UNIX mode local primary connection and INET mode remote backup
        connection:

            <Location /shop>
            SetHandler perl-script
            PerlResponseHandler Interchange::Link
            PerlSetVar InterchangeServer /opt/interchange/etc/socket
            PerlSetVar InterchangeServerBackup another.server.com:7786
            </Location>

        The default if not set is "127.0.0.1:7786".

    ConnectTries and ConnectRetryDelay
        The ConnectTries parameter specifies the number of connection
        attempts to make before giving up. ConnectRetryDelay specifies the
        delay, in seconds, between each retry attempt.

        The ConnectTries default is 10 and the ConnectRetryDelay default is
        2 seconds. Here is an example:

            <Location /shop>
            SetHandler perl-script
            PerlResponseHandler Interchange::Link
            PerlSetVar ConnectTries 10
            PerlSetVar ConnectRetryDelay 1
            </Location>

    DropRequestList
        The DropRequestList allows a list of space-separated URI components
        to be specified. If one of the list entries is found anywhere in the
        requested URI, the request will be dropped with a 404 (not found)
        error, without the request being passed to Interchange. This
        parameter is useful for blocking known Microsoft IIS attacks like
        "Code Red", so that we don't waste any more time processing the
        (bogus) requests than we have to.

            <Location /shop>
            SetHandler perl-script
            PerlResponseHandler Interchange::Link
            PerlSetVar DropRequestList "/default.ida /x.ida /cmd.exe /root.exe"
            </Location>

    OrdinaryFileList
        The OrdinaryFileList allows a list of space-separated URI path
        components to be specified. If one of the list entries is found at
        the start of any request then that request will not be passed to
        Interchange. Instead, the file will be directly served by Apache.
        For example:

            <Location />
            SetHandler perl-script
            PerlResponseHandler Interchange::Link
            PerlSetVar OrdinaryFileList "/foundation/ /interchange-5/ /robots.txt"
            </Location>

        This will result in the following:

            www.example.com/index.html          (handled by Interchange)
            www.example.com/ord/basket.html     (handled by Interchange)
            www.example.com/foundation/images/somefile.gif (served by Apache)
            www.example.com/robots.txt          (served by Apache)

        You should add a trailing slash to directory names to prevent, for
        instance, "/images/foo.gif" from being confused with the likes of
        "/images.html". If OrdinaryFileList was set to "/images" then both
        of those requests would be handled by Apache. If OrdinaryFileList
        was set to "/images/" then "/images/foo.gif" would be handled by
        Apache and "/images.html" would be handled by Interchange.

        If you're using "<Location />" then you will need a dummy
        "index.html" file in your VirtualHost's DocumentRoot directory to
        avoid permission problems assocated with the Apache directory index
        creation code.

    InterchangeScript
        The InterchangeScript parameter allows the SCRIPT_NAME to be
        different from the <Location>. For example:

            <Location /shop>
                ...
            </Location>

        The above will set the SCRIPT_NAME to "/shop".

            <Location /shop>
                ...
            PerlSetVar InterchangeScript /foo
            </Location>

        The above will set the SCRIPT_NAME to "/foo", instead of "/shop"
        before passing the request to Interchange.

        The appropriate SCRIPT_NAME must be configured into the "Catalog"
        directive in your interchange.cfg file.

    FileDeliveryBase
        Interchange::Link can deliver files without needing to keep
        Interchange open. To do this, you set the HTTP Status: header to
        "httpd_deliver". In Interchange 5.0 or higher you can do this by
        putting in a page:

            [deliver
                status=httpd_deliver
                location=directory/file.ext
                type=application/octet-stream
               ]

        The "FileDeliveryBase" setting determines where the file will be
        relative to. While you can set it to "/", that is not recommended as
        files like "/etc/passwd" could be delivered.

        The default is the document root of the Apache server. To protect
        files from being served directly by Apache, you can either put them
        under a directory at the Interchange location, or you can use normal
        Apache exclusions.

BUGS
    Send bug reports and suggestions to the Interchange users list,
    <interchange-users@icdevgroup.org>.

COPYRIGHT AND LICENSE
     Copyright (C) 1996-2002 Red Hat, Inc.
     Copyright (C) 2002-2003 Interchange Development Group

    This program is free software. You can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation. You may refer to either version 2 of the
    License or (at your option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

