config.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html lang="en"><head>
   4 <title>mod_proxy_html</title>
   5 <style type="text/css">
   6 @import url(/index.css) ;
   7 </style>
   8 </head><body>
   9 <div id="apache">
  10 <h1>mod_proxy_html: Configuration</h1>
  11 <p><a href="./">mod_proxy_html</a> Version 2.4 (Sept 2004) and upwards.
  12 <span class="v3">Updates in Version 3 (Dec. 2006) are highlighted</span>.</p>
  13 <h2>Configuration Directives</h2>
  14 <p>The following can be used anywhere in an <strong>httpd.conf</strong>
  15 or included configuration file.</p>
  16 <dl>
  17 <dt>ProxyHTMLURLMap</dt>
  18 <dd>
  19 <p>Syntax:
  20 <code>ProxyHTMLURLMap   from-pattern    to-pattern [flags] [cond]</code></p>
  21 <p>This is the key directive for rewriting HTML links.  When parsing a document,
  22 whenever a link target matches <samp>from-pattern</samp>, the matching
  23 portion will be rewritten to <samp>to-pattern</samp>.</p>
  24 <p>Starting at version 2.0, this supports a wider range of pattern-matching
  25 and substitutions, including regular expression search and replace,
  26 controlled by the optional third <code>flags</code> argument.
  27 </p>
  28 <p class="v3">Starting at version 3.0, this also supports environment variable
  29 interpolation using the V and v flags, and rules may apply conditionally
  30 based on an environment variable.  Note that interpolation takes place
  31 before the parse starts, so variables set during the parse (e.g.
  32 using SSI directives) will not apply.  This flexible configuration
  33 is enabled by the <code>ProxyHTMLInterp</code> directive, or can
  34 be disabled for speed.</p>
  35 <h3>Flags for ProxyHTMLURLMap</h3>
  36 <p>Flags are case-sensitive.</p>
  37 <dl class="table">
  38 <dt>h</dt>
  39 <dd><p>Ignore HTML links (pass through unchanged)</p></dd>
  40 <dt>e</dt>
  41 <dd><p>Ignore scripting events (pass through unchanged)</p></dd>
  42 <dt>c</dt>
  43 <dd><p>Pass embedded script and style sections through untouched.</p></dd>
  44 <dt>L</dt>
  45 <dd><p>Last-match.  If this rule matches, no more rules are applied
  46 (note that this happens automatically for HTML links).</p></dd>
  47 <dt class="v3">l</dt>
  48 <dd class="v3">Opposite to L.  Overrides the one-change-only default
  49 behaviour with HTML links.</dd>
  50 <dt>R</dt>
  51 <dd><p>Use Regular Expression matching-and-replace.  <code>from-pattern</code>
  52 is a regexp, and <code>to-pattern</code> a replacement string that may be
  53 based on the regexp.  Regexp memory is supported: you can use brackets ()
  54 in the <code>from-pattern</code> and retrieve the matches with $1 to $9
  55 in the <code>to-pattern</code>.</p>
  56 <p>If R is not set, it will use string-literal search-and-replace, as in
  57 versions 1.x.  Logic is <em>starts-with</em> in HTML links, but
  58 <em>contains</em> in scripting events and embedded script and style sections.
  59 </p>
  60 </dd>
  61 <dt>x</dt>
  62 <dd><p>Use POSIX extended Regular Expressions.  Only applicable with R.</p></dd>
  63 <dt>i</dt>
  64 <dd><p>Case-insensitive matching.  Only applicable with R.</p></dd>
  65 <dt>n</dt>
  66 <dd><p>Disable regexp memory (for speed).  Only applicable with R.</p></dd>
  67 <dt>s</dt>
  68 <dd><p>Line-based regexp matching.  Only applicable with R.</p></dd>
  69 <dt>^</dt>
  70 <dd><p>Match at start only.  This applies only to string matching
  71 (not regexps) and is irrelevant to HTML links.</p></dd>
  72 <dt>$</dt>
  73 <dd><p>Match at end only.  This applies only to string matching
  74 (not regexps) and is irrelevant to HTML links.</p></dd>
  75 <dt class="v3">V</dt>
  76 <dd class="v3"><p>Interpolate environment variables in <code>to-pattern</code>.
  77 A string of the form <code>${varname|default}</code> will be replaced by the
  78 value of environment variable <code>varname</code>.  If that is unset, it
  79 is replaced by <code>default</code>.  The <code>|default</code> is optional.</p>
  80 <p>NOTE: interpolation will only be enabled if ProxyHTMLInterp is On.</p>
  81 </dd>
  82 <dt class="v3">v</dt>
  83 <dd class="v3"><p>Interpolate environment variables in <code>from-pattern</code>.
  84 Patterns supported are as above.</p>
  85 <p>NOTE: interpolation will only be enabled if ProxyHTMLInterp is On.</p>
  86 </dd>
  87 </dl>
  88 <h3 class="v3">Conditions for ProxyHTMLURLMap</h3>
  89 <p class="v3">The optional <code>cond</code> argument specifies a condition to
  90 test before the parse.  If a condition is unsatisfied, the URLMap
  91 will be ignored in this parse.</p>
  92 <p class="v3">The condition takes the form <code>[!]var[=val]</code>, and is
  93 satisfied if the value of environment variable <code>var</code>
  94 is <code>val</code>.  If the optional <code>=val</code> is omitted,
  95 then any value of <code>var</code> satisfies the condition, provided
  96 only it is set to something.  If the first character is <code>!</code>,
  97 the condition is reversed.</p>
  98 <p class="v3">NOTE: conditions will only be applied if ProxyHTMLInterp is On.</p>
  99 </dd>
 100 <dt class="v3">ProxyHTMLInterp</dt>
 101 <dd class="v3">
 102 <p>Syntax: <code>ProxyHTMLInterp On|Off</code></p>
 103 <p>Enables new (per-request) features of ProxyHTMLURLMap.</p>
 104 </dd>
 105 <dt>ProxyHTMLDoctype</dt>
 106 <dd>
 107 <p>Syntax: <code>ProxyHTMLDoctype HTML|XHTML [Legacy]</code></p>
 108 <p>Alternative Syntax: <code>ProxyHTMLDocType fpi [SGML|XML]</code></p>
 109 <p>In the first form, documents will be declared as HTML 4.01 or XHTML 1.0
 110 according to the option selected.  This option also determines whether
 111 HTML or XHTML syntax is used for output.   Note that the format of the
 112 documents coming from the backend server is immaterial: the parser will
 113 deal with it automatically.  If the optional second argument is set to
 114 "Legacy", documents will be declared "Transitional", an option that may
 115 be necessary if you are proxying pre-1998 content or working with defective
 116 authoring/publishing tools.</p>
 117 <p>In the second form, it will insert your own <abbr
 118 title="Formal Public Identifier">FPI</abbr>.  The optional second
 119 argument determines whether SGML/HTML or XML/XHTML syntax will be used.</p>
 120 <p>Starting at version 2.0, the default is changed to omitting any FPI,
 121 on the grounds that no FPI is better than a bogus one.  If your backend
 122 generates decent HTML or XHTML, set it accordingly.</p>
 123 <p class="v3">From version 3, if the first form is used, mod_proxy_html
 124 will also clean up the HTML to the specified standard.  It cannot
 125 fix every error, but it will strip out bogus elements and attributes.
 126 It will also optionally log other errors at <tt>LogLevel Debug</tt>.</p>
 127 </dd>
 128 <dt>ProxyHTMLFixups</dt>
 129 <dd>
 130 <p>Syntax: <code>ProxyHTMLFixups [lowercase] [dospath] [reset]</code></p>
 131 <p>This directive takes one to three arguments as follows:</p>
 132 <ul>
 133 <li><code>lowercase</code> Urls are rewritten to lowercase</li>
 134 <li><code>dospath</code> Backslashes in URLs are rewritten to forward slashes.</li>
 135 <li><code>reset</code> Unset any options set at a higher level in the configuration.</li>
 136 </ul>
 137 <p>Take care when using these.  The fixes will correct certain authoring
 138 mistakes, but risk also erroneously fixing links that were correct to start with.
 139 Only use them if you know you have a broken backend server.</p>
 140 </dd>
 141 <dt>ProxyHTMLMeta</dt>
 142 <dd><p>Syntax <code>ProxyHTMLMeta [On|Off]</code></p>
 143 <p>Parses <code>&lt;meta http-equiv ...&gt;</code> elements to real HTTP
 144 headers.</p>
 145 <p class="v3">In version 3, this is also tied in with the improved
 146 <a href="guide.html#charset">internationalisation support</a>, and is
 147 required to support some character encodings.</p>
 148 </dd>
 149 <dt>ProxyHTMLExtended</dt>
 150 <dd><p>Syntax <code>ProxyHTMLExtended [On|Off]</code></p>
 151 <p>Set to <code>Off</code>, this gives the same behaviour as 1.x versions
 152 of mod_proxy_html.  HTML links are rewritten according the ProxyHTMLURLMap
 153 directives, but links appearing in Javascript and CSS are ignored.</p>
 154 <p>Set to <code>On</code>, all scripting events and embedded scripts or
 155 stylesheets are also processed by the ProxyHTMLURLMap rules, according to
 156 the flags set for each rule.  Since this requires more parsing, performance
 157 will be best if you only enable it when strictly necessary.</p>
 158 </dd>
 159 <dt>ProxyHTMLStripComments</dt>
 160 <dd><p>Syntax <code>ProxyHTMLStripComments [On|Off]</code></p>
 161 <p>This directive will cause mod_proxy_html to strip HTML comments.
 162 Note that this will also kill off any scripts or styles embedded in
 163 comments (a bogosity introduced in 1995/6 with Netscape 2 for the
 164 benefit of then-older browsers, but still in use today).
 165 It may also interfere with comment-based processors such as SSI or ESI:
 166 be sure to run any of those <em>before</em> mod_proxy_html in the
 167 filter chain if stripping comments!</p>
 168 </dd>
 169 <dt>ProxyHTMLLogVerbose</dt>
 170 <dd><p>Syntax <code>ProxyHTMLLogVerbose [On|Off]</code></p>
 171 <p>Turns on verbose logging.  This causes mod_proxy_html to make
 172 error log entries (at <code>LogLevel Info</code>) about charset
 173 detection and about all meta substitutions and rewrites made.
 174 When Off, only errors and warnings (if any) are logged.</p>
 175 </dd>
 176 <dt>ProxyHTMLBufSize</dt>
 177 <dd><p>Syntax <code>ProxyHTMLBufSize nnnn</code></p>
 178 <p>Set the buffer size increment for buffering inline stylesheets and scripts.</p>
 179 <p>In order to parse non-HTML content (stylesheets and scripts), mod_proxy_html
 180 has to read the entire script or stylesheet into a buffer.  This buffer will
 181 be expanded as necessary to hold the largest script or stylesheet in a page,
 182 in increments of [nnnn] as set by this directive.</p>
 183 <p>The default is 8192, and will work well for almost all pages.  However,
 184 if you know you're proxying a lot of pages containing stylesheets and/or
 185 scripts bigger than 8K (that is, for a single script or stylesheet,
 186 NOT in total), it will be more efficient to set a larger buffer
 187 size and avoid the need to resize the buffer dynamically during a request.
 188 </p>
 189 </dd>
 190 <dt class="v3">ProxyHTMLEvents</dt>
 191 <dd class="v3">
 192 <p>Syntax <code>ProxyHTMLEvents attr [attr ...]</code></p>
 193 <p>Specifies one or more attributes to treat as scripting events and
 194 apply URLMaps to where appropriate.  You can specify any number of
 195 attributes in one or more <code>ProxyHTMLEvents</code> directives.
 196 The <a href="/svn/apache/filters/proxy_html/">sample configuration</a>
 197 defines the events in standard HTML 4 and XHTML 1.</p>
 198 </dd>
 199 <dt class="v3">ProxyHTMLLinks</dt>
 200 <dd class="v3">
 201 <p>Syntax <code>ProxyHTMLLinks elt attr [attr ...]</code></p>
 202 <p>Specifies elements that have URL attributes that should be rewritten
 203 using standard URLMaps as in versions 1 and 2 of mod_proxy_html.
 204 You will need one <code>ProxyHTMLLinks</code> directive per element,
 205 but it can have any number of attributes.  The <a
 206 href="/svn/apache/filters/proxy_html/">sample configuration</a>
 207 defines the HTML links for standard HTML 4 and XHTML 1.</p>
 208 </dd>
 209 <dt class="v3">ProxyHTMLCharsetAlias</dt>
 210 <dd class="v3">
 211 <p>Syntax <code>ProxyHTMLCharsetAlias charset alias [alias ...]</code></p>
 212 <p>This server-wide directive aliases one or more charset to another
 213 charset.  This enables encodings not recognised by libxml2 to be handled
 214 internally by libxml2's charset support using the translation table for
 215 a recognised charset.</p>
 216 <p>For example, Latin 1 (<tt>ISO-8859-1</tt>) is supported by libxml2.
 217 Microsoft's <tt>Windows-1252</tt> is almost identical and can be supported
 218 by aliasing it:<br />
 219 <code>ProxyHTMLCharsetAlias ISO-8859-1 Windows-1252</code></p>
 220 </dd>
 221 <dt class="v3">ProxyHTMLCharsetDefault</dt>
 222 <dd class="v3">
 223 <p>Syntax <code>ProxyHTMLCharsetDefault name</code></p>
 224 <p>This defines the default encoding to assume when absolutely no charset
 225 information is available from the backend server.  The default value for
 226 this is <code>ISO-8859-1</code>, as specified in HTTP/1.0 and assumed in
 227 earlier mod_proxy_html versions.</p>
 228 </dd>
 229 <dt class="v3">ProxyHTMLCharsetOut</dt>
 230 <dd class="v3">
 231 <p>Syntax <code>ProxyHTMLCharsetOut name</code></p>
 232 <p>This selects an encoding for mod_proxy_html output.  It should not
 233 normally be used, as any change from the default <code>UTF-8</code>
 234 (Unicode - as used internally by libxml2) will impose an additional
 235 processing overhead.  The special token <code>ProxyHTMLCharsetOut *</code>
 236 will generate output using the same encoding as the input.</p>
 237 </dd>
 238 <dt class="v3">ProxyHTMLStartParse</dt>
 239 <dd class="v3">
 240 <p>Syntax <code>ProxyHTMLStartParse element [elt*]</code></p>
 241 <p>Specify that the HTML parser should start at the first instance
 242 of any of the elements specified.  This can be used where a broken
 243 backend inserts leading junk that messes up the parser (<a
 244 href="http://bahumbug.wordpress.com/2006/10/12/mod_proxy_html-revisited/"
 245 >example here</a>).</p>
 246 </dd>
 247 </dl>
 248 <h3>Other Configuration</h3>
 249 <p class="v3">Normally, mod_proxy_html will refuse to run when not
 250 in a proxy or when the contents are not HTML.  This can be overridden
 251 (at your own risk) by setting the environment variable
 252 <tt>PROXY_HTML_FORCE</tt> (e.g. with the <tt>SetEnv</tt> directive).</p>
 253 </div>
 254 </body></html>