258 lines
9.5 KiB
HTML
258 lines
9.5 KiB
HTML
<html>
|
|
<head>
|
|
<title>ProFTPD module mod_proxy_protocol</title>
|
|
</head>
|
|
|
|
<body bgcolor=white>
|
|
|
|
<hr>
|
|
<center>
|
|
<h2><b>ProFTPD module <code>mod_proxy_protocol</code></b></h2>
|
|
</center>
|
|
<hr><br>
|
|
|
|
<p>
|
|
The purpose of the <code>mod_proxy_protocol</code> module is to handle
|
|
protocols which are used by proxies, <i>e.g.</i> <code>haproxy</code>, for
|
|
conveying information about the real origin/client to the backend server.
|
|
Protocols like HTTP often have their own mechanism for doing so, via headers
|
|
such as "X-Forwarded-For". Unfortunately, FTP does <b>not</b> have such a
|
|
mechanism, nor does SSH.
|
|
|
|
<p>
|
|
However, there <em>are</em> protocols which an provide this information without
|
|
impacting FTP. HAproxy's <a href="http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt"><code>PROXY</code></a> protocol is one such mechanism. The
|
|
<code>mod_proxy_protocol</code> module uses these mechanisms to change the
|
|
information about the "remote" client so that it is the real client, not the
|
|
proxy, whose IP address/port are logged and used for <i>e.g.</i> network ACLs.
|
|
|
|
<p>
|
|
This module is contained in the <code>mod_proxy_protocol.c</code> file for
|
|
ProFTPD 1.3.<i>x</i>, and is not compiled by default. Installation
|
|
instructions are discussed <a href="#Installation">here</a>; detailed
|
|
notes on best practices for using this module are <a href="#Usage">here</a>.
|
|
|
|
<p>
|
|
The most current version of <code>mod_proxy_protocol</code> can be found at:
|
|
<pre>
|
|
<a href="https://github.com/Castaglia/proftpd-mod_proxy_protocol.git">https://github.com/Castaglia/proftpd-mod_proxy_protocol.git</a>
|
|
</pre>
|
|
|
|
<h2>Author</h2>
|
|
<p>
|
|
Please contact TJ Saunders <tj <i>at</i> castaglia.org> with any
|
|
questions, concerns, or suggestions regarding this module.
|
|
|
|
<h2>Directives</h2>
|
|
<ul>
|
|
<li><a href="#ProxyProtocolEngine">ProxyProtocolEngine</a>
|
|
<li><a href="#ProxyProtocolTimeout">ProxyProtocolTimeout</a>
|
|
<li><a href="#ProxyProtocolVersion">ProxyProtocolVersion</a>
|
|
</ul>
|
|
|
|
<p>
|
|
<hr>
|
|
<h2><a name="ProxyProtocolEngine">ProxyProtocolEngine</a></h2>
|
|
<strong>Syntax:</strong> ProxyProtocolEngine <em>on|off</em><br>
|
|
<strong>Default:</strong> None<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_proxy_protocol<br>
|
|
<strong>Compatibility:</strong> 1.3.5rc4 and later
|
|
|
|
<p>
|
|
The <code>ProxyProtocolEngine</code> directive enables the expectation
|
|
and handling of protocols which provide information on proxied connections;
|
|
support for these protocols is provided by <code>mod_proxy_protocol</code>.
|
|
|
|
<p>
|
|
<hr>
|
|
<h2><a name="ProxyProtocolTimeout">ProxyProtocolTimeout</a></h2>
|
|
<strong>Syntax:</strong> ProxyProtocolTimeout <em>seconds</em><br>
|
|
<strong>Default:</strong> 3sec<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_proxy_protocol<br>
|
|
<strong>Compatibility:</strong> 1.3.5rc4 and later
|
|
|
|
<p>
|
|
The <code>ProxyProtocolTimeout</code> directive is used to configure the
|
|
amount of time, in seconds, that <code>mod_proxy_protocol</code> will wait to
|
|
receive the full expected proxy information. If the full information is
|
|
not received within the given number of seconds, the connection to the client
|
|
is closed.
|
|
|
|
<p>
|
|
<hr>
|
|
<h2><a name="ProxyProtocolVersion">ProxyProtocolVersion</a></h2>
|
|
<strong>Syntax:</strong> ProxyProtocolVersion <em>protocolVersion</em><br>
|
|
<strong>Default:</strong> haproxyV1<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_proxy_protocol<br>
|
|
<strong>Compatibility:</strong> 1.3.5rc4 and later
|
|
|
|
<p>
|
|
The <code>ProxyProtocolVersion</code> directive is used to configure the
|
|
protocol that <code>mod_proxy_protocol</code> expects to handle. The
|
|
currently supported values are:
|
|
<ul>
|
|
<li><code>haproxyV1</code>
|
|
<li><code>haproxyV2</code>
|
|
</ul>
|
|
|
|
<p>
|
|
<hr>
|
|
<h2><a name="Usage">Usage</a></h2>
|
|
|
|
<p>
|
|
<b>Example Configuration</b><br>
|
|
<pre>
|
|
<IfModule mod_proxy_protocol.c>
|
|
ProxyProtocolEngine on
|
|
ProxyProtocolTimeout 3sec
|
|
|
|
# Necessary to allow data transfers
|
|
AllowForeignAddress on
|
|
</IfModule>
|
|
</pre>
|
|
|
|
<p>
|
|
<b>Module Load Order</b><br>
|
|
In order for <code>mod_proxy_protocol</code> to work its magic, it <b>must</b>
|
|
the first module in line to handle the bytes coming in from the client.
|
|
If some other module (such as <code>mod_sftp</code> or <code>mod_tls</code>)
|
|
tries to handle the incoming bytes first, Bad Things will happen, since those
|
|
modules will expect different protocols than the <code>PROXY</code> protocol.
|
|
|
|
<p>
|
|
For <code>mod_proxy_protocol</code> to be the first module called, it must
|
|
the <b>last</b> module loaded. To do this as a static module, you would
|
|
use something like this when building proftpd:
|
|
<pre>
|
|
# ./configure --with-modules=...:mod_proxy_protocol
|
|
</pre>
|
|
ensuring that <code>mod_proxy_protocol</code> is the <b>last</b> module in
|
|
your <code>--with-modules</code> list.
|
|
|
|
<p>
|
|
As a shared module, configuring <code>mod_proxy_protocol</code> to be the
|
|
last module loaded is much easier. Your configuration will have a list
|
|
of <code>LoadModule</code> directives; the last of which would be:
|
|
<pre>
|
|
LoadModule mod_proxy_protocol.c
|
|
</pre>
|
|
|
|
<b>Note</b> that using <code>mod_proxy_protocol</code> as a shared module
|
|
is <i>required</i> in cases where you want to use both
|
|
<code>mod_proxy_protocol</code> <i>and</i> <code>mod_ifsession</code>. For
|
|
example, perhaps you want to use <code>mod_ifsession</code> to change the
|
|
behavior of some module, <i>e.g.</i> <code>mod_ban</code>, based on the IP
|
|
address of the original client. This means that <code>mod_proxy_protocol</code>
|
|
would need to hande the connection <i>first</i>, so that it can decode the
|
|
<code>PROXY</code> protocol and set the correct client IP address.
|
|
<i>However</i>, the ProFTPD build system is hardcoded to ensure that the
|
|
<code>mod_ifsession</code> will always be first -- <i>if</i> using static
|
|
modules. By using <i>shared</i> modules, you can enforce the proper ordering
|
|
using the <code>LoadModule</code> directive, like so:
|
|
<pre>
|
|
<IfModule mod_dso.c>
|
|
...
|
|
LoadModule mod_ifsession.c
|
|
LoadModule mod_proxy_protocol.c
|
|
</IfModule>
|
|
</pre>
|
|
The <i>last</i> module loaded will be the <i>first</i> module called.
|
|
|
|
<p>
|
|
<b>Trusting Senders of Proxy Data</b><br>
|
|
Use of these proxy protocols means changes in audit trails and/or client
|
|
access permissions (<i>e.g.</i> different <code>mod_wrap2</code> and/or
|
|
<code>mod_geoip</code> rules will apply). Unscrupulous senders may try to
|
|
actively lie to your server about the original client using these protocols.
|
|
Thus you <b>must</b> trust the upstream machines <b>before</b> enabling the
|
|
<code>mod_proxy_protocol</code> module.
|
|
|
|
<p>
|
|
Put another way: do <b>not</b> use the <code>mod_proxy_protocol</code> module
|
|
if your server handles connections from the open Internet. Doing so means
|
|
that any machine can use the proxy protocol to hide their activities, or
|
|
make it look like the connection is coming from someone else. <b>Only accept
|
|
proxy information from trusted sources.</b>
|
|
|
|
<p>
|
|
<b>Why <code>AllowForeignAddress</code> Is Needed</b><br>
|
|
One of the consequences of allowing <code>mod_proxy_protocol</code> to change
|
|
the remote IP address is that security checks performed on data transfers
|
|
will cause problems. For active data transfers (<i>i.e.</i> for clients
|
|
which send the <code>PORT</code> or <code>EPRT</code> commands),
|
|
<code>proftpd</code> requires that the IP address sent in the command matches
|
|
the IP address of the client which sends the command. Otherwise, a message
|
|
like the following is logged:
|
|
<pre>
|
|
Refused PORT 127,0,0,1,218,225 (address mismatch)
|
|
</pre>
|
|
and the command is rejected.
|
|
|
|
<p>
|
|
Similarly for passive data transfers (<i>i.e.</i> for clients which send the
|
|
<code>PASV</code> or <code>EPSV</code> commands), <code>proftpd</code> requires
|
|
that the remote IP address of the client which connects to the data transfer
|
|
address <b>must</b> match the remote IP address of the client on the control
|
|
connection. If the addresses do no match, then the following is logged:
|
|
<pre>
|
|
SECURITY VIOLATION: Passive connection from 127.0.0.1 rejected.
|
|
</pre>
|
|
and the control connection is closed.
|
|
|
|
<p>
|
|
These security measures are done to prevent abuses of FTP data transfers
|
|
such as the <a href="http://www.proftpd.org/docs/howto/FXP.html">FTP bounce</a>
|
|
attack. However, the very fact that <code>mod_proxy_protocol</code> changes
|
|
the remote IP address means that to allow data transfers when using this module,
|
|
you need to use:
|
|
<pre>
|
|
AllowForeignAddress on
|
|
</pre>
|
|
in the same virtual host section in which the <code>ProxyProtocolEngine</code>
|
|
directive appears.
|
|
|
|
<p>
|
|
<hr>
|
|
<h2><a name="Installation">Installation</a></h2>
|
|
To install <code>mod_proxy_protocol</code>, copy the
|
|
<code>mod_proxy_protocol.c</code> file into:
|
|
<pre>
|
|
<i>proftpd-dir</i>/contrib/
|
|
</pre>
|
|
after unpacking the latest proftpd-1.3.<i>x</i> source code. For including
|
|
<code>mod_proxy_protocol</code> as a staticly linked module:
|
|
<pre>
|
|
$ ./configure --with-modules=...:mod_proxy_protocol
|
|
</pre>
|
|
To build <code>mod_proxy_protocol</code> as a DSO module:
|
|
<pre>
|
|
$ ./configure --enable-dso --with-shared=...:mod_proxy_protocol
|
|
</pre>
|
|
Then follow the usual steps:
|
|
<pre>
|
|
$ make
|
|
$ make install
|
|
</pre>
|
|
|
|
<p>
|
|
For those with an existing ProFTPD installation, you can use the
|
|
<code>prxs</code> tool to add <code>mod_proxy_protocol</code>, as a DSO module,
|
|
to your existing server:
|
|
<pre>
|
|
$ prxs -c -i -d mod_proxy_protocol.c
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<font size=2><b><i>
|
|
© Copyright 2013-2019 TJ Saunders<br>
|
|
All Rights Reserved<br>
|
|
</i></b></font>
|
|
|
|
<hr>
|
|
</body>
|
|
</html>
|