[DOC] add the proxy protocol's specifications

doc/proxy-protocol.txt

@@ -0,0 +1,159 @@
+The PROXY protocol - 2010/10/29 - Willy TARREAU
+-----------------------------------------------
+
+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.
+
+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, any 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.
+
+We have a patch available for recent versions of Stunnel that brings it the
+ability to be an emitter. The feature is called "send-proxy" there. The code
+for the receiving side has been merged into haproxy and is enabled using the
+"accept-proxy" keyword on a "bind" statement. Haproxy will use the transport
+information from the PROXY protocol for logging, ACLs, etc... everywhere an
+information about the original connection is required.
+
+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.
+--