hex/wstunnel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update README.md

Browse source 
Former-commit-id: 80b5f496e2f6a7b83205d14a6edccafa959f5eb6 [formerly f83d082dfb796b31ad23aa40cd9487582d92f986] [formerly a995a1451886c4aea49760f73a3c8d480c926c14 [formerly 8c9ee8cecd0d79971a8ba22e49e7bdc0e005d1f6]]
Former-commit-id: eb118bf65f61f5c886056f748beff32c970f586d [formerly 431739ed71903e3da602da5683ecf70bb9bcb73b]
Former-commit-id: 1ea96a923c587d88aa44f1ad3b72c94bcd153352
Former-commit-id: 766527fa2febf32ba2c5783a68f9824e4b0a0c28
Former-commit-id: 5efbf1ea04a3b803cc4935a60b9a0a849b85cf68
Former-commit-id: 6dc7d4d17ee2419d9dfd8be20f24bf612e6bc9a2 [formerly 2ff2ff25a8141693bee6bc41bb6b3aaffbf29a63]
Former-commit-id: dfddc357b5965a690ec16ac6f71d75e36707d9c0
This commit is contained in:
Erèbe - Romain Gerard 2023-10-21 14:49:10 +02:00 committed by Σrebe - Romain GERARD
parent 89df547a7a
commit 016cfe91ef
1 changed files with 82 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

151
README.md
View file

@ -31,79 +31,92 @@ Use the websockets protocol to tunnel {TCP,UDP} traffic
wsTunnelClient <---> wsTunnelServer <---> RemoteHost wsTunnelClient <---> wsTunnelServer <---> RemoteHost
Use secure connection (wss://) to bypass proxies Use secure connection (wss://) to bypass proxies
wstunnel [OPTIONS] ws[s]://wstunnelServer[:port] Client:
Usage: wstunnel client [OPTIONS] <ws[s]://wstunnel.server.com[:port]>
Client options: Arguments:
-L --localToRemote=[BIND:]PORT:HOST:PORT Listen on local and forwards <ws[s]://wstunnel.server.com[:port]> Address of the wstunnel server
traffic from remote. Can be Example: With TLS wss://wstunnel.example.com or without ws://wstunnel.example.com
used multiple time
-D --dynamicToRemote=[BIND:]PORT Listen on local and Options:
dynamically (with socks5 proxy) -L, --local-to-remote <{tcp,udp,socks5,stdio}://[BIND:]PORT:HOST:PORT>
forwards traffic from remote Listen on local and forwards traffic from remote. Can be specified multiple times
-u --udp forward UDP traffic instead examples:
of TCP 'tcp://1212:google.com:443' => listen locally on tcp on port 1212 and forward to google.com on port 443
--udpTimeoutSec=INT When using udp forwarding, 'udp://1212:1.1.1.1:53' => listen locally on udp on port 1212 and forward to cloudflare dns 1.1.1.1 on port 53
timeout in seconds after when 'udp://1212:1.1.1.1:53?timeout_sec=10' timeout_sec on udp force close the tunnel after 10sec. Set it to 0 to disable the timeout [default: 30]
the tunnel connection is 'socks5://1212' => listen locally with socks5 on port 1212 and forward dynamically requested tunnel
closed. Default 30sec, -1 means 'socks5://1212?socket_so_mark=2' => each tunnel can have the socket_so_mark option, cf explanation on server command
no timeout 'stdio://google.com:443' => listen for data from stdio, mainly for `ssh -o ProxyCommand="wstunnel client -L stdio://%h:%p ws://localhost:8080" my-server`
-p --httpProxy=USER:PASS@HOST:PORT If set, will use this proxy --tls-sni-override <DOMAIN_NAME>
to connect to the server Domain name that will be use as SNI during TLS handshake
--soMark=int (linux only) Mark network Warning: If you are behind a CDN (i.e: Cloudflare) you must set this domain also in the http HOST header.
packet with SO_MARK sockoption or it will be flagged as fishy and your request rejected
with the specified value. You --tls-verify-certificate
need to use {root, sudo, Enable TLS certificate verification.
capabilities} to run wstunnel Disabled by default. The client will happily connect to any server with self signed certificate.
when using this option -p, --http-proxy <http://USER:PASS@HOST:PORT>
--upgradePathPrefix=String Use a specific prefix that If set, will use this http proxy to connect to the server
will show up in the http path --http-upgrade-path-prefix <HTTP_UPGRADE_PATH_PREFIX>
in the upgrade request. Useful Use a specific prefix that will show up in the http path during the upgrade request.
if you need to route requests Useful if you need to route requests server side but don't have vhosts [default: morille]
server side but don't have --http-upgrade-credentials <USER[:PASS]>
vhosts Pass authorization header with basic auth credentials during the upgrade request.
--hostHeader=String If set, add the custom string If you need more customization, you can use the http_headers option.
as host http header --websocket-ping-frequency-sec <seconds>
--tlsSNI=String If set, use custom string in Frequency at which the client will send websocket ping to the server. [default: 30]
the SNI during TLS handshake --websocket-mask-frame
--websocketPingFrequencySec=int do a hearthbeat ping every x Enable the masking of websocket frames. Default is false
seconds to maintain websocket Enable this option only if you use unsecure (non TLS) websocket server and you see some issues. Otherwise, it is just overhead.
connection -H, --http-headers <HEADER_NAME: HEADER_VALUE>
--upgradeCredentials=USER[:PASS] Credentials for the Basic Send custom headers in the upgrade request
HTTP authorization type sent Can be specified multiple time
with the upgrade request. -h, --help
-H --customHeaders="HeaderName: HeaderValue" Send custom headers in the Print help
upgrade request. Can be used
multiple time Server:
-h --help Display help message Usage: wstunnel server [OPTIONS] <ws[s]://0.0.0.0[:port]>
-V --version Print version information
Server options: Arguments:
--server Start a server that will <ws[s]://0.0.0.0[:port]> Address of the wstunnel server to bind to
forward traffic for you Example: With TLS wss://0.0.0.0:8080 or without ws://[::]:8080
-r --restrictTo=HOST:PORT Accept traffic to be
forwarded only to this service Options:
--tlsCertificate=FILE [optional] provide a custom --socket-so-mark <INT>
tls certificate (.crt) that the (linux only) Mark network packet with SO_MARK sockoption with the specified value.
server will use instead of the You need to use {root, sudo, capabilities} to run wstunnel when using this option
embeded one --websocket-ping-frequency-sec <seconds>
--tlsKey=FILE [optional] provide a custom Frequency at which the server will send websocket ping to client.
tls key (.key) that the server --websocket-mask-frame
will use instead of the embeded Enable the masking of websocket frames. Default is false
one Enable this option only if you use unsecure (non TLS) websocket server and you see some issues. Otherwise, it is just overhead.
Common options: --restrict-to <DEST:PORT>
-v --verbose Print debug information Server will only accept connection from the specified tunnel information.
-q --quiet Print only errors Can be specified multiple time
Example: --restrict-to "google.com:443" --restrict-to "localhost:22"
--restrict-http-upgrade-path-prefix <RESTRICT_HTTP_UPGRADE_PATH_PREFIX>
Server will only accept connection from if this specific path prefix is used during websocket upgrade.
Useful if you specify in the client a custom path prefix and you want the server to only allow this one.
The path prefix act as a secret to authenticate clients
Disabled by default. Accept all path prefix
--tls-certificate <FILE_PATH>
[Optional] Use custom certificate (.crt) instead of the default embedded self signed certificate.
--tls-private-key <FILE_PATH>
[Optional] Use a custom tls key (.key) that the server will use instead of the default embedded one
-h, --help
Print help
``` ```
## Examples ## Examples
### Simplest one ### Simplest one
On your remote host, start the wstunnel's server by typing this command in your terminal On your remote host, start the wstunnel's server by typing this command in your terminal
```bash ```bash
wstunnel --server ws://0.0.0.0:8080 wstunnel server ws://[::]:8080
``` ```
This will create a websocket server listening on any interface on port 8080. This will create a websocket server listening on any interface on port 8080.
On the client side use this command to forward traffic through the websocket tunnel On the client side use this command to forward traffic through the websocket tunnel
```bash ```bash
wstunnel -D 8888 ws://myRemoteHost:8080 wstunnel client -L socks5://8888 ws://myRemoteHost:8080
``` ```
This command will create a sock5 server listening on port 8888 of a loopback interface and will forward traffic. This command will create a sock5 server listening on port 8888 of a loopback interface and will forward traffic.
@ -119,7 +132,7 @@ curl -x socks5h://127.0.0.1:8888 http://google.com/
### As proxy command for SSH ### As proxy command for SSH
You can specify `stdio` as source port on the client side if you wish to use wstunnel as part of a proxy command for ssh You can specify `stdio` as source port on the client side if you wish to use wstunnel as part of a proxy command for ssh
``` ```
ssh -o ProxyCommand="wstunnel -L stdio:%h:%p ws://localhost:8080" my-server ssh -o ProxyCommand="wstunnel client -L stdio://%h:%p ws://localhost:8080" my-server
``` ```
### When behind a corporate proxy ### When behind a corporate proxy
@ -128,7 +141,7 @@ The most reliable way to do it is to use wstunnel as described below
Start your wstunnel server with tls activated Start your wstunnel server with tls activated
``` ```
wstunnel --server wss://0.0.0.0:443 -r 127.0.0.1:22 wstunnel server wss://[::]:443 --restrict-to 127.0.0.1:22
``` ```
The server will listen on any interface using port 443 (https) and restrict traffic to be forwarded only to the ssh daemon. The server will listen on any interface using port 443 (https) and restrict traffic to be forwarded only to the ssh daemon.
@ -139,7 +152,7 @@ It was made in order to add the least possible overhead while still being compli
Now on the client side start the client with Now on the client side start the client with
``` ```
wstunnel -L 9999:127.0.0.1:22 -p mycorporateproxy:8080 wss://myRemoteHost:443 wstunnel client -L tcp://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, negotiate a tls connection with the remote host and forward traffic to the ssh daemon on the remote host. It will start a tcp server on port 9999 that will contact the corporate proxy, negotiate a tls connection with the remote host and forward traffic to the ssh daemon on the remote host.
@ -157,14 +170,14 @@ Else if you forward all the traffic without putting a static route, you will end
## How to Build ## How to Build
Install the stack tool https://docs.haskellstack.org/en/stable/README/ or if you are a believer Install the Rust https://www.rust-lang.org/tools/install or if you are a believer
``` ```
curl -sSL https://get.haskellstack.org/ | sh curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
``` ```
and run those commands at the root of the project and run those commands at the root of the project
``` ```
stack init cargo build
stack install target/debug/wstunnel ...
``` ```
## TODO ## TODO