<?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>, an <dfn>environment

variable</dfn> may also 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. The

variable must be set before <directive module="env">SetEnv</directive>

is effective. <directive module="setenv">SetEnvIf</directive> can be

used instead: <code>SetEnvIf Request_URI . proxy-scgi-pathinfo</code>

</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 be served directly by the gateway. This is useful

for performance purposes &mdash; httpd can use <code>sendfile</code> or other

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

socket. Additionally, the file contents are not transmitted twice.</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 the 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

<code>X-Sendfile</code>, the argument is used as the 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|<var>Headername</var></syntax>

<default>ProxySCGIInternalRedirect On</default>

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

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

<compatibility>The <var>Headername</var> feature is available in Apache

httpd 2.5.0 and later.</compatibility>

<usage>

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

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

originates 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> (or configured alternate

header) and its value starts with a slash (<code>/</code>). This value is

interpreted as a new local URL that Apache httpd 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 or specify the use of a header other than <code>Location</code>.</p>

<example><title>Example</title>

<highlight language="config">

ProxySCGIInternalRedirect Off

# Django and some other frameworks will fully qualify "local URLs"

# set by the application, so an alternate header must be used.

&lt;Location /django-app/&gt;

ProxySCGIInternalRedirect X-Location

&lt;/Location&gt;

</highlight>

</example>

</usage>

</directivesynopsis>

</modulesynopsis>