libapache2-mod-proxy-protocol/mod_proxy_protocol.xml
2020-02-12 11:53:48 +01:00

127 lines
5.4 KiB
XML

<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "http://httpd.apache.org/docs/2.4/style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="http://httpd.apache.org/docs/2.4/style/manual.en.xsl"?>
<!--
Copyright 2014 Cloudzilla Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<modulesynopsis metafile="mod_proxy_protocol.xml.meta">
<name>mod_proxy_protocol</name>
<description>Implements the server side of the proxy protocol.</description>
<status>Extension</status>
<sourcefile>mod_proxy_protocol.c</sourcefile>
<identifier>proxy_protocol_module</identifier>
<summary>
<p><module>mod_proxy_protocol</module> implements the server side of
HAProxy's
<a href="http://blog.haproxy.com/haproxy/proxy-protocol/">Proxy Protocol</a>.</p>
<p>The module overrides the client IP address for the connection
with the information supplied by the upstream proxy in the proxy
protocol (connection) header.</p>
<p>This overridden useragent IP address is then used for the
<module>mod_authz_host</module>
<directive module="mod_authz_core" name="require">Require ip</directive>
feature, is reported by <module>mod_status</module>, and is recorded by
<module>mod_log_config</module> <code>%a</code> and <module>core</module>
<code>%a</code> format strings. The underlying client IP of the connection
is available in the <code>%{c}a</code> format string.</p>
<note type="warning">It is critical to only enable this behavior from
intermediate proxies which are trusted by this server, since it is trivial
for the remote client to impersonate another client. Currently this must
be done by external means (such as a firewall) as this module does not
(yet) implement access controls.</note>
</summary>
<seealso><a href="http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt">Proxy Protocol Spec</a></seealso>
<directivesynopsis>
<name>ProxyProtocol</name>
<description>Enable or disable the proxy protocol handling</description>
<syntax>ProxyProtocol On|Off</syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>The <directive>ProxyProtocol</directive> enables or disables the
reading and handling of the proxy protocol connection header. If enabled
the upstream client <em>must</em> send the header every time it opens a
connection or the connection will get aborted.</p>
<p>While this directive may be specified in any virtual host, it is
important to understand that because the proxy protocol is connection
based and protocol agnostic, the enabling and disabling is actually based
on ip-address and port. This means that if you have multiple name-based
virtual hosts for the same host and port, and you enable it any one of
them, then it is enabled for all them (with that host and port). It also
means that if you attempt to enable the proxy protocol in one and disable
in the other, that won't work; in such a case the last one wins and a
notice will be logged indicating which setting was being overridden.</p>
<highlight language="config">
ProxyProtocol On
</highlight>
</usage>
</directivesynopsis>
<!--
<directivesynopsis>
<name>ProxyProtocolTrustedProxies</name>
<description>A listed of clients that are trusted to provide the proxy
protocol header.</description>
<syntax>ProxyProtocolTrustedProxies <var>levels</var></syntax>
<syntax>ProxyProtocolTrustedProxies all|<var>host</var> [<var>host</var>] ...</syntax>
<default>ProxyProtocolTrustedProxies all</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>The <directive>ProxyProtocolTrustedProxies</directive> directive limits
which clients are trusted to use the proxy protocol. What happens when a
client is not trusted is controlled by the
<directive module="mod_proxy_protocol">ProxyProtocolRejectUntrusted</directive>
directive.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>ProxyProtocolRejectUntrusted</name>
<description>The number of characters in subdirectory names</description>
<syntax>ProxyProtocolRejectUntrusted On|Off</syntax>
<default>ProxyProtocolRejectUntrusted On</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>The <directive>ProxyProtocolRejectUntrusted</directive> directive
controls the behavior when a connection is received from an untrusted
client (as configured by the
<directive module="mod_proxy_protocol">ProxyProtocolTrustedProxies</directive>
directive) on a host and port for which the proxy protocol has been enabled.
If set to On (the default) then the connection is aborted; if set to Off
then the connection is allowed, and client must send a valid proxy protocol
header, but the contents of the header are ignored and the client IP for
the connection left untouched (i.e. will be that of the immediate client).
</p>
</usage>
</directivesynopsis>
-->
</modulesynopsis>