<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<modulesynopsis metafile="mod_proxy_scgi.xml.meta">

<name>mod_proxy_scgi</name>

<description>SCGI gateway module for <module>mod_proxy</module></description>

<status>Extension</status>

<sourcefile>mod_proxy_scgi.c</sourcefile>

<identifier>proxy_scgi_module</identifier>

<summary>

<p>This module <em>requires</em> the service of <module

>mod_proxy</module>. It provides support for the

<a href="http://python.ca/scgi/protocol.txt">SCGI protocol, version

1</a>.</p>

<p>Thus, in order to get the ability of handling the SCGI protocol,

<module>mod_proxy</module> and <module>mod_proxy_scgi</module> have to

be present in the server.</p>

<note type="warning"><title>Warning</title>

<p>Do not enable proxying until you have <a

href="mod_proxy.html#access">secured your server</a>. Open proxy

servers are dangerous both to your network and to the Internet at

large.</p>

</note>

</summary>

<seealso><module>mod_proxy</module></seealso>

<seealso><module>mod_proxy_balancer</module></seealso>

<section id="examples"><title>Examples</title>

<p>Remember, in order to make the following examples work, you have to

enable <module>mod_proxy</module> and <module>mod_proxy_scgi</module>.</p>

<example><title>Simple gateway</title>

<highlight language="config">

ProxyPass /scgi-bin/ scgi://localhost:4000/

</highlight>

</example>

<p>The balanced gateway needs <module>mod_proxy_balancer</module> and

at least one load balancer algorithm module, such as

<module>mod_lbmethod_byrequests</module>, in addition to the proxy

modules listed above. <module>mod_lbmethod_byrequests</module> is the

default, and will be used for this example configuration.</p>

<example><title>Balanced gateway</title>

<highlight language="config">

ProxyPass /scgi-bin/ balancer://somecluster/

&lt;Proxy balancer://somecluster&gt;

BalancerMember scgi://localhost:4000

BalancerMember scgi://localhost:4001

&lt;/Proxy&gt;

</highlight>

</example>

</section>

<section id="env"><title>Environment Variables</title>

<p>In addition to the configuration directives that control the

behaviour of <module>mod_proxy</module>, there are a number of

<dfn>environment variables</dfn> that control the SCGI protocol

provider:</p>

<dl>

<dt>proxy-scgi-pathinfo</dt>

<dd>By default <module>mod_proxy_scgi</module> will neither create

nor export the <var>PATH_INFO</var> environment variable. This allows

the backend SCGI server to correctly determine <var>SCRIPT_NAME</var>

and <var>Script-URI</var> and be compliant with RFC 3875 section 3.3.

If instead you need <module>mod_proxy_scgi</module> to generate

a "best guess" for <var>PATH_INFO</var>, set this env-var.</dd>

</dl>

</section>

<directivesynopsis>

<name>ProxySCGISendfile</name>

<description>Enable evaluation of <var>X-Sendfile</var> pseudo response

header</description>

<syntax>ProxySCGISendfile On|Off|<var>Headername</var></syntax>

<default>ProxySCGISendfile Off</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context></contextlist>

<usage>

<p>The <directive>ProxySCGISendfile</directive> directive enables the

SCGI backend to let files serve directly by the gateway. This is useful

performance purposes -- the httpd can use <code>sendfile</code> or other

optimizations, which are not possible if the file comes over the backend

socket.</p>

<p>The <directive>ProxySCGISendfile</directive> argument determines the

gateway behaviour:</p>

<dl>

<dt><code>Off</code></dt>

<dd>No special handling takes place.</dd>

<dt><code>On</code></dt>

<dd>The gateway looks for a backend response header called

<code>X-Sendfile</code> and interprets the value as filename to serve. The

header is removed from the final response headers. This is equivalent to

<code>ProxySCGISendfile X-Sendfile</code>.</dd>

<dt>anything else</dt>

<dd>Similar to <code>On</code>, but instead of the hardcoded header name

the argument is applied as header name.</dd>

</dl>

<example><title>Example</title>

<highlight language="config">

# Use the default header (X-Sendfile)

ProxySCGISendfile On

# Use a different header

ProxySCGISendfile X-Send-Static

</highlight>

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>ProxySCGIInternalRedirect</name>

<description>Enable or disable internal redirect responses from the

backend</description>

<syntax>ProxySCGIInternalRedirect On|Off</syntax>

<default>ProxySCGIInternalRedirect On</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context></contextlist>

<usage>

<p>The <directive>ProxySCGIInternalRedirect</directive> enables the backend

to internally redirect the gateway to a different URL. This feature

origins in <module>mod_cgi</module>, which internally redirects the

response, if the response status is <code>OK</code> (<code>200</code>) and

the response contains a <code>Location</code> header and its value starts

with a slash (<code>/</code>). This value is interpreted as a new local

URL the apache internally redirects to.</p>

<p><module>mod_proxy_scgi</module> does the same as

<module>mod_cgi</module> in this regard, except that you can turn off the

feature.</p>

<example><title>Example</title>

<highlight language="config">

ProxySCGIInternalRedirect Off

</highlight>

</example>

</usage>

</directivesynopsis>

</modulesynopsis>