doc/proxy-protocol.txt

                               The PROXY protocol
                                  Willy Tarreau
                                    2011/03/20

Abstract

   The PROXY protocol provides a convenient way to safely transport connection
   information such as a client's address across multiple layers of NAT or TCP
   proxies. It is designed to require little changes to existing components and
   to limit the performance impact caused by the processing of the transported
   information.


Revision history

   2010/10/29 - first version
   2011/03/20 - update: implementation and security considerations


1. Background

Relaying TCP connections through proxies generally involves a loss of the
original TCP connection parameters such as source and destination addresses,
ports, and so on. Some protocols make it a little bit easier to transfer such
information. For SMTP, Postfix authors have proposed the XCLIENT protocol which
received broad adoption and is particularly suited to mail exchanges. In HTTP,
we have the non-standard but omnipresent X-Forwarded-For header which relays
information about the original source address, and the less common
X-Original-To which relays information about the destination address.

However, both mechanisms require a knowledge of the underlying protocol to be
implemented in intermediaries.

Then comes a new class of products which we'll call "dumb proxies", not because
they don't do anything, but because they're processing protocol-agnostic data.
Stunnel is an example of such a "dumb proxy". It talks raw TCP on one side, and
raw SSL on the other one, and does that reliably.

The problem with such a proxy when it is combined with another one such as
haproxy is to adapt it to talk the higher level protocol. A patch is available
for Stunnel to make it capable to insert an X-Forwarded-For header in the first
HTTP request of each incoming connection. Haproxy is able not to add another
one when the connection comes from Stunnel, so that it's possible to hide it
from the servers.

The typical architecture becomes the following one :


      +--------+      HTTP                      :80 +----------+
      | client |  --------------------------------> |          |
      |        |                                    | haproxy, |
      +--------+             +---------+            |  1 or 2  |
     /        /     HTTPS    | stunnel |  HTTP  :81 | listening|
    <________/    ---------> | (server | ---------> |  ports   |
                             |  mode)  |            |          |
                             +---------+            +----------+


The problem appears when haproxy runs with keep-alive on the side towards the
client. The Stunnel patch will only add the X-Forwarded-For header to the first
request of each connection and all subsequent requests will not have it. One
solution could be to improve the patch to make it support keep-alive and parse
all forwarded data, whether they're announced with a Content-Length or with a
Transfer-Encoding, taking care of special methods such as HEAD which announce
data without transfering them, etc... In fact, it would require implementing a
full HTTP stack in Stunnel. It would then become a lot more complex, a lot less
reliable and would not anymore be the "dumb proxy" that fits every purposes.

In practice, we don't need to add a header for each request because we'll emit
the exact same information every time : the information related to the client
side connection. We could then cache that information in haproxy and use it for
every other request. But that becomes dangerous and is still limited to HTTP
only.

Another approach would be to prepend each connection with a line reporting the
characteristics of the other side's connection. This method is a lot simpler to
implement, does not require any protocol-specific knowledge on either side, and
completely fits the purpose. That's finally what we did with a small patch to
Stunnel and another one to haproxy. We have called this protocol the PROXY
protocol.


2. The PROXY protocol

The PROXY protocol's goal is to fill the receiver's internal structures with
the information it could have found itself if it performed the accept from the
client. Thus right now we're supporting the following :
  - INET protocol and family (TCP over IPv4 or IPv6)
  - layer 3 source and destination addresses
  - layer 4 source and destination ports if any

Unlike the XCLIENT protocol, the PROXY protocol was designed with limited
extensibility in order to help the receiver parse it very fast, while keeping
it human-readable for better debugging possibilities. So it consists in exactly
the following block prepended before any data flowing from the dumb proxy to
the next hop :

  - a string identifying the protocol : "PROXY" ( \x50 \x52 \x4F \x58 \x59 )

  - exactly one space : " " ( \x20 )

  - a string indicating the proxied INET protocol and family. At the moment,
    only "TCP4" ( \x54 \x43 \x50 \x34 ) for TCP over IPv4, and "TCP6"
    ( \x54 \x43 \x50 \x36 ) for TCP over IPv6 are allowed. Unsupported or
    unknown protocols must be reported with the name "UNKNOWN" ( \x55 \x4E \x4B
    \x4E \x4F \x57 \x4E). The remaining fields of the line are then optional
    and may be ignored, until the CRLF is found.

  - exactly one space : " " ( \x20 )

  - the layer 3 source address in its canonical format. IPv4 addresses must be
    indicated as a series of exactly 4 integers in the range [0..255] inclusive
    written in decimal representation separated by exactly one dot between each
    other. Heading zeroes are not permitted in front of numbers in order to
    avoid any possible confusion with octal numbers. IPv6 addresses must be
    indicated as series of 4 hexadecimal digits (upper or lower case) delimited
    by colons between each other, with the acceptance of one double colon
    sequence to replace the largest acceptable range of consecutive zeroes. The
    total number of decoded bits must exactly be 128. The advertised protocol
    family dictates what format to use.

  - exactly one space : " " ( \x20 )

  - the layer 3 destination address in its canonical format. It is the same
    format as the layer 3 source address and matches the same family.

  - exactly one space : " " ( \x20 )

  - the TCP source port represented as a decimal integer in the range
    [0..65535] inclusive. Heading zeroes are not permitted in front of numbers
    in order to avoid any possible confusion with octal numbers.

  - exactly one space : " " ( \x20 )

  - the TCP destination port represented as a decimal integer in the range
    [0..65535] inclusive. Heading zeroes are not permitted in front of numbers
    in order to avoid any possible confusion with octal numbers.

  - the CRLF sequence ( \x0D \x0A )

The receiver MUST be configured to only receive this protocol and MUST not try
to guess whether the line is prepended or not. That means that the protocol
explicitly prevents port sharing between public and private access. Otherwise
it would become a big security issue. The receiver should ensure proper access
filtering so that only trusted proxies are allowed to use this protocol. The
receiver must wait for the CRLF sequence to decode the addresses in order to
ensure they are complete. Any sequence which does not exactly match the
protocol must be discarded and cause a connection abort. It is recommended
to abort the connection as soon as possible to that the emitter notices the
anomaly.

If the announced transport protocol is "UNKNOWN", then the receiver knows that
the emitter talks the correct protocol, and may or may not decide to accept the
connection and use the real connection's parameters as if there was no such
protocol on the wire.

An example of such a line before an HTTP request would look like this (CR
marked as "\r" and LF marked as "\n") :

    PROXY TCP4 192.168.0.1 192.168.0.11 56324 443\r\n
    GET / HTTP/1.1\r\n
    Host: 192.168.0.11\r\n
    \r\n

For the emitter, the line is easy to put into the output buffers once the
connection is established. For the receiver, once the line is parsed, it's
easy to skip it from the input buffers.


3. Implementations

Haproxy 1.5 implements the PROXY protocol on both sides :
  - the listening sockets accept the protocol when the "accept-proxy" setting
    is passed to the "bind" keyword. Connections accepted on such listeners
    will behave just as if the source really was the one advertised in the
    protocol. This is true for logging, ACLs, content filtering, transparent
    proxying, etc...

  - the protocol may be used to connect to servers if the "send-proxy" setting
    is present on the "server" line. It is enabled on a per-server basis, so it
    is possible to have it enabled for remote servers only and still have local
    ones behave differently. If the incoming connection was accepted with the
    "accept-proxy", then the relayed information is the one advertised in this
    connection's PROXY line.

We have a patch available for recent versions of Stunnel that brings it the
ability to be an emitter. The feature is called "sendproxy" there.

The protocol is so simple that it is expected that other implementations will
appear, especially in environments such as SMTP, IMAP, FTP, RDP where the
client's address is an important piece of information for the server and some
intermediaries.

Proxy developers are encouraged to implement this protocol, because it will
make their products much more transparent in complex infrastructures, and will
get rid of a number of issues related to logging and access control.


4. Security considerations

The protocol was designed so as to be distinguishable from HTTP. It will not
parse as a valid HTTP request and an HTTP request will not parse as a valid
proxy request. That makes it easier to enfore its use certain connections.
Implementers should be very careful about not trying to automatically detect
whether they have to decode the line or not, but rather to only rely on a
configuration parameter. Indeed, if the opportunity is left to a normal client
to use the protocol, he will be able to hide his activities or make them appear
as coming from someone else. However, accepting the line only from a number of
known sources should be safe.


5. Future developments

It is possible that the protocol may slightly evolve to present other
information such as the incoming network interface, or the origin addresses in
case of network address translation happening before the first proxy, but this
is not identified as a requirement right now. Suggestions on improvements are
welcome.


6. Contacts

Please use w@1wt.eu to send any comments to the author.