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
  31 <summary>
  32     <p>This module <em>requires</em> the service of <module
  33     >mod_proxy</module>. It provides support for the
  34     <a href="http://python.ca/scgi/protocol.txt">SCGI protocol, version
  35     1</a>.</p>
  36
  37     <p>Thus, in order to get the ability of handling the SCGI protocol,
  38     <module>mod_proxy</module> and <module>mod_proxy_scgi</module> have to
  39     be present in the server.</p>
  40
  41     <note type="warning"><title>Warning</title>
  42       <p>Do not enable proxying until you have <a
  43       href="mod_proxy.html#access">secured your server</a>. Open proxy
  44       servers are dangerous both to your network and to the Internet at
  45       large.</p>
  46     </note>
  47 </summary>
  48
  49 <seealso><module>mod_proxy</module></seealso>
  50 <seealso><module>mod_proxy_balancer</module></seealso>
  51
  52 <section id="examples"><title>Examples</title>
  53     <p>Remember, in order to make the following examples work, you have to
  54     enable <module>mod_proxy</module> and <module>mod_proxy_scgi</module>.</p>
  55
  56     <example><title>Simple gateway</title>
  57     <highlight language="config">
  58 ProxyPass "/scgi-bin/" "scgi://localhost:4000/"
  59       </highlight>
  60     </example>
  61
  62     <p>The balanced gateway needs <module>mod_proxy_balancer</module> and
  63     at least one load balancer algorithm module, such as
  64     <module>mod_lbmethod_byrequests</module>, in addition to the proxy
  65     modules listed above.  <module>mod_lbmethod_byrequests</module> is the
  66     default, and will be used for this example configuration.</p>
  67
  68     <example><title>Balanced gateway</title>
  69     <highlight language="config">
  70 ProxyPass "/scgi-bin/" "balancer://somecluster/"
  71 &lt;Proxy balancer://somecluster&gt;
  72     BalancerMember scgi://localhost:4000
  73     BalancerMember scgi://localhost:4001
  74 &lt;/Proxy&gt;
  75     </highlight>
  76     </example>
  77 </section>
  78
  79 <section id="env"><title>Environment Variables</title>
  80     <p>In addition to the configuration directives that control the
  81     behaviour of <module>mod_proxy</module>, an <dfn>environment
  82     variable</dfn> may also control the SCGI protocol
  83     provider:</p>
  84     <dl>
  85         <dt>proxy-scgi-pathinfo</dt>
  86         <dd>By default <module>mod_proxy_scgi</module> will neither create
  87         nor export the <var>PATH_INFO</var> environment variable. This allows
  88         the backend SCGI server to correctly determine <var>SCRIPT_NAME</var>
  89         and <var>Script-URI</var> and be compliant with RFC 3875 section 3.3.
  90         If instead you need <module>mod_proxy_scgi</module> to generate
  91         a "best guess" for <var>PATH_INFO</var>, set this env-var.  The
  92         variable must be set before <directive module="env">SetEnv</directive>
  93         is effective.  <directive module="setenv">SetEnvIf</directive> can be
  94         used instead: <code>SetEnvIf Request_URI . proxy-scgi-pathinfo</code>
  95         </dd>
  96     </dl>
  97 </section>
  98
  99 <directivesynopsis>
 100 <name>ProxySCGISendfile</name>
 101 <description>Enable evaluation of <var>X-Sendfile</var> pseudo response
 102 header</description>
 103 <syntax>ProxySCGISendfile On|Off|<var>Headername</var></syntax>
 104 <default>ProxySCGISendfile Off</default>
 105 <contextlist><context>server config</context><context>virtual host</context>
 106 <context>directory</context></contextlist>
 107
 108 <usage>
 109     <p>The <directive>ProxySCGISendfile</directive> directive enables the
 110     SCGI backend to let files be served directly by the gateway. This is useful
 111     for performance purposes &mdash; httpd can use <code>sendfile</code> or other
 112     optimizations, which are not possible if the file comes over the backend
 113     socket.  Additionally, the file contents are not transmitted twice.</p>
 114     <p>The <directive>ProxySCGISendfile</directive> argument determines the
 115     gateway behaviour:</p>
 116     <dl>
 117     <dt><code>Off</code></dt>
 118     <dd>No special handling takes place.</dd>
 119
 120     <dt><code>On</code></dt>
 121     <dd>The gateway looks for a backend response header called
 122     <code>X-Sendfile</code> and interprets the value as the filename to serve.
 123     The  header is removed from the final response headers. This is equivalent to
 124     <code>ProxySCGISendfile X-Sendfile</code>.</dd>
 125
 126     <dt>anything else</dt>
 127     <dd>Similar to <code>On</code>, but instead of the hardcoded header name
 128     <code>X-Sendfile</code>, the argument is used as the header name.</dd>
 129     </dl>
 130
 131     <example><title>Example</title>
 132     <highlight language="config">
 133 # Use the default header (X-Sendfile)
 134 ProxySCGISendfile On
 135
 136 # Use a different header
 137 ProxySCGISendfile X-Send-Static
 138     </highlight>
 139     </example>
 140 </usage>
 141 </directivesynopsis>
 142
 143 <directivesynopsis>
 144 <name>ProxySCGIInternalRedirect</name>
 145 <description>Enable or disable internal redirect responses from the
 146 backend</description>
 147 <syntax>ProxySCGIInternalRedirect On|Off</syntax>
 148 <default>ProxySCGIInternalRedirect On</default>
 149 <contextlist><context>server config</context><context>virtual host</context>
 150 <context>directory</context></contextlist>
 151
 152 <usage>
 153     <p>The <directive>ProxySCGIInternalRedirect</directive> enables the backend
 154     to internally redirect the gateway to a different URL. This feature
 155     originates in <module>mod_cgi</module>, which internally redirects the
 156     response if the response status is <code>OK</code> (<code>200</code>) and
 157     the response contains a <code>Location</code> header and its value starts
 158     with a slash (<code>/</code>). This value is interpreted as a new local
 159     URL that Apache httpd internally redirects to.</p>
 160
 161     <p><module>mod_proxy_scgi</module> does the same as
 162     <module>mod_cgi</module> in this regard, except that you can turn off the
 163     feature.</p>
 164
 165     <example><title>Example</title>
 166     <highlight language="config">
 167     ProxySCGIInternalRedirect Off
 168     </highlight>
 169     </example>
 170 </usage>
 171 </directivesynopsis>
 172
 173 </modulesynopsis>