wstunnel

Tunnel all your traffic over Websocket or HTTP2 - Bypass firewalls/DPI - Static binary available

4,232

366

4,232

View on GitHub

Top Related Projects

frp

85,378

A fast reverse proxy to help you expose a local server behind a NAT or firewall to the internet.

gost

15,882

GO Simple Tunnel - a simple tunnel written in golang

SirTunnel

1,343

Minimal, self-hosted, 0-config alternative to ngrok. Caddy+OpenSSH+50 lines of Python.

go-http-tunnel

3,232

Fast and secure tunnels over HTTP/2

sslh

4,558

Applicative Protocol Multiplexer (e.g. share SSH and HTTPS on the same port)

Quick Overview

wstunnel is a tool that allows tunneling of TCP/UDP connections through WebSocket connections. It's particularly useful for bypassing firewalls or proxies that block certain protocols but allow WebSocket traffic. This project provides both client and server components for establishing such tunnels.

Pros

Bypasses restrictive firewalls and proxies
Supports both TCP and UDP tunneling
Offers TLS encryption for secure connections
Cross-platform compatibility (Linux, macOS, Windows)

Cons

May introduce additional latency due to WebSocket overhead
Requires setup on both client and server sides
Could potentially be misused for malicious purposes
Limited documentation for advanced use cases

Getting Started

Download the latest release for your platform from the GitHub releases page.

On the server side, run:

./wstunnel server -v --restrict-to 127.0.0.1:8000 ws://0.0.0.0:8080

On the client side, run:

./wstunnel client -v ws://server_ip:8080 127.0.0.1:8000

Now you can connect to localhost:8000 on the client, and the traffic will be tunneled through the WebSocket connection to the server.

For secure connections, use wss:// instead of ws:// and provide appropriate TLS certificates on the server side.

Competitor Comparisons

frp

85,378

A fast reverse proxy to help you expose a local server behind a NAT or firewall to the internet.

Pros of frp

More comprehensive feature set, including load balancing and custom plugins
Supports multiple protocols (TCP, UDP, HTTP, HTTPS, STCP, XTCP)
Built-in web dashboard for monitoring and management

Cons of frp

More complex setup and configuration
Higher resource usage due to additional features
Steeper learning curve for new users

Code Comparison

frp configuration example:

[common]
server_addr = x.x.x.x
server_port = 7000

[ssh]
type = tcp
local_ip = 127.0.0.1
local_port = 22
remote_port = 6000

wstunnel command example:

wstunnel -L 127.0.0.1:8080 ws://example.com:8080

Key Differences

frp offers a more feature-rich solution with support for various protocols and advanced functionalities
wstunnel focuses on simplicity and ease of use, primarily for WebSocket tunneling
frp requires separate client and server components, while wstunnel can operate in both modes
wstunnel is lighter and easier to set up for basic tunneling needs
frp provides better scalability and management options for complex networking scenarios

Both tools serve different use cases, with frp being more suitable for enterprise-level deployments and wstunnel for quick and simple tunneling tasks.

chisel

12,843

A fast TCP/UDP tunnel over HTTP

Pros of Chisel

Supports multiple protocols (HTTP, SOCKS5, TCP) for versatile tunneling options
Includes built-in server and client functionality for easier setup
Offers reverse tunneling capabilities for accessing services behind NAT

Cons of Chisel

More complex configuration due to additional features
Larger binary size and potentially higher resource usage
May have a steeper learning curve for new users

Code Comparison

Chisel client connection:

c, err := chisel.NewClient(config)
if err != nil {
    log.Fatal(err)
}
err = c.Run()

wstunnel client connection:

let mut client = Client::new(url, None)?;
client.connect().await?;
client.run().await?;

Key Differences

Chisel is written in Go, while wstunnel is written in Rust
Chisel offers more features and protocols, while wstunnel focuses on WebSocket tunneling
wstunnel may have better performance due to Rust's efficiency, but Chisel provides more flexibility

Use Cases

Choose Chisel for complex networking scenarios requiring multiple protocols and reverse tunneling
Opt for wstunnel when a lightweight, WebSocket-specific solution is needed, especially in resource-constrained environments

Both projects serve similar purposes but cater to different needs based on their feature sets and implementation languages.

gost

15,882

GO Simple Tunnel - a simple tunnel written in golang

Pros of gost

Supports multiple protocols (HTTP, SOCKS4, SOCKS5, SS) in addition to WebSocket tunneling
Offers more advanced features like chain proxying and traffic forwarding
Provides both client and server implementations in a single package

Cons of gost

More complex setup and configuration due to its extensive feature set
Potentially higher resource usage because of the additional functionalities
May have a steeper learning curve for users who only need simple WebSocket tunneling

Code Comparison

wstunnel:

conn, err := websocket.Dial(wsURL, "", origin)
if err != nil {
    return nil, err
}
return &wsConn{conn}, nil

gost:

node, err := gost.ParseNode(nodeString)
if err != nil {
    return nil, err
}
handler, err := gost.NewHandler(node.Protocol, node)
if err != nil {
    return nil, err
}

The code snippets show that wstunnel focuses specifically on WebSocket connections, while gost uses a more generalized approach to handle multiple protocols and node configurations.

SirTunnel

1,343

Minimal, self-hosted, 0-config alternative to ngrok. Caddy+OpenSSH+50 lines of Python.

Pros of SirTunnel

Written in Python, which may be more accessible for some developers
Supports HTTPS tunneling out of the box
Includes a simple web interface for managing tunnels

Cons of SirTunnel

Less actively maintained compared to wstunnel
Fewer features and configuration options
May have lower performance due to being written in Python

Code Comparison

SirTunnel (Python):

async def handle_tunnel(reader, writer):
    try:
        while True:
            data = await reader.read(8192)
            if not data:
                break
            writer.write(data)
            await writer.drain()
    finally:
        writer.close()

wstunnel (Rust):

async fn tunnel(mut ws_stream: WsStream, mut tcp_stream: TcpStream) -> Result<(), Error> {
    let (mut ws_sender, mut ws_receiver) = ws_stream.split();
    let (mut tcp_reader, mut tcp_writer) = tcp_stream.split();
    
    let ws_to_tcp = tokio::io::copy(&mut ws_receiver, &mut tcp_writer);
    let tcp_to_ws = tokio::io::copy(&mut tcp_reader, &mut ws_sender);
    
    tokio::try_join!(ws_to_tcp, tcp_to_ws)?;
    Ok(())
}

The code comparison shows that wstunnel uses Rust's async/await syntax and leverages the tokio runtime for efficient I/O operations, potentially offering better performance than SirTunnel's Python implementation.

go-http-tunnel

3,232

Fast and secure tunnels over HTTP/2

Pros of go-http-tunnel

Written in Go, potentially offering better performance and concurrency handling
Supports multiple tunneling protocols (HTTP, HTTPS, TCP, SNI)
Provides built-in authentication and encryption features

Cons of go-http-tunnel

Less actively maintained (last commit over 2 years ago)
More complex setup and configuration compared to wstunnel
Limited documentation and examples for advanced use cases

Code Comparison

wstunnel (Rust):

let mut ws = WebSocket::new(url, None)?;
ws.connect(None)?;
let (mut receiver, mut sender) = ws.split()?;

go-http-tunnel (Go):

tunnel := tunnel.NewServer(&tunnel.ServerConfig{
    Addr: ":80",
})
tunnel.Start()

Summary

While go-http-tunnel offers more features and protocol support, wstunnel provides a simpler, more actively maintained solution focused on WebSocket tunneling. go-http-tunnel may be better suited for complex networking scenarios, while wstunnel excels in straightforward WebSocket-based tunneling applications. The choice between the two depends on specific project requirements, desired features, and the preferred programming language ecosystem.

sslh

4,558

Applicative Protocol Multiplexer (e.g. share SSH and HTTPS on the same port)

Pros of sslh

Supports multiple protocols (SSH, HTTP, SSL, etc.) on a single port
Can handle both IPv4 and IPv6 connections
Offers flexible configuration options for protocol detection

Cons of sslh

May have higher resource usage due to protocol detection overhead
Limited to specific protocols, while wstunnel focuses on WebSocket tunneling
Requires more complex setup for advanced configurations

Code Comparison

sslh (configuration example):

listen:
  - host: "0.0.0.0"
    port: "443"
protocols:
  - name: "ssh"
    host: "localhost"
    port: "22"
  - name: "http"
    host: "localhost"
    port: "80"

wstunnel (usage example):

wstunnel -L 0.0.0.0:8080 ws://example.com:8080

While sslh focuses on multiplexing various protocols on a single port, wstunnel specializes in creating WebSocket tunnels. sslh offers more flexibility in protocol handling but may require more complex configuration. wstunnel provides a simpler setup for WebSocket-specific tunneling needs.

The code examples highlight the difference in approach: sslh uses a configuration file to define protocol handling, while wstunnel uses command-line arguments for tunnel setup. This reflects the broader scope of sslh compared to the more focused functionality of wstunnel.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

wstunnel logo

Description

Most of the time when you are using a public network, you are behind some kind of firewall or proxy. One of their purpose is to constrain you to only use certain kind of protocols and consult only a subset of the web. Nowadays, the most widespread protocol is http and is de facto allowed by third party equipment.

Wstunnel uses the websocket protocol which is compatible with http in order to bypass firewalls and proxies. Wstunnel allows you to tunnel whatever traffic you want and access whatever resources/site you need.

My inspiration came from this project but as I don't want to install npm and nodejs to use this tool, I remade it in ~~Haskell~~ Rust and improved it.

What to expect:

Easy to use
Good error messages and debug information
Static forward (reverse) tunneling (TCP, UDP, Unix socket, Stdio)
Dynamic (reverse) tunneling (Socks5 proxy, HTTP proxy and Transparent Proxy)
Support for using http proxy (when behind one) as gateway
Support of proxy protocol
Support for tls/https server with certificates auto-reload (with embedded self-signed certificate, or your own)
Support of mTLS with certificates auto-reload - documentation here
Support IPv6
Support for Websocket and HTTP2 as transport protocol (websocket is more performant)
Standalone binaries (so just cp it where you want) here

Note

v7.0.0 is a complete rewrite of wstunnel in Rust and is not compatible with previous version. Previous code in Haskell can be found on branch https://github.com/erebe/wstunnel/tree/haskell

What to expect from previous version:

More throughput and less jitter due to Haskell GC. Most of you will not care, as it was performant enough already. But you can now saturate a gigabit ethernet card with a single connection
Command line is more homogeneous/has better UX. All tunnel can be specified multiple times
Tunnel protocol tries to look like normal traffic, to avoid being flagged
Support of reverse tunneling
New bug, it is a rewrite (â¯'â¡')â¯ï¸µ â»ââ» Â¯\(ã)/Â¯
Mainly for me to ease the maintenance of the project. I don't do a lot of haskell nowadays and it was harder for me to keep maintening the project over time, as I get lost in touch of the Haskell ecosystem and new release.
Armv7 build (aka raspberry pi), as new version of GHC (Haskell compiler) dropped its support

Demo server

If you just want to try out that you can bypass your proxy/firewall. You can give it a try with wstunnel demo server.

# In a terminal start wstunnel client
# You can set as tls-sni-override whatever domain you want. The tunnel is the only one that is going to be allowed. 
wstunnel client -L 'tcp://4443:localhost:444?proxy_protocol' -P demo --tls-sni-override=google.fr wss://49.13.58.9

# on another terminal, run curl and it should return you this greetings
curl -k https://localhost:4443
> Memento mori !

Command line

Usage: wstunnel client [OPTIONS] <ws[s]|http[s]://wstunnel.server.com[:port]>

Arguments:
  <ws[s]|http[s]://wstunnel.server.com[:port]>
          Address of the wstunnel server
          You can either use websocket or http2 as transport protocol. Use websocket if you are unsure.
          Example: For websocket with TLS wss://wstunnel.example.com or without ws://wstunnel.example.com
                   For http2 with TLS https://wstunnel.example.com or without http://wstunnel.example.com
          
          *WARNING* HTTP2 as transport protocol is harder to make it works because:
            - If you are behind a (reverse) proxy/CDN they are going to buffer the whole request before forwarding it to the server
              Obviously, this is not going to work for tunneling traffic
            - if you have wstunnel behind a reverse proxy, most of them (i.e: nginx) are going to turn http2 request into http1
              This is not going to work, because http1 does not support streaming naturally
          The only way to make it works with http2 is to have wstunnel directly exposed to the internet without any reverse proxy in front of it

Options:
  -L, --local-to-remote <{tcp,udp,socks5,stdio,unix}://[BIND:]PORT:HOST:PORT>
          Listen on local and forwards traffic from remote. Can be specified multiple times
          examples:
          'tcp://1212:google.com:443'      =>       listen locally on tcp on port 1212 and forward to google.com on port 443
          'tcp://2:n.lan:4?proxy_protocol' =>       listen locally on tcp on port 2 and forward to n.lan on port 4
                                                    Send a proxy protocol header v2 when establishing connection to n.lan
          
          '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
          '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]
          
          'socks5://[::1]:1212'            =>       listen locally with socks5 on port 1212 and forward dynamically requested tunnel
          'socks5://[::1]:1212?login=admin&password=admin' => listen locally with socks5 on port 1212 and only accept connection with login=admin and password=admin
          
          'http://[::1]:1212'              =>       start a http proxy on port 1212 and forward dynamically requested tunnel
          'http://[::1]:1212?login=admin&password=admin' => start a http proxy on port 1212 and only accept connection with login=admin and password=admin

          'tproxy+tcp://[::1]:1212'        =>       listen locally on tcp on port 1212 as a *transparent proxy* and forward dynamically requested tunnel
          'tproxy+udp://[::1]:1212?timeout_sec=10'  listen locally on udp on port 1212 as a *transparent proxy* and forward dynamically requested tunnel
                                                    linux only and requires sudo/CAP_NET_ADMIN
          
          'stdio://google.com:443'         =>       listen for data from stdio, mainly for `ssh -o ProxyCommand="wstunnel client --log-lvl=off -L stdio://%h:%p ws://localhost:8080" my-server`
          
          'unix:///tmp/wstunnel.sock:g.com:443' =>  listen for data from unix socket of path /tmp/wstunnel.sock and forward to g.com:443

  -R, --remote-to-local <{tcp,udp,socks5,unix}://[BIND:]PORT:HOST:PORT>
          Listen on remote and forwards traffic from local. Can be specified multiple times. Only tcp is supported
          examples:
          'tcp://1212:google.com:443'      =>     listen on server for incoming tcp cnx on port 1212 and forward to google.com on port 443 from local machine
          'udp://1212:1.1.1.1:53'          =>     listen on server for incoming udp on port 1212 and forward to cloudflare dns 1.1.1.1 on port 53 from local machine
          'socks5://[::1]:1212'            =>     listen on server for incoming socks5 request on port 1212 and forward dynamically request from local machine
          'http://[::1]:1212'              =>     listen on server for incoming http proxy request on port 1212 and forward dynamically request from local machine (login/password is supported)
          'unix://wstunnel.sock:g.com:443' =>     listen on server for incoming data from unix socket of path wstunnel.sock and forward to g.com:443 from local machine

      --no-color <NO_COLOR>
          Disable color output in logs
          
          [env: NO_COLOR=]

      --socket-so-mark <INT>
          (linux only) Mark network packet with SO_MARK sockoption with the specified value.
          You need to use {root, sudo, capabilities} to run wstunnel when using this option

  -c, --connection-min-idle <INT>
          Client will maintain a pool of open connection to the server, in order to speed up the connection process.
          This option set the maximum number of connection that will be kept open.
          This is useful if you plan to create/destroy a lot of tunnel (i.e: with socks5 to navigate with a browser)
          It will avoid the latency of doing tcp + tls handshake with the server
          
          [default: 0]

      --nb-worker-threads <INT>
          *WARNING* The flag does nothing, you need to set the env variable *WARNING*
          Control the number of threads that will be used.
          By default, it is equal the number of cpus
          
          [env: TOKIO_WORKER_THREADS=]

      --log-lvl <LOG_LEVEL>
          Control the log verbosity. i.e: TRACE, DEBUG, INFO, WARN, ERROR, OFF
          for more details: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax
          
          [env: RUST_LOG=]
          [default: INFO]

      --tls-sni-override <DOMAIN_NAME>
          Domain name that will be used as SNI during TLS handshake
          Warning: If you are behind a CDN (i.e: Cloudflare) you must set this domain also in the http HOST header.
                   or it will be flagged as fishy and your request rejected

      --tls-sni-disable
          Disable sending SNI during TLS handshake
          Warning: Most reverse proxies rely on it

      --tls-verify-certificate
          Enable TLS certificate verification.
          Disabled by default. The client will happily connect to any server with self-signed certificate.

  -p, --http-proxy <USER:PASS@HOST:PORT>
          If set, will use this http proxy to connect to the server
          
          [env: HTTP_PROXY=]

      --http-proxy-login <LOGIN>
          If set, will use this login to connect to the http proxy. Override the one from --http-proxy
          
          [env: WSTUNNEL_HTTP_PROXY_LOGIN=]

      --http-proxy-password <PASSWORD>
          If set, will use this password to connect to the http proxy. Override the one from --http-proxy
          
          [env: WSTUNNEL_HTTP_PROXY_PASSWORD=]

  -P, --http-upgrade-path-prefix <HTTP_UPGRADE_PATH_PREFIX>
          Use a specific prefix that will show up in the http path during the upgrade request.
          Useful if you need to route requests server side but don't have vhosts
          
          [env: WSTUNNEL_HTTP_UPGRADE_PATH_PREFIX=]
          [default: v1]

      --http-upgrade-credentials <USER[:PASS]>
          Pass authorization header with basic auth credentials during the upgrade request.
          If you need more customization, you can use the http_headers option.

      --websocket-ping-frequency-sec <seconds>
          Frequency at which the client will send websocket ping to the server.
          
          [default: 30]

      --websocket-mask-frame
          Enable the masking of websocket frames. Default is false
          Enable this option only if you use unsecure (non TLS) websocket server, and you see some issues. Otherwise, it is just overhead.

  -H, --http-headers <HEADER_NAME: HEADER_VALUE>
          Send custom headers in the upgrade request
          Can be specified multiple time

      --http-headers-file <FILE_PATH>
          Send custom headers in the upgrade request reading them from a file.
          It overrides http_headers specified from command line.
          File is read everytime and file format must contain lines with `HEADER_NAME: HEADER_VALUE`

      --tls-certificate <FILE_PATH>
          [Optional] Certificate (pem) to present to the server when connecting over TLS (HTTPS).
          Used when the server requires clients to authenticate themselves with a certificate (i.e. mTLS).
          The certificate will be automatically reloaded if it changes

      --tls-private-key <FILE_PATH>
          [Optional] The private key for the corresponding certificate used with mTLS.
          The certificate will be automatically reloaded if it changes

      --dns-resolver <DNS_RESOLVER>
          Dns resolver to use to lookup ips of domain name. Can be specified multiple time
          Example:
           dns://1.1.1.1 for using udp
           dns+https://1.1.1.1?sni=cloudflare-dns.com for using dns over HTTPS
           dns+tls://8.8.8.8?sni=dns.google for using dns over TLS
          For Dns over HTTPS/TLS if an HTTP proxy is configured, it will be used also
          To use libc resolver, use
          system://0.0.0.0

          **WARN** On windows you may want to specify explicitly the DNS resolver to avoid excessive DNS queries

SERVER
Usage: wstunnel server [OPTIONS] <ws[s]://0.0.0.0[:port]>

Arguments:
  <ws[s]://0.0.0.0[:port]>
          Address of the wstunnel server to bind to
          Example: With TLS wss://0.0.0.0:8080 or without ws://[::]:8080
          
          The server is capable of detecting by itself if the request is websocket or http2. So you don't need to specify it.

Options:
      --socket-so-mark <INT>
          (linux only) Mark network packet with SO_MARK sockoption with the specified value.
          You need to use {root, sudo, capabilities} to run wstunnel when using this option

      --websocket-ping-frequency-sec <seconds>
          Frequency at which the server will send websocket ping to client.

      --no-color <NO_COLOR>
          Disable color output in logs
          
          [env: NO_COLOR=]

      --websocket-mask-frame
          Enable the masking of websocket frames. Default is false
          Enable this option only if you use unsecure (non TLS) websocket server, and you see some issues. Otherwise, it is just overhead.

      --nb-worker-threads <INT>
          *WARNING* The flag does nothing, you need to set the env variable *WARNING*
          Control the number of threads that will be used.
          By default, it is equal the number of cpus
          
          [env: TOKIO_WORKER_THREADS=]

      --restrict-to <DEST:PORT>
          Server will only accept connection from the specified tunnel information.
          Can be specified multiple time
          Example: --restrict-to "google.com:443" --restrict-to "localhost:22"

      --dns-resolver <DNS_RESOLVER>
          Dns resolver to use to lookup ips of domain name
          This option is not going to work if you use transparent proxy
          Can be specified multiple time
          Example:
           dns://1.1.1.1 for using udp
           dns+https://1.1.1.1?sni=loudflare-dns.com for using dns over HTTPS
           dns+tls://8.8.8.8?sni=dns.google for using dns over TLS
          To use libc resolver, use
          system://0.0.0.0

      --log-lvl <LOG_LEVEL>
          Control the log verbosity. i.e: TRACE, DEBUG, INFO, WARN, ERROR, OFF
          for more details: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax
          
          [env: RUST_LOG=]
          [default: INFO]

  -r, --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. Can be specified multiple time
          
          [env: WSTUNNEL_RESTRICT_HTTP_UPGRADE_PATH_PREFIX=]

      --restrict-config <RESTRICT_CONFIG>
          Path to the location of the restriction yaml config file.
          Restriction file is automatically reloaded if it changes

      --tls-certificate <FILE_PATH>
          [Optional] Use custom certificate (pem) instead of the default embedded self-signed certificate.
          The certificate will be automatically reloaded if it changes

      --tls-private-key <FILE_PATH>
          [Optional] Use a custom tls key (pem, ec, rsa) that the server will use instead of the default embedded one
          The private key will be automatically reloaded if it changes

      --tls-client-ca-certs <FILE_PATH>
          [Optional] Enables mTLS (client authentication with certificate). Argument must be PEM file
          containing one or more certificates of CA's of which the certificate of clients needs to be signed with.
          The ca will be automatically reloaded if it changes
          
    -p, --http-proxy <USER:PASS@HOST:PORT>
          If set, will use this http proxy to connect to the client

          [env: HTTP_PROXY=]

      --http-proxy-login <LOGIN>
          If set, will use this login to connect to the http proxy. Override the one from --http-proxy

          [env: WSTUNNEL_HTTP_PROXY_LOGIN=]

      --http-proxy-password <PASSWORD>
          If set, will use this password to connect to the http proxy. Override the one from --http-proxy

          [env: WSTUNNEL_HTTP_PROXY_PASSWORD=]

Release

Static binaries are available in release section

docker image are available at https://github.com/erebe/wstunnel/pkgs/container/wstunnel

docker pull ghcr.io/erebe/wstunnel:latest

Examples

Understand command line syntax
Simplest one with socks5 - Good for browsing internet
Proxy SSH
Bypass a corporate proxy
Proxy Wireguard traffic
Proxy easily any traffic with transparent proxy (linux only)
Reverse tunneling
How to secure access of your wstunnel server
Use HTTP2 instead of websocket for transport protocol
Maximize your stealthiness/Make your traffic discrete

Understand command line syntax

Wstunnel command line mimic ssh tunnel syntax. You can take reference to this article, or this diagram to understand

Simplest one

On your remote host, start the wstunnel's server by typing this command in your terminal

wstunnel server wss://[::]: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

wstunnel client -L socks5://127.0.0.1:8888 --connection-min-idle 5 wss://myRemoteHost:8080

This command will create a socks5 server listening on port 8888 of the loopback interface and will forward traffic dynamically. connection-min-idle 10 is going an optimization to create a pool of 10 connection connected to the server, to speed-up the establishement of new tunnels.

With firefox you can setup a proxy using this tunnel, by setting in networking preferences 127.0.0.1:8888 and selecting socks5 proxy. Be sure to check the option Proxy DNS when using SOCKS v5 for the server to resolve DNS name and not your local machine.

or with curl

curl -x socks5h://127.0.0.1:8888 http://google.com/
#Please note h after the 5, it is to avoid curl resolving DNS name locally

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

ssh -o ProxyCommand="wstunnel client --log-lvl=off -L stdio://%h:%p ws://myRemoteHost:8080" my-server

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://[::]: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.

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.

Do not rely on wstunnel to protect your privacy, if it is one of your concerns, you should only forwards traffic that is already secure by design (ie: https or vpn traffic)

Now on the client side start the client with

wstunnel client -L tcp://9999:127.0.0.1:22 -p http://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.

You may now access your server from your local machine on ssh by using

ssh -p 9999 login@127.0.0.1

Wireguard and wstunnel

You have a working wireguard client configuration called wg0.conf. Let's say

[Interface]
Address = 10.200.0.2/32, fd00:cafe::2/128
PrivateKey = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=

[Peer]
PublicKey = 9iicV7Stdl/U0RH1BNf3VvlVjaa4Eus6QPEfEz6cR0c=
AllowedIPs = 0.0.0.0/0, ::/0
Endpoint = my.server.com:51820

Start wstunnel server on my.server.com like this

wstunnel server --restrict-to localhost:51820 wss://[::]:443

on your local machine start the client like this

wstunnel client -L 'udp://51820:localhost:51820?timeout_sec=0' wss://my.server.com:443

change your wireguard client config to something

[Interface]
Address = 10.200.0.2/32, fd00:cafe::2/128
PrivateKey = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=
# Replace by a dns your server has access to
dns = 8.8.8.8
# https://github.com/nitred/nr-wg-mtu-finder to find best mtu for you
MTU = 1400 

[Peer]
PublicKey = 9iicV7Stdl/U0RH1BNf3VvlVjaa4Eus6QPEfEz6cR0c=
AllowedIPs = 0.0.0.0/0, ::/0
# Should target port where wstunnel client is listenning to
Endpoint = localhost:51820
# Should not be necessary if you enable wstunnel client websocket ping
PersistentKeepalive = 20

Add a default route to your server, as your AllowedIps are catch-all, it is to avoid the traffic looping.

sudo ip route add ip.of.my.server.com dev eth0 via 192.168.0.1
# replace eth0 (interface) and 192.168.0.1 (router gateway) by the one given by `ip route get ip.of.my.server.com`

start your wireguard, and it should be working

sudo wg-quick up wg0
ping 10.200.0.1 # ping another ip of your vpn network

FAQ

Disable default udp tunnel timeout that will auto-close it after 30sec. i.e: udp://1212:127.0.0.1:5201?timeout_sec=0
If you see some throughput issue, be sure to lower the MTU of your wireguard interface (you can do it via config file) to something like 1300 or you will endup fragmenting udp packet (due to overhead of other layer) which is always causing issues
If wstunnel cannot connect to server while wireguard is on, be sure you have added a static route via your main gateway for the ip of wstunnel server. Else if you forward all the traffic without putting a static route, you will endup looping your traffic wireguard interface -> wstunnel client -> wireguard interface
If you have trouble making it works on windows, please check this issue https://github.com/erebe/wstunnel/issues/252

Transparent proxy (linux only)

Transparent proxy allows to easily proxy any program. Start wstunnel with

sudo wstunnel client -L 'tproxy+tcp://1080' -L 'tproxy+udp://1080' wss://my.server.com:443

use this project to route traffic seamlessly https://github.com/NOBLES5E/cproxy. It works with any program

cproxy --port 1080 --mode tproxy -- curl https://google.com

You can even start a new shell, were all your commands will be proxyfied

cproxy --port 1080 --mode tproxy -- bash

Reverse tunneling

Start wstunnel with

sudo wstunnel client -R 'tcp://[::]:8000:localhost:8000' wss://my.server.com:443

In another terminal, start a simple webserver on your local machine

python3 -m http.server

From your my.server.com machine/network you can now do

curl http://localhost:8000

How to secure the access of your wstunnel server

Generate a secret, let's say h3GywpDrP6gJEdZ6xbJbZZVFmvFZDCa4KcRd

Now start you server with the following command

wstunnel server --restrict-http-upgrade-path-prefix h3GywpDrP6gJEdZ6xbJbZZVFmvFZDCa4KcRd  wss://[::]:443

And start your client with

wstunnel client --http-upgrade-path-prefix h3GywpDrP6gJEdZ6xbJbZZVFmvFZDCa4KcRd ... wss://myRemoteHost

Now your wstunnel server, will only accept connection if the client specify the correct path prefix during the upgrade request.

If you need more customization, you can use a config file to specify specific rules with --restrict-config. You can find examples of restriction rules there

Use HTTP2 instead of websocket for the transport protocol

Use this only if websocket is blocked by your firewall/proxy. Otherwise, it is less performant than websocket.

Start your wstunnel server as usual with

wstunnel server wss://[::]:8080

On the client the only difference is to specify https:// instead of wss://

wstunnel client -L socks5://127.0.0.1:8888 https://myRemoteHost:8080

WARNING HTTP2 as transport protocol is harder to make it works because:

If you are behind a (reverse) proxy/CDN they may buffer the whole request before forwarding it to the server. Cloudflare is doing that, and obviously, this is not going to work for tunneling traffic
if you have wstunnel behind a reverse proxy, most of them (i.e: nginx) are going to turn http2 request into http1 This is not going to work, because http1 does not support streaming naturally

The only way to make it works with HTTP2 is to have wstunnel server directly exposed to the internet without any reverse proxy in front of it

In addition, you may also want to play with the request headers (i.e: content-length and content-type) to make it looks like normal traffic to bypass your firewall/proxy. Some firewall may not like to see request with content-length not set, or with content-type set to application/octet-stream

Maximize your stealthiness/Make your traffic discrete

Use wstunnel with TLS activated (wss://) and use your own certificate
- Embedded certificate is self-signed and are the same for everyone, so can be easily fingerprinted/flagged
- Use valid certificate (i.e: with Let's Encrypt), self-signed certificate are suspicious
Use a custom http path prefix (see --http-upgrade-path-prefix option)
- To avoid having the same url than every other wstunnel user
Change your tls-sni-override to a domain is known to be allowed (i.e: google.com, baidu.com, etc...)
- this will not work if your wstunnel server is behind a reverse proxy (i.e: Nginx, Cloudflare, HAProxy, ...)

Benchmark

How to Build

Install the Rust https://www.rust-lang.org/tools/install or if you are a believer

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

and run those commands at the root of the project

cargo build
target/debug/wstunnel ...

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Getting Started

Competitor Comparisons

Pros of frp

Cons of frp

Code Comparison

Key Differences

Pros of Chisel

Cons of Chisel

Code Comparison

Key Differences

Use Cases

Pros of gost

Cons of gost

Code Comparison

Pros of SirTunnel

Cons of SirTunnel

Code Comparison

Pros of go-http-tunnel

Cons of go-http-tunnel

Code Comparison

Summary

Pros of sslh

Cons of sslh

Code Comparison

Convert designs to code with AI

README

Summary

Description

Sponsors

Note

Demo server

Command line

Release

Examples

Understand command line syntax

Simplest one

As proxy command for SSH

When behind a corporate proxy

Wireguard and wstunnel

Transparent proxy (linux only)

Reverse tunneling

How to secure the access of your wstunnel server

Use HTTP2 instead of websocket for the transport protocol

Maximize your stealthiness/Make your traffic discrete

Benchmark

How to Build

Top Related Projects

Convert designs to code with AI