Added information about using shapeshifter-dispatcher with the obfs4 transport

1 files changed, 53 insertions, 0 deletions

diff --git a/README.md b/README.md
index 2394cf9..da21c0d 100644
--- a/README.md
+++ b/README.md
@@ -133,6 +133,59 @@ The full set of command line flags is specified in the Pluggable Transport 2.0
 draft 1 specification.
 <http://www.pluggabletransports.info/assets/PTSpecV2Draft1.pdf>
 
+#### Running with obfs4
+
+Here are example command lines to run the dispatcher with the obfs4 transport:
+
+##### Server
+
+    bin/shapeshifter-dispatcher -transparent -server -state state -orport 127.0.0.1:3333 -transports obfs4 -bindaddr obfs4-127.0.0.1:2222 -logLevel DEBUG -enableLogging -extorport 127.0.0.1:3334
+
+This runs the server in transparent TCP proxy mode. The directory "state" is used
+to hold transport state. The destination that the server will proxy to is
+127.0.0.1, port 3333. For this demo to work, something needs to be running on
+this host and port. You can use netcat to run a simple server with "nc -l 3333".
+The obfs4 transport is enabled and bound to the address 127.0.0.1 and the port
+2222. Logging is enabled and set to DEBUG level. The statistics reporting server
+address is also required on the server and is set to 127.0.0.1, port 3334.
+However, this service does not actually need to be running for the demo to work.
+
+When the server is run for the first time, it will generate a new public key
+and it will write it to a file in the state directory called
+obfs4_bridgeline.txt. This information is needed by the dispatcher client. Look
+in the file and retrieve the public key from the bridge line. It will look
+similar to this:
+
+    Bridge obfs4 <IP ADDRESS>:<PORT> <FINGERPRINT> cert=OfQAPDamjsRO90fDGlnZR5RNG659FZqUKUwxUHcaK7jIbERvNU8+EVF6rmdlvS69jVYrKw iat-mode=0
+
+The cert parameter is what is needed for the dispatcher client.
+
+##### Client
+
+    bin/shapeshifter-dispatcher -transparent -client -state state -target 127.0.0.1:2222  -transports obfs4 -bindaddr obfs4-127.0.0.1:443 -options '{"cert": "OfQAPDamjsRO90fDGlnZR5RNG659FZqUKUwxUHcaK7jIbERvNU8+EVF6rmdlvS69jVYrKw", "iatMode": "0"}' -logLevel DEBUG -enableLogging
+
+This runs the client in transparent TCP proxy mode. The directory "state" is
+used to hold transport state. The address of the server is specified as
+127.0.0.1, port 2222. This is the same address as was specified on the server
+command line above. For this demo to work, the dispatcher server needs to be
+running on this host and port. The obfs4 transport is enabled and bound to the
+address 127.0.0.1 and the port 443. The -options parameter is different for
+every transport. For obfs4, the "cert" and "iatMode" parameters are required.
+These can be found in the obfs4_bridgeline.txt in the server state directory,
+which is generated by the server the first time that it is run. It is important
+for the cert parameter to be correct, otherwise obfs4 will silently fail.
+Logging is enabled and set to DEBUG level.
+
+Once the client is running, you can connect to the client address, which in this
+case is 127.0.0.1, port 443. For instance, you can telnet to this address:
+
+    telnet 127.0.0.1 443
+
+Any bytes sent over this connection will be forwarded through the transport
+server to the application server, which in the case of this demo is a netcat
+server. You can also type bytes into the netcat server and they will appear
+on the telnet client, once again being routed over the transport.
+
 ##### Environment Variables
 
 Using command line flags is convenient for testing. However, when launching the