c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<?xml version="1.0"?>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<modulesynopsis metafile="mod_substitute.xml.meta">

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<name>mod_substitute</name>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<description>Perform search and replace operations on response bodies</description>

4164e3432a828eb32e70e777927a23b93a77494fsf<status>Extension</status>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<sourcefile>mod_substitute.c</sourcefile>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<identifier>substitute_module</identifier>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<summary>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl <p><module>mod_substitute</module> provides a mechanism to perform

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl both regular expression and fixed string substitutions on

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl response bodies.</p>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl</summary>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<directivesynopsis>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<name>Substitute</name>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<description>Pattern to filter the response content</description>

ca33b922ae8ad1b24a8235b656b0ac6f82915355jim<syntax>Substitute <var>s/pattern/substitution/[infq]</var></syntax>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<contextlist><context>directory</context>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<context>.htaccess</context></contextlist>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<override>FileInfo</override>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl<usage>

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

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

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim

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

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl combination of these flags:</p>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl <dl>

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

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

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

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

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

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl as a fixed string.</dd>

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

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl <dd>The <code>f</code> flag causes mod_substitute to flatten the

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl result of a substitution allowing for later substitutions to

ca33b922ae8ad1b24a8235b656b0ac6f82915355jim take place on the boundary of this one. This is the default.</dd>

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

ca33b922ae8ad1b24a8235b656b0ac6f82915355jim <dd>The <code>q</code> flag causes mod_substitute to not

ca33b922ae8ad1b24a8235b656b0ac6f82915355jim flatten the buckets after each substitution. This can

ca33b922ae8ad1b24a8235b656b0ac6f82915355jim result in much faster response and a decrease in memory

ca33b922ae8ad1b24a8235b656b0ac6f82915355jim utilization, but should only be used if there is no possibility

ca33b922ae8ad1b24a8235b656b0ac6f82915355jim that the result of one substitution will ever match a pattern

ca33b922ae8ad1b24a8235b656b0ac6f82915355jim or regex of a subsequent one.</dd>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl </dl>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl <example><title>Example</title>

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh <highlight language="config">

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar&lt;Location "/"&gt;

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh AddOutputFilterByType SUBSTITUTE text/html

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh Substitute s/foo/bar/ni

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh&lt;/Location&gt;

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh </highlight>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl </example>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim

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

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

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim

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

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh <highlight language="config">

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar&lt;Location "/"&gt;

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh AddOutputFilterByType SUBSTITUTE text/html

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

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh&lt;/Location&gt;

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh </highlight>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl </example>

f97b24463c41ab08129805bc63069b59c3ee0b48rbowen

18ee8bb3db5cc3b04291f89301bd5d14dc271066lgentis <p>Backreferences can be used in the comparison and in the substitution,

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

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

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh <highlight language="config">

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar&lt;Location "/"&gt;

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh AddOutputFilterByType SUBSTITUTE text/html

5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar # "foo=k,bar=k" -> "foo/bar=k"

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

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh&lt;/Location&gt;

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh </highlight>

206f0fb731ca7d2d2b2378cbd5b2882080490bd7covener </example>

206f0fb731ca7d2d2b2378cbd5b2882080490bd7covener

f97b24463c41ab08129805bc63069b59c3ee0b48rbowen <p>A common use scenario for <code>mod_substitute</code> is the

f97b24463c41ab08129805bc63069b59c3ee0b48rbowen situation in which a front-end server proxies requests to a back-end

f97b24463c41ab08129805bc63069b59c3ee0b48rbowen server which returns HTML with hard-coded embedded URLs that refer

f97b24463c41ab08129805bc63069b59c3ee0b48rbowen to the back-end server. These URLs don't work for the end-user,

f97b24463c41ab08129805bc63069b59c3ee0b48rbowen since the back-end server is unreachable.</p>

f97b24463c41ab08129805bc63069b59c3ee0b48rbowen

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

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

f97b24463c41ab08129805bc63069b59c3ee0b48rbowen

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

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh <highlight language="config">

2fae9d127f7143fabe8f73958eb9bde31df17d41coarProxyPass "/blog/" "http://internal.blog.example.com"

2fae9d127f7143fabe8f73958eb9bde31df17d41coarProxyPassReverse "/blog/" "http://internal.blog.example.com/"

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh

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

ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh </highlight>

f97b24463c41ab08129805bc63069b59c3ee0b48rbowen </example>

f97b24463c41ab08129805bc63069b59c3ee0b48rbowen

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

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

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

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

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

f97b24463c41ab08129805bc63069b59c3ee0b48rbowen

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl</usage>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl</directivesynopsis>

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung<directivesynopsis>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung<name>SubstituteMaxLineLength</name>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung<description>Set the maximum line size</description>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung<syntax>SubstituteMaxLineLength <var>bytes</var>(b|B|k|K|m|M|g|G)</syntax>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung<default>SubstituteMaxLineLength 1m</default>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung<contextlist><context>directory</context>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung<context>.htaccess</context></contextlist>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung<override>FileInfo</override>

0d747e805cfc207e1b210904a3f4dd95f176b562jailletc<compatibility>Available in httpd 2.4.11 and later</compatibility>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung<usage>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung <p>The maximum line size handled by <module>mod_substitute</module>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung is limited to restrict memory use. The limit can be configured

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung using <directive>SubstituteMaxLineLength</directive>.

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung The value can be given as the number of bytes and can be suffixed

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung with a single letter <code>b</code>, <code>B</code>, <code>k</code>,

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung <code>K</code>, <code>m</code>, <code>M</code>, <code>g</code>,

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung <code>G</code> to provide the size in bytes, kilobytes, megabytes

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung or gigabytes respectively.</p>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung <example><title>Example</title>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung <highlight language="config">

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar&lt;Location "/"&gt;

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung AddOutputFilterByType SUBSTITUTE text/html

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung SubstituteMaxLineLength 10m

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung Substitute s/foo/bar/ni

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung&lt;/Location&gt;

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung </highlight>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung </example>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung</usage>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung</directivesynopsis>

643ed38ed1c7634b7306f1eb1058e1ce8c543686rjung

c3aaccf2d58cbd445efed832c4028787ac9f1542noodl</modulesynopsis>