From af14149a133ae07e420b00cc68bc0cbece5fb067 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Mon, 30 Oct 2017 11:16:20 -0600 Subject: [PATCH] updated docs for tcp.proxy and ssh --- README.md | 48 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 39 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index fbbc544..7deca89 100644 --- a/README.md +++ b/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.