[tor-commits] [tor/master] Document the haproxy option of HiddenServiceExportCircuitID.

[nickm at torproject.org]

commit 03ef4ec466fd7f1de097a7b0244ca5bc8cc32b18
Author: Alexander Færøy <ahf at torproject.org>
Date:   Thu Sep 20 21:15:25 2018 +0200

    Document the haproxy option of HiddenServiceExportCircuitID.
    
    See: https://bugs.torproject.org/4700
---
 doc/tor.1.txt | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index df298e1d7..124b01053 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -2839,7 +2839,28 @@ The following options are used to configure a hidden service.
    The onion service will use the given protocol to expose the global circuit
    identifier of each inbound client circuit via the selected protocol. The only
    protocol supported right now \'haproxy\'. This option is only for v3
-   services. (Default: none)
+   services. (Default: none) +
+ +
+   The haproxy option works in the following way: when the feature is
+   enabled, the Tor process will write a header line when a client is connecting
+   to the onion service. The header will look like this: +
+ +
+   "PROXY TCP6 fc00:dead:beef:4dad::ffff:ffff ::1 65535 42\r\n" +
+ +
+   We encode the "global circuit identifier" as the last 32-bits of the first
+   IPv6 address. All other values in the header can safely be ignored. You can
+   compute the global circuit identifier using the following formula given the
+   IPv6 address "fc00:dead:beef:4dad::AABB:CCDD": +
+ +
+      global_circuit_id = (0xAA << 24) + (0xBB << 16) + (0xCC << 8) + 0xDD; +
+ +
+   In the case above, where the last 32-bit is 0xffffffff, the global circuit
+   identifier would be 4294967295. You can use this value together with Tor's
+   control port where it is possible to terminate a circuit given the global
+   circuit identifier. For more information about this see controls-spec.txt. +
+ +
+   The HAProxy version 1 proxy protocol is described in detail at
+   https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
 
 [[HiddenServiceMaxStreams]] **HiddenServiceMaxStreams** __N__::
    The maximum number of simultaneous streams (connections) per rendezvous