diff --git a/README.md b/README.md index 384ad70..1c558de 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# wstunnel +# Wstunnel ``` Use the websockets protocol to tunnel {TCP,UDP} traffic wsTunnelClient <---> wsTunnelServer <---> RemoteHost @@ -27,6 +27,48 @@ Common options: -V --version Print version information ``` +## Examples +### Simplest one +On your remote host, start the wstunnel's server by typing this command in your terminal +``` +wstunnel --server ws://0.0.0.0:8080 +``` +This will create a websocket server listenning on any interface on port 8080. +On the client side use this command to forwards traffic trought the websocket tunnel +``` +wstunnel -D 8888 ws://myRemoteHost:8080 +``` +This command will create a sock5 server listenning only on loopback interface on port 8888 and will forwards traffic. + +Ex: With firefox you can setup a proxy using this tunnel by settings in networking preferences 127.0.0.1:8888 and selecting socks5 proxy + +### When behind a corporate proxy +An other useful example is when you want to bypass an http proxy (a corporate proxy for example) +The most reliable way to do it is to use wstunnel as described below + +Start your wstunnel server with tls activated +``` +wstunnel --server wss://0.0.0.0:443 -r 127.0.0.1:22 +``` +The server will listen on any interface on port 443 (https) and restrict traffic to be forwarded only to the ssh daemon. + +**Be aware that the server will use self signed certificate with weak cryptographic algorithm. +It was made in order to add the least possible overhead while still being compliant with tls.** + +**So do not rely on wstunnel to protect your privacy, if you want to do so, forwards only traffic that is already secure by design (ex: https)** + +Now on the client side start the client with +``` +wstunnel -L 9999:127.0.0.1:22 -p mycorporateproxy:8080 wss://myRemoteHost:443 +``` +It will start a tcp server on port 9999 that will contact the corporate proxy, negociate a tls connection with the remote host and forward traffic to the ssh daemon on the remote host. + +You can now access your server from your local machine on ssh by using +``` +ssh -p 9999 login@127.0.0.1 +``` + + ## TODO - [x] Add sock5 proxy - [x] Add better logging