Apache module: mod_interchange (version 1.33)

Apache link module for Interchange

This module replaces the tlink and vlink programs that come with Interchange. It has been tested with all Interchange versions up to and including 5.3.1 (development).

This module has been tested with Apache versions 1.3.6 through 1.3.33. Note that this module is not compatible with Apache 2.

Contents

  1. Module Directives:
  2. Configuration Examples
  3. Copyright and License

InterchangeServer

Syntax: InterchangeServer address
Context: Location
Override: None
Status: Extension

Specifies the way Apache should connect to the primary Interchange server.

InterchangeServerBackup

Syntax: InterchangeServerBackup address
Context: Location
Override: None
Status: Extension

Specifies the way Apache should connect to the backup Interchange server in the event that the primary server is unavailable for any reason.

InterchangeServerBackup takes the same arguments as the InterchangeServer directive 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.

ConnectTries

Syntax: ConnectTries number
Context: Location
Override: None
Status: Extension

Number of connection attempts to make before giving up.  The default is 10.

ConnectRetryDelay

Syntax: ConnectRetryDelay seconds
Context: Location
Override: None
Status: Extension

Delay, in seconds, between each retry attempt.  The default is 2.

DropRequestList

Syntax: DropRequestList entry entry entry
Context: Location
Override: None
Status: Extension

Space-separated list of URI path components to deny access to.  Various attacks are made on Microsoft IIS systems and, while they don't affect Apache, they do tend to waste valuable processor time.

If any of the entries in the list are found anywhere in the requested URI, the request will be dropped with a 404 (not found) error.

A maximum of 10 entries may be present in the list.  Any other entries will be ignored.  If you need more than 10 entries, edit the IC_MAX_DROPLIST value in mod_interchange.c and recompile the module.  See the example below for a common use of this directive.

OrdinaryFileList

Syntax: OrdinaryFileList entry entry entry
Context: Location
Override: None
Status: Extension

Space-separated list of URI path components.  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.

A maximum of 10 entries may be present in the list.  Any other entries will be ignored.  If you need more than 10 entries, edit the IC_MAX_ORDINARYLIST value in mod_interchange.c and recompile the module.  See the example below for a common use of this directive.

InterchangeScript

Syntax: InterchangeScript name
Context: Location
Override: None
Status: Extension

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


Configuration Examples

Note: The Apache URI 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.

Here is an example UNIX-socket configuration:

    <Location /shop>
        SetHandler interchange-handler
        InterchangeServer /opt/interchange/etc/socket
    </Location>

Here is an INET-socket example:

    <Location /shop>
        SetHandler interchange-handler
        InterchangeServer localhost:7786
    </Location>

UNIX-socket local primary connection and INET-socket remote backup connection:

    <Location /shop>
        SetHandler interchange-handler
        InterchangeServer /opt/interchange/etc/socket
        InterchangeServerBackup another.server.com:7786
    </Location>

Two parameters control what happens when mod_interchange fails to connect to the Interchange server.  The most likely reason for a failure to connect is that Interchange is being restarted by the administrator.

ConnectTries specifies the number of connection attempts to make before giving up.  The default is 10.  ConnectRetryDelay specifies the delay, in seconds, between each retry attempt.  The default is 2.  Connection retry example:

    <Location /shop>
        SetHandler interchange-handler
        InterchangeServer localhost:7786
        ConnectTries 10
        ConnectRetryDelay 1
    </Location>

If an InterchangeServerBackup directive has been specified then the backup server will be tried immediately after an attempt to contact the primary server fails.  The ConnectTries and ConnectRetryDelay paramaters will only come into affect if both the primary and backup Interchange servers are found to be unavailable.

The DropRequestList allows a list of up to 10 space-separated URI components to be specified.  If any 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, such as "Code Red", so that we don't waste any more time processing these bogus requests than we have to.  DropRequestList example:

    <Location /shop>
        SetHandler interchange-handler
        InterchangeServer /opt/interchange/etc/socket
        DropRequestList /default.ida /x.ida /cmd.exe /root.exe
    </Location>

The OrdinaryFileList allows a list of up to 10 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.  OrdinaryFileList example:

    <Location />
        SetHandler interchange-handler
        InterchangeServer /opt/interchange/etc/socket
        OrdinaryFileList /foundation/ /interchange-5/ /robots.txt
    </Location>

This will result in the following:

    www.example.com/index.html  (Processed by Interchange)
    www.example.com/ord/basket.html  (Processed 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.

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

    <Location /shop>
        SetHandler interchange-handler
        InterchangeServer /opt/interchange/etc/socket
        InterchangeScript /foo
    </Location>

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

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



Change Log



Copyright and License

Copyright © 2000-2005 Cursor Software Limited.
Copyright © 1999 Francis J. Lacoste and iNsu Innovations Inc.
All rights reserved.

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.