# 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:
   - InterchangeServer
   - InterchangeServerBackup
   - ConnectTries
   - ConnectRetryDelay
   - DropRequestList
   - OrdinaryFileList
   - InterchangeScript
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

- 1.33 (Mon 07 Jun 2005) Kevin Walsh <kevin@cursor.biz>
  - Applied a patch supplied by Jonathon Sim of Zeald. Thanks Jon! The patch fixes a problem where the result code from a call to the `ap_scan_script_header_err_buff()` Apache API function was not being examined closely enough. This apparently caused problems with GoogleBot and caching proxies that make use of the `If-Modified-Since:` HTTP header.
- 1.32 (Mon 21 Jan 2005) Kevin Walsh <kevin@cursor.biz>
  - Fixed a bug that caused problems with `[history-scan]` regex matches. The entire `Location` path was being stripped from the URI, which was fine unless `<Location />` was specified.
- 1.31 (Thu 13 Oct 2004) Kevin Walsh <kevin@cursor.biz>
  - Fixed a bug with a patch kindly supplied by Josh Lavin. The `OrdinaryFileList` code was using the `IC_MAX_DROPLIST` configurable setting instead of its own `IC_MAX_ORDINARYLIST`. That'll teach me not to copy/paste when creating new code. :-)
- 1.30 (Thu 08 Mar 2004) Kevin Walsh <kevin@cursor.biz>
  - Added the `OrdinaryFileList` and `InterchangeScript` configuration parameters.
- 1.29 (Thu 09 Jan 2003) Kevin Walsh <kevin@cursor.biz>
  - Fixed a bug reported by Jeff Dafoe. The request information enabled Interchange to show the correct page but prevented it from storing the request in the session's history. The problem only showed itself when Interchange's `[history-scan]` tag was used. As almost no page history was saved, `[history-scan]` sent the user to the default page (usually index) most of the time. This bug seems to have originated in version 1.28.
- 1.28 (Thu 09 Jan 2003) Kevin Walsh <kevin@cursor.biz>
  - Fixed a weird bug where empty HTTP variables were being passed under certain circumstances.
- 1.27 (Wed 27 Nov 2002) Kevin Walsh <kevin@cursor.biz>
  - Implemented a proper (automatic) `URILevels` mechanism and removed the `URILevels` configuration directive. This also fixes a bug, reported by Philip Hempel in the interchange-users mail list, where `[PT]` redirects were not being handled correctly.
- 1.26 (Sun 03 Nov 2002) Kevin Walsh <kevin@cursor.biz>
  - Added proper support for internal redirects which will help with the security of "soft product" delivery.
- 1.25 (Sat 02 Nov 2002) Kevin Walsh <kevin@cursor.biz>
  - Fixed a bug reported by Jeff Dafoe. There are some instances where the socket to Interchange may not be closed upon error. While I'm reasonably certain that Apache will handle this for us, it doesn't hurt to ensure that the socket is closed.
- 1.24 (Mon 31 Oct 2002) Kevin Walsh <kevin@cursor.biz>
  - Fixed a bug reported by Shawn Mathews. The `URILevels` directive was not taken into account when munging the `PATH_INFO` HTTP environment variable.
- 1.23 (Wed 02 Oct 2002) Kevin Walsh <kevin@cursor.biz>
  - Added the module identification to the Apache version string so that it shows up in the "Server:" response header field when Apache is configured to show version information. Of course, suitably paranoid system administrators should configure Apache so that it doesn't release unnecessay server information. Any competent adminsitrator should know what module versions they have anyway. :-)
- 1.22 (Mon 05 Aug 2002) Kevin Walsh <kevin@cursor.biz>
  - Fixed a bug reported by John Young. Mod_interchange was not decoding entities in the `REQUEST_URI`, which caused Interchange searches (scan) with encoded spaces to fail.
- 1.21 (Mon 01 Apr 2002) Kevin Walsh <kevin@cursor.biz>
  - Added Support for Solaris 8 with a patch supplied by John Young. Apparently Solaris doesn't have the `AF_LOCAL`, `PF_LOCAL` or `SUN_LEN` macros. John's patch conditionally `#define`s the missing `_LOCAL` macros as aliases for `AF_UNIX` and `PF_UNIX`, and conditionally `#define`s a `SUN_LEN` macro.
- 1.20 (Fri 15 Mar 2002) Kevin Walsh <kevin@cursor.biz>
  - Added the `InterchangeServerBackup` module parameter to allow the module to automatically try a backup Interchange server if the primary is unavailable.
- 1.14 (Wed 26 Sep 2001) Kevin Walsh <kevin@cursor.biz>
  - Added the `DropRequestList` module parameter to stop Interchange from having to waste its time processing known IIS exploits.
- 1.13 (Wed 22 Aug 2001) Kevin Walsh <kevin@cursor.biz>
  - Added a retry loop so that connections delay for a while, instead of failing, while the Interchange server is being restarted.
- 1.12 (Sun 10 Aug 2001) Kevin Walsh <kevin@cursor.biz>
  - Added OS/X patch as it doesn't appear to have a typedef for `socklen_t`. The poor Apple OS/X users must un-comment the OSX line in the Makefile to the module to compile the definition in.
- 1.11 (Fri 20 Apr 2001) Kevin Walsh <kevin@cursor.biz>
  - Added the `URILevels` parameter to allow for sites that need to specify `<Location>`s that have more than one directory level. The default `URILevel` is 1.
- 1.10 (Tue 27 Feb 2001) Kevin Walsh <kevin@cursor.biz>
  - Rewrote the `ic_send_request()` and `ic_transfer_response()` functions because they were giving all sorts of `EPIPE` errors when writing data to clients during a concurrent-user test. Testing tools used were ab (ApacheBench/1.3) and httperf. We have now lost the "connreset" errors that were reported by httperf as well as the associated "broken pipe" meessages in the Apache error logs. The module now stands up properly when placed under a heavy load.
- 1.05 (Mon 29 Jan 2001) Kevin Walsh <kevin@cursor.biz>
  - Nothing more than a rename from `mod_minivend` to `mod_interchange`. (Changed "`mv_`" function names to "`ic_`" etc.)
- 1.04 (Tue 23 May 2000) Kevin Walsh <kevin@cursor.biz>
  - Changed to make the module work with Apache name-based `<VirtualHost>` entries that have been configured with the Apache `ServerPath` directive.
- 1.03-1i (Mon 02 Aug 1999) Francis J. Lacoste <francis.lacoste@iNsu.COM>
  - Last bugfixes.
- 1.02-1i (Mon 02 Aug 1999) Francis J. Lacoste <francis.lacoste@iNsu.COM>
  - Fixed spec files bugs.
- 1.00-1i (Mon 02 Aug 1999) Francis J. Lacoste <francis.lacoste@iNsu.COM>
  - Packaged for iNs/linux.

## 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.