mod_replace: Documentation

What is mod_replace?

mod_replace is a simple Apache 2.0.x filter module which has originally been developed based on mod_ext_filter. The initial purpose has been to support an Apache-based reverse proxy with mod_rewrite. Absolute URLs contained in the HTTP body could not be handled with mod_rewrite. Thus there was a slow mod_perl solution to rewrite the body content.

The C-based mod_replace in its original version provided a much faster approach to this problem. Since then HTTP header replacement (eg. for Cookie adjustments) have been added.

Until now, mod_replace is only used in addition to mod_proxy to provide an improved reverse proxy experience. It greatly helps to sanitize ill behaving web servers / applications. Examples: absolute links within web pages, absolute links in HTTP headers which aren't controlled by mod_proxy (eg. Set-Cookie).

How does it work?

There are up to date three destinct mechanisms to do pattern replacement within mod_replace. Those are:

• HTTP response body replacements
  • The most powerful replacements, since there's support for subpatterns
  • most commonly used feature of mod_replace
  • based upon Apache's filter mechanism (Output Filter)
• HTTP response header replacements
  • Suitable for rewriting HTTP header information of server responses
  • No support for subpatterns (still to come)
  • based upon Apache's filter mechanism (Output Filter)
• HTTP request header replacements
  • Suitable for rewriting HTTP header information of client requests before they reach the server (eg. on a reverse proxy)
  • NOT based upon Apache's filter mechanism

When a HTTP response is routed through an HTTP body filter, there are a couple of things you should be aware of:

• The filter has to assemble the whole response before it starts processing the content. Apache uses buckets to store parts of the data. If you process only those buckets, you certainly get into trouble when a pattern extends over the edges of those buckets. Thus you have to concatenate all buckets to a single data structure. This takes time and resources!
• Multiple patterns for the same filter definition are concatenated using a linked list. This means that the patterns are processed sequentially. The pattern first defined will be the pattern first processed by the filter. Once this run is complete, the next pattern processes the already altered data. This means, if you define multiple patterns, each page has to be processed multiple times. Try to solve you problem with as few patterns as possible.
• Once all patterns are processed the data is passed to the next filter. If this is another HTTP body filter, the whole story is repeated.

This means, that you can define multiple patterns for a single filter definition. You simply create a new ReplacePattern with the same name as the previous one (see examples below).

Using an HTTP response header filter, the process is almost the same as above. The patterns are sequentially matched against the data and the necessary replacements take place before the next pattern is processed.

One special feature to note with this filter is, that is doesn't stop looking for matching headers once it found one (which would make sense, according to the HTTP standard, there is only one occurrence of an HTTP header per response). There is one commonly used situation where there are multiple occurrences of the same HTTP header, each with different content: Set-Cookie.

The HTTP request header filter is quite different from the other filters, because it doesn't use the same mechanism within Apache. If it would use the filter mechanism (eg. as an input filter), any request that is also routed through mod_proxy (using Apache as a reverse proxy) will first be processed by mod_proxy and then by mod_replace. Any modifications applied to the HTTP header then are completely ignored by mod_proxy, since it already has created the request to the origin server and the modifications by mod_replace are simply discarded.

The mechanism used by mod_replace for modifications of the request header allow you to alter the HTTP header before mod_proxy processes the request. The same rules apply for the patterns: Multiple patterns are linked together in a linked list and are processed sequentially. Note: There is only one "filter" for all patterns. You don't need to create a named definition and you don't have to set the output filter. But you won't be able to specify additional parameters.

Configuration

Configuring an HTTP body filter

Syntax

ReplaceFilterDefine <name> [<options> ...]

ReplacePattern <name> <pattern> <string>

SetOutputFilter <name>[;<name>]

Examples

  ReplaceFilterDefine revproxy CaseIgnore intype=text/html
  ReplacePattern revproxy "(http|https)://origin.server/" "\1://revproxy/"
  SetOutputFilter revproxy

  ReplaceFilterDefine multiple CaseIgnore intype=text/html
  ReplacePattern multiple "(http|https)://origin.server/" "\1://revproxy/"
  ReplacePattern multiple "ftp://origin.server" "ftp://public.server/pub"
  SetOutputFilter multiple

Configuring an HTTP header filter

Syntax

ReplaceFilterDefine <name> [<options> ...]

HeaderReplacePattern <name> <header> <pattern> <string>

SetOutputFilter <name>[;<name>]

Examples

  ReplaceFilterDefine revproxy CaseIgnore
  HeaderReplacePattern revproxy Set-Cookie \
    " domain=[.]?server.com" \
    " domain=revproxy.com"
  SetOutputFilter revproxy

    Date: Wed, 07 Apr 2004 13:08:01 GMT
    Server: Apache/1.3.29
    Vary: Accept-Encoding,User-agent
    Set-Cookie: UID=0815; domain=server.com; path=/
    Connection: close
    Content-Type: text/html; charset=iso-8859-1
   

    Date: Wed, 07 Apr 2004 13:08:01 GMT
    Server: Apache/1.3.29
    Vary: Accept-Encoding,User-agent
    Set-Cookie: UID=0815; domain=revproxy.com; path=/
    Connection: close
    Content-Type: text/html; charset=iso-8859-1
   

Configuring an HTTP request header filter

Syntax

RequestHeaderPattern <header> <pattern> <string>

Examples

  RequestHeaderPattern Cookie " UID=0815" " UID=007"