granicus.if.org Git - apache/blob - 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.2.14 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> and
  62     at least one load balancer algorithm module, such as
  63     <module>mod_lbmethod_byrequests</module>, in addition to the proxy
  64     modules listed above.  <module>mod_lbmethod_byrequests</module> is the
  65     default, and will be used for this example configuration.</p>
  66
  67     <example><title>Balanced gateway</title>
  68     ProxyPass /scgi-bin/ balancer://somecluster/<br />
  69     &lt;Proxy balancer://somecluster/&gt;<br />
  70     <indent>
  71         BalancerMember scgi://localhost:4000/<br />
  72         BalancerMember scgi://localhost:4001/<br />
  73     </indent>
  74     &lt;/Proxy&gt;
  75     </example>
  76 </section>
  77
  78 <directivesynopsis>
  79 <name>ProxySCGISendfile</name>
  80 <description>Enable evaluation of <var>X-Sendfile</var> pseudo response
  81 header</description>
  82 <syntax>ProxySCGISendfile On|Off|<var>Headername</var></syntax>
  83 <default>ProxySCGISendfile Off</default>
  84 <contextlist><context>server config</context><context>virtual host</context>
  85 <context>directory</context></contextlist>
  86
  87 <usage>
  88     <p>The <directive>ProxySCGISendfile</directive> directive enables the
  89     SCGI backend to let files serve directly by the gateway. This is useful
  90     performance purposes -- the httpd can use <code>sendfile</code> or other
  91     optimizations, which are not possible if the file comes over the backend
  92     socket.</p>
  93     <p>The <directive>ProxySCGISendfile</directive> argument determines the
  94     gateway behaviour:</p>
  95     <dl>
  96     <dt><code>Off</code></dt>
  97     <dd>No special handling takes place.</dd>
  98
  99     <dt><code>On</code></dt>
 100     <dd>The gateway looks for a backend response header called
 101     <code>X-Sendfile</code> and interprets the value as filename to serve. The
 102     header is removed from the final response headers. This is equivalent to
 103     <code>ProxySCGISendfile X-Sendfile</code>.</dd>
 104
 105     <dt>anything else</dt>
 106     <dd>Similar to <code>On</code>, but instead of the hardcoded header name
 107     the argument is applied as header name.</dd>
 108     </dl>
 109
 110     <example><title>Example</title>
 111     # Use the default header (X-Sendfile)<br />
 112     ProxySCGISendfile On<br />
 113     <br />
 114     # Use a different header<br />
 115     ProxySCGISendfile X-Send-Static
 116     </example>
 117 </usage>
 118 </directivesynopsis>
 119
 120 <directivesynopsis>
 121 <name>ProxySCGIInternalRedirect</name>
 122 <description>Enable or disable internal redirect responses from the
 123 backend</description>
 124 <syntax>ProxySCGIInternalRedirect On|Off</syntax>
 125 <default>ProxySCGIInternalRedirect On</default>
 126 <contextlist><context>server config</context><context>virtual host</context>
 127 <context>directory</context></contextlist>
 128
 129 <usage>
 130     <p>The <directive>ProxySCGIInternalRedirect</directive> enables the backend
 131     to internally redirect the gateway to a different URL. This feature
 132     origins in <module>mod_cgi</module>, which internally redirects the
 133     response, if the response status is <code>OK</code> (<code>200</code>) and
 134     the response contains a <code>Location</code> header and its value starts
 135     with a slash (<code>/</code>). This value is interpreted as a new local
 136     URL the apache internally redirects to.</p>
 137
 138     <p><module>mod_proxy_scgi</module> does the same as
 139     <module>mod_cgi</module> in this regard, except that you can turn off the
 140     feature.</p>
 141
 142     <example><title>Example</title>
 143     ProxySCGIInternalRedirect Off
 144     </example>
 145 </usage>
 146 </directivesynopsis>
 147
 148 </modulesynopsis>