updated docs for tcp.proxy and ssh

README.md

@@ -273,7 +273,8 @@ tls:
 
 ### tcp
 
-The tcp system handles all tcp network traffic **before decryption** and may use port numbers
+The tcp system handles both *raw* and *tls-terminated* tcp network traffic
+(see the _Note_ section below the example). It may use port numbers
 or traffic sniffing to determine how the connection should be handled.
 
 It has the following options:
@@ -296,37 +297,66 @@ tcp:
       address: '127.0.0.1:2222'
 ```
 
+_Note_: When tcp traffic comes into goldilocks it will be tested against the tcp modules.
+The connection may be handed to the TLS module if it appears to be a TLS/SSL/HTTPS connection
+and if the tls module terminates the traffic, the connection will be sent back to the TLS module.
+Due to the complexity of node.js' networking stack it is not currently possible to tell which
+port tls-terminated traffic came from, so only the SNI header (serername / domain name) may be used for
+modules matching terminated TLS.
+
 ### tcp.proxy
 
-The proxy module routes traffic based on the servername contained in a SNI header.
-As such this only works to route TCP connections wrapped in a TLS stream.
+The proxy module routes traffic **after tls-termination** based on the servername (domain name)
+contained in a SNI header. As such this only works to route TCP connections wrapped in a TLS stream.
 
 It has the same options as the [HTTP proxy module](#httpproxy-how-to-reverse-proxy-ruby-python-etc).
 
+This is particularly useful for routing ssh and vpn traffic over tcp port 443 as wrapped TLS
+connections in order to access one of your servers even when connecting from a harsh or potentially
+misconfigured network environment (i.e. hotspots in public libraries and shopping malls).
+
 Example config:
 ```yml
 tcp:
   modules:
     - type: proxy
       domains:
-        - ssh.example.com
+        - _ssh.example.com      # Note: this domain would also listed in tls.acme.domains
+      host: localhost
       port: 22
 ```
 
+_Note_: In same cases network administrators purposefully block ssh and vpn connections using
+Application Firewalls with DPI (deep packet inspection) enabled. You should read the ToS of the
+network you are connected to to ensure that you aren't subverting policies that are purposefully
+in place on such networks.
+
+#### Using with ssh
+
 In order to use this to route SSH connections you will need to use `ssh`'s
-`ProxyCommand` option. For example to ssh into `ssh.example.com` you could use
-the following command.
+`ProxyCommand` option. For example to use the TLS certificate for `_ssh.example.com`
+to wrap an ssh connection you could use the following command:
 
 ```bash
-ssh user@ssh.example.com -o ProxyCommand='openssl s_client -quiet -connect ssh.example.com:443 -servername ssh.example.com'
+ssh user@example.com -o ProxyCommand='openssl s_client -quiet -connect example.com:443 -servername _ssh.example.com'
 ```
 
 Alternatively you could add the following lines to your ssh config file.
 ```
-Host ssh.example.com
-  ProxyCommand openssl s_client -quiet -connect ssh.example.com:443 -servername ssh.example.com
+Host example.com
+  ProxyCommand openssl s_client -quiet -connect example.com:443 -servername _ssh.example.com
 ```
 
+#### Using with OpenVPN
+
+There are two strategies that will work well for you:
+
+1) [Use ssh](https://redfern.me/tunneling-openvpn-through-ssh/) with the config above to reverse proxy tcp port 1194 to you. (`ssh -L 1194:localhost:1194 example.com`)
+
+2) [Use stunnel](https://git.daplie.com/Daplie/node-tunnel-client)
+
+3) Use stunnel.js as described in the "tunnel_server" section below
+
 ### tcp.forward
 
 The forward module routes traffic based on port number **without decrypting** it.