| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <modulesynopsis metafile="mod_substitute.xml.meta"> |
| |
| <name>mod_substitute</name> |
| <description>Perform search and replace operations on response bodies</description> |
| <status>Extension</status> |
| <sourcefile>mod_substitute.c</sourcefile> |
| <identifier>substitute_module</identifier> |
| <compatibility>Available in Apache HTTP Server 2.2.7 and later</compatibility> |
| |
| <summary> |
| <p><module>mod_substitute</module> provides a mechanism to perform |
| both regular expression and fixed string substitutions on |
| response bodies.</p> |
| </summary> |
| |
| <directivesynopsis> |
| <name>Substitute</name> |
| <description>Pattern to filter the response content</description> |
| <syntax>Substitute <var>s/pattern/substitution/[infq]</var></syntax> |
| <contextlist><context>directory</context> |
| <context>.htaccess</context></contextlist> |
| <override>FileInfo</override> |
| |
| <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 <code>mod_substitute</code> 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 <code>mod_substitute</code> 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> |
| <highlight language="config"> |
| <Location "/"> |
| AddOutputFilterByType SUBSTITUTE text/html |
| Substitute "s/foo/bar/ni" |
| </Location> |
| </highlight> |
| </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> |
| <highlight language="config"> |
| <Location "/"> |
| AddOutputFilterByType SUBSTITUTE text/html |
| Substitute "s|<BR */?>|<br />|i" |
| </Location> |
| </highlight> |
| </example> |
| |
| <p>Backreferences can be used in the comparison and in the substitution, |
| when regular expressions are used, as illustrated in the following example: </p> |
| <example><title>Example of using backreferences and captures</title> |
| <highlight language="config"> |
| <Location "/"> |
| AddOutputFilterByType SUBSTITUTE text/html |
| # "foo=k,bar=k" -> "foo/bar=k" |
| Substitute "s|foo=(\w+),bar=\1|foo/bar=$1" |
| </Location> |
| </highlight> |
| </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_substitute</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> |
| <highlight language="config"> |
| 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" |
| </highlight> |
| </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, |
| <directive>Substitute</directive> takes care of the rest of the problem by |
| fixing up the HTML response as well.</p> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SubstituteMaxLineLength</name> |
| <description>Set the maximum line size</description> |
| <syntax>SubstituteMaxLineLength <var>bytes</var>(b|B|k|K|m|M|g|G)</syntax> |
| <default>SubstituteMaxLineLength 1m</default> |
| <contextlist><context>directory</context> |
| <context>.htaccess</context></contextlist> |
| <override>FileInfo</override> |
| <compatibility>Available in httpd 2.4.11 and later</compatibility> |
| |
| <usage> |
| <p>The maximum line size handled by <module>mod_substitute</module> |
| is limited to restrict memory use. The limit can be configured |
| using <directive>SubstituteMaxLineLength</directive>. |
| The value can be given as the number of bytes and can be suffixed |
| with a single letter <code>b</code>, <code>B</code>, <code>k</code>, |
| <code>K</code>, <code>m</code>, <code>M</code>, <code>g</code>, |
| <code>G</code> to provide the size in bytes, kilobytes, megabytes |
| or gigabytes respectively.</p> |
| |
| <example><title>Example</title> |
| <highlight language="config"> |
| <Location "/"> |
| AddOutputFilterByType SUBSTITUTE text/html |
| SubstituteMaxLineLength 10m |
| Substitute "s/foo/bar/ni" |
| </Location> |
| </highlight> |
| </example> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SubstituteInheritBefore</name> |
| <description>Change the merge order of inherited patterns</description> |
| <syntax>SubstituteInheritBefore on|off</syntax> |
| <default>SubstituteInheritBefore off</default> |
| <contextlist><context>directory</context> |
| <context>.htaccess</context></contextlist> |
| <override>FileInfo</override> |
| <compatibility>Available in httpd 2.4.17 and later</compatibility> |
| |
| <usage> |
| <p>Whether to apply the inherited <directive module="mod_substitute">Substitute</directive> |
| patterns first (<code>on</code>), or after the ones of the current |
| context (<code>off</code>). |
| <directive>SubstituteInheritBefore</directive> is itself inherited, |
| hence contexts that inherit it (those that don't specify their own |
| <directive>SubstituteInheritBefore</directive> value) will apply the |
| closest defined merge order.</p> |
| </usage> |
| </directivesynopsis> |
| |
| </modulesynopsis> |