0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<?xml version="1.0"?>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<modulesynopsis metafile="mod_substitute.xml.meta">

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<name>mod_substitute</name>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<description>Perform search and replace operations on response bodies</description>

2f54b716e4d3cb0dc99066638fed631e3cbec97cRichard Lowe<status>Experimental</status>

2f54b716e4d3cb0dc99066638fed631e3cbec97cRichard Lowe<sourcefile>mod_substitute.c</sourcefile>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<identifier>substitute_module</identifier>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<compatibility>Available in Apache HTTP Server 2.2.7 and later</compatibility>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<summary>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson <p><module>mod_substitute</module> provides a mechanism to perform

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson both regular expression and fixed string substitutions on

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson response bodies.</p>

2f54b716e4d3cb0dc99066638fed631e3cbec97cRichard Lowe</summary>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<directivesynopsis>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<name>Substitute</name>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<description>Pattern to filter the response content</description>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<syntax>Substitute <var>s/pattern/substitution/[infq]</var></syntax>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<contextlist><context>directory</context>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<context>.htaccess</context></contextlist>

0fd2682eef78b1fd2fbb5d69ccc03968820967aeMark J. Nelson<override>FileInfo</override>

2f54b716e4d3cb0dc99066638fed631e3cbec97cRichard Lowe

<usage>

<p>The <directive>Substitute</directive> directive specifies a

search and replace pattern to apply to the response body.</p>

<p>The meaning of the pattern can be modified by using any

combination of these flags:</p>

<dl>

<dt><code>i</code></dt>

<dd>Perform a case-insensitive match.</dd>

<dt><code>n</code></dt>

<dd>By default the pattern is treated as a regular expression.

Using the <code>n</code> flag forces the pattern to be treated

as a fixed string.</dd>

<dt><code>f</code></dt>

<dd>The <code>f</code> 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.</dd>

<dt><code>q</code></dt>

<dd>The <code>q</code> 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.</dd>

</dl>

<example><title>Example</title>

&lt;Location /&gt;

<indent>

AddOutputFilterByType SUBSTITUTE text/html<br />

Substitute s/foo/bar/ni<br />

</indent>

&lt;/Location&gt;

</example>

<p>If either the pattern or the substitution contain a slash

character then an alternative delimiter should be used:</p>

<example><title>Example of using an alternate delimiter</title>

&lt;Location /&gt;

<indent>

AddOutputFilterByType SUBSTITUTE text/html<br />

Substitute "s|&lt;BR */?&gt;|&lt;br /&gt;|i"

</indent>

&lt;/Location&gt;

</example>

<p>Backreferences can be used in the comparison and in the substituion,

when regular expressions are used, as illustrated in the following example: </p>

<example><title>Example of using backreferences and captures</title>

&lt;Location /&gt;

<indent>

AddOutputFilterByType SUBSTITUTE text/html<br />

# "foo=k,bar=k" -> "foo/bar=k" <br />

Substitute "s|foo=(\w+),bar=\1|foo/bar=$1"

</indent>

&lt;/Location&gt;

</example>

<p>A common use scenario for <code>mod_substitute</code> 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.</p>

<p>In this case, <code>mod_substutite</code> can be used to rewrite

those URLs into something that will work from the front end:</p>

<example><title>Rewriting URLs embedded in proxied content</title>

ProxyPass /blog/ http://internal.blog.example.com<br />

ProxyPassReverse /blog/ http://internal.blog.example.com/<br />

<br />

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

</example>

<p><directive module="mod_proxy">ProxyPassReverse</directive>

modifies any <code>Location</code> (redirect) headers that are sent

by the back-end server, and, in this example,

<code>Substitute</code> takes care of the rest of the problem by

fixing up the HTML response as well.</p>

</usage>

</directivesynopsis>

</modulesynopsis>