mod_substitute - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

# Apache Module mod_substitute

Available Languages: en | fr

Description: | Perform search and replace operations on response bodies
Status: | Extension
Module Identifier: | substitute_module
Source File: | mod_substitute.c
Compatibility: | Available in Apache HTTP Server 2.2.7 and later

### Summary

`mod_substitute` provides a mechanism to perform both regular expression and fixed string substitutions on response bodies.

### Directives

### Bugfix checklist

- httpd changelog
- Known issues
- Report a bug

### See also

- Comments

## Substitute Directive

Description: | Pattern to filter the response content
Syntax: | `Substitute s/pattern/substitution/[infq]`
Context: | directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_substitute

The `Substitute` directive specifies a search and replace pattern to apply to the response body.

The meaning of the pattern can be modified by using any combination of these flags:

`i`
  Perform a case-insensitive match.
`n`
  By default the pattern is treated as a regular expression. Using the `n` flag forces the pattern to be treated as a fixed string.
`f`
  The `f` flag causes `mod_substitute` to flatten the result of a substitution allowing for later substitutions to take place on the boundary of this one. This is the default.
`q`
  The `q` flag causes `mod_substitute` to not flatten the buckets after each substitution. This can result in much faster response and a decrease in memory utilization, but should only be used if there is no possibility that the result of one substitution will ever match a pattern or regex of a subsequent one.

The substitution may contain literal text and regular expression backreferences

### Example

    <Location "/">
        AddOutputFilterByType SUBSTITUTE text/html
        Substitute "s/foo/bar/ni"
    </Location>

The character which is used to separate (or "delimit") the various parts of the substitution string is referred to as the "delimiter", and it is most common to use a slash for this purpose.

If either the pattern or the substitution contain a slash character then an alternative delimiter may be used to make the directive more readable:

### Example of using an alternate delimiter

    <Location "/">
        AddOutputFilterByType SUBSTITUTE text/html
        Substitute "s|<BR */?>|<br />|i"
    </Location>

Backreferences can be used in the comparison and in the substitution, when regular expressions are used, as illustrated in the following example:

### Example of using backreferences and captures

    <Location "/">
        AddOutputFilterByType SUBSTITUTE text/html
        # "foo=k,bar=k" -> "foo/bar=k"
        Substitute "s|foo=(\w+),bar=\1|foo/bar=$1|"
    </Location>

A common use scenario for `mod_substitute` is the situation in which a front-end server proxies requests to a back-end server which returns HTML with hard-coded embedded URLs that refer to the back-end server. These URLs don't work for the end-user, since the back-end server is unreachable.

In this case, `mod_substitute` can be used to rewrite those URLs into something that will work from the front end:

### Rewriting URLs embedded in proxied content

    ProxyPass        "/blog/" "http://internal.blog.example.com/"
    ProxyPassReverse "/blog/" "http://internal.blog.example.com/"

    Substitute "s|http://internal.blog.example.com/|http://www.example.com/blog/|i"

`ProxyPassReverse` modifies any `Location` (redirect) headers that are sent by the back-end server, and, in this example, `Substitute` takes care of the rest of the problem by fixing up the HTML response as well.

## SubstituteInheritBefore Directive

Description: | Change the merge order of inherited patterns
Syntax: | `SubstituteInheritBefore on|off`
Default: | `SubstituteInheritBefore off`
Context: | directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_substitute
Compatibility: | Available in httpd 2.4.17 and later

Whether to apply the inherited `Substitute` patterns first (`on`), or after the ones of the current context (`off`). `SubstituteInheritBefore` is itself inherited, hence contexts that inherit it (those that don't specify their own `SubstituteInheritBefore` value) will apply the closest defined merge order.

## SubstituteMaxLineLength Directive

Description: | Set the maximum line size
Syntax: | `SubstituteMaxLineLength bytes(b|B|k|K|m|M|g|G)`
Default: | `SubstituteMaxLineLength 1m`
Context: | directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_substitute
Compatibility: | Available in httpd 2.4.11 and later

The maximum line size handled by `mod_substitute` is limited to restrict memory use. The limit can be configured using `SubstituteMaxLineLength`. The value can be given as the number of bytes and can be suffixed with a single letter `b`, `B`, `k`, `K`, `m`, `M`, `g`, `G` to provide the size in bytes, kilobytes, megabytes or gigabytes respectively.

### Example

    <Location "/">
        AddOutputFilterByType SUBSTITUTE text/html
        SubstituteMaxLineLength 10m
        Substitute "s/foo/bar/ni"
    </Location>

Available Languages: en | fr

## Comments

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Libera.chat, or sent to our mailing lists.