docs/manual/mod/mod_proxy_scgi.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_proxy_scgi.xml.meta">
  24
  25 <name>mod_proxy_scgi</name>
  26 <description>SCGI gateway module for <module>mod_proxy</module></description>
  27 <status>Extension</status>
  28 <sourcefile>mod_proxy_scgi.c</sourcefile>
  29 <identifier>proxy_scgi_module</identifier>
  30 <compatibility>Available in version 2.3 and later</compatibility>
  31
  32 <summary>
  33     <p>This module <em>requires</em> the service of <module
  34     >mod_proxy</module>. It provides support for the
  35     <a href="http://python.ca/scgi/protocol.txt">SCGI protocol, version
  36     1</a>.</p>
  37
  38     <p>Thus, in order to get the ability of handling the SCGI protocol,
  39     <module>mod_proxy</module> and <module>mod_proxy_scgi</module> have to
  40     be present in the server.</p>
  41
  42     <note type="warning"><title>Warning</title>
  43       <p>Do not enable proxying until you have <a
  44       href="mod_proxy.html#access">secured your server</a>. Open proxy
  45       servers are dangerous both to your network and to the Internet at
  46       large.</p>
  47     </note>
  48 </summary>
  49
  50 <seealso><module>mod_proxy</module></seealso>
  51 <seealso><module>mod_proxy_balancer</module></seealso>
  52
  53 <section id="examples"><title>Examples</title>
  54     <p>Remember, in order to make the following examples work, you have to
  55     enable <module>mod_proxy</module> and <module>mod_proxy_scgi</module>.</p>
  56
  57     <example><title>Simple gateway</title>
  58       ProxyPass /scgi-bin/ scgi://localhost:4000/
  59     </example>
  60
  61     <p>The balanced gateway needs <module>mod_proxy_balancer</module> in
  62     addition to the already mentioned proxy modules.</p>
  63
  64     <example><title>Balanced gateway</title>
  65     ProxyPass /scgi-bin/ balancer://somecluster/<br />
  66     &lt;Proxy balancer://somecluster/&gt;<br />
  67     <indent>
  68         BalancerMember scgi://localhost:4000/<br />
  69         BalancerMember scgi://localhost:4001/<br />
  70     </indent>
  71     &lt;/Proxy&gt;
  72     </example>
  73 </section>
  74
  75 <directivesynopsis>
  76 <name>ProxySCGISendfile</name>
  77 <description>Enable evaluation of <var>X-Sendfile</var> pseudo response
  78 header</description>
  79 <syntax>ProxySCGISendfile On|Off|<var>Headername</var></syntax>
  80 <default>ProxySCGISendfile Off</default>
  81 <contextlist><context>server config</context><context>virtual host</context>
  82 <context>directory</context></contextlist>
  83
  84 <usage>
  85     <p>The <directive>ProxySCGISendfile</directive> directive enables the
  86     SCGI backend to let files serve directly by the gateway. This is useful
  87     performance purposes -- the httpd can use <code>sendfile</code> or other
  88     optimizations, which are not possible if the file comes over the backend
  89     socket.</p>
  90     <p>The <directive>ProxySCGISendfile</directive> argument determines the
  91     gateway behaviour:</p>
  92     <dl>
  93     <dt><code>Off</code></dt>
  94     <dd>No special handling takes place.</dd>
  95
  96     <dt><code>On</code></dt>
  97     <dd>The gateway looks for a backend response header called
  98     <code>X-Sendfile</code> and interprets the value as filename to serve. The
  99     header is removed from the final response headers. This is equivalent to
 100     <code>ProxySCGIRequest X-Sendfile</code>.</dd>
 101
 102     <dt>anything else</dt>
 103     <dd>Similar to <code>On</code>, but instead of the hardcoded header name
 104     the argument is applied as header name.</dd>
 105     </dl>
 106
 107     <example><title>Example</title>
 108     # Use the default header (X-Sendfile)<br />
 109     ProxySCGISendfile On<br />
 110     <br />
 111     # Use a different header<br />
 112     ProxySCGISendfile X-Send-Static
 113     </example>
 114 </usage>
 115 </directivesynopsis>
 116
 117 <directivesynopsis>
 118 <name>ProxySCGIInternalRedirect</name>
 119 <description>Enable or disable internal redirect responses from the
 120 backend</description>
 121 <syntax>ProxySCGIInternalRedirect On|Off</syntax>
 122 <default>ProxySCGIInternalRedirect On</default>
 123 <contextlist><context>server config</context><context>virtual host</context>
 124 <context>directory</context></contextlist>
 125
 126 <usage>
 127     <p>The <directive>ProxySCGIInternalRedirect</directive> enables the backend
 128     to internally redirect the gateway to a different URL. This feature
 129     origins in <module>mod_cgi</module>, which internally redirects the
 130     response, if the response status is <code>OK</code> (<code>200</code>) and
 131     the response contains a <code>Location</code> header and its value starts
 132     with a slash (<code>/</code>). This value is interpreted as a new local
 133     URL the apache internally redirects to.</p>
 134
 135     <p><module>mod_proxy_scgi</module> does the same as
 136     <module>mod_cgi</module> in this regard, except that you can turn off the
 137     feature.</p>
 138
 139     <example><title>Example</title>
 140     ProxySCGIInternalRedirect Off
 141     </example>
 142 </usage>
 143 </directivesynopsis>
 144
 145 </modulesynopsis>