wstunnel: TCP/UDP su WebSocket nel 2026 (guida completa)

Divulgazione affiliati — Questo articolo contiene link affiliati a Contabo. Se ordini un VPS tramite i nostri link, guadagniamo una commissione senza costi aggiuntivi per te. Le nostre raccomandazioni si basano sul comportamento documentato degli strumenti e sulle specifiche pubblicate dal fornitore.

Conosci la storia: il tuo VPN WireGuard funziona perfettamente a casa, vai dal cliente o ti siedi in uno spazio di coworking, e la porta UDP 51820 è bloccata. Il Wi-Fi aziendale lascia passare solo 80, 443, a volte 22, e basta. Accedi tramite il captive portal, il tuo tunnel non si attiva e sei bloccato fuori dalla tua infrastruttura.

Questo è lo scenario esatto che wstunnel risolve. L'idea è semplice: incapsulare qualsiasi traffico TCP o UDP in WebSocket sulla porta 443 — il che significa far sembrare il tuo WireGuard (UDP) un legittimo traffico WebSocket HTTPS. Il firewall vede wss://cdn.tuodominio.com sulla porta 443, lo lascia passare, e dall'altra parte wstunnel spacchetta per restituire i pacchetti UDP a WireGuard.

Questa guida copre l'installazione di wstunnel su un VPS Contabo (Ubuntu 24.04), la configurazione del client su Linux/Windows/macOS/Android, i compromessi in termini di latenza e throughput da aspettarsi, e quando wstunnel è la scelta giusta rispetto a V2Ray o Cloak.

Perché wstunnel funziona dove WireGuard semplice fallisce

Tre famiglie di blocchi uccidono un tunnel WireGuard "vanilla":

• Firewall aziendale classico: lista di permessi di uscita restrittiva, solo 80/443/53 escono. La porta UDP 51820 non ha possibilità.
• Portali captive di hotel/aeroporti: prima dell'autenticazione, tutto tranne 80/443 TCP viene bloccato. E anche dopo il login, alcuni mantengono chiuso l'UDP.
• DPI nazionale/aziendale avanzato: vede l'handshake WireGuard, identifica il protocollo e lo blocca. La porta di ascolto non importa.

WebSocket su 443 bypassa i primi due perché È HTTPS — un aggiornamento da HTTP/1.1, accettato da ogni proxy TLS. Per il DPI nazionale (GFW, SmartFilter), è necessario abbinarlo a un vero TLS e un certificato valido; wstunnel gestisce questo tramite wss://.

Lo strumento wstunnel è scritto in Rust da Erebe (repo GitHub). È un singolo binario, ~7 MB, che funge sia da server che da client. Nessun Python da patchare, nessun Node.js da mantenere, nessun Docker obbligatorio. Copi il binario, esegui un comando, il tunneling inizia.

Installazione del server su un VPS Contabo

Usiamo un VPS Contabo S (4 vCPU, 8 GB RAM, €4,99/mese) che esegue Ubuntu 24.04 LTS. Se non hai ancora un VPS, controlla l'offerta Contabo VPS S 24 mesi. Puoi condividere questo VPS con il tuo WireGuard esistente — wstunnel utilizza meno di 50 MB di RAM a riposo.

Passo 1 — Scarica il binario wstunnel

WSTUNNEL_VER="10.1.4"  # controlla l'ultima versione su github.com/erebe/wstunnel/releases
curl -L -o /usr/local/bin/wstunnel \
  "https://github.com/erebe/wstunnel/releases/download/v${WSTUNNEL_VER}/wstunnel_${WSTUNNEL_VER}_linux_amd64"
chmod +x /usr/local/bin/wstunnel
wstunnel --version

Passo 2 — Dominio + proxy inverso Caddy (consigliato)

Per un credibile wss://, mettiamo Caddy davanti per gestire automaticamente il TLS di Let's Encrypt. Prerequisito: un dominio che punta all'IP del VPS (record A cdn.tuodominio.com → 188.245.x.x).

# Installazione di Caddy
apt update && apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
apt update && apt install -y caddy

/etc/caddy/Caddyfile:

cdn.tuodominio.com {
  root * /var/www/html
  file_server

  @ws {
    path /ws/*
    header Connection *Upgrade*
    header Upgrade websocket
  }
  reverse_proxy @ws 127.0.0.1:8080
}

Il blocco @ws corrisponde solo alle richieste di aggiornamento WebSocket sul percorso /ws/*. Ogni altra richiesta vede un normale sito HTML statico (metti un blog fittizio o una pagina di manutenzione in /var/www/html).

Passo 3 — Servizio systemd wstunnel

/etc/systemd/system/wstunnel.service:

[Unit]
Description=wstunnel server
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/wstunnel server ws://127.0.0.1:8080 \
  --restrict-to 127.0.0.1:51820
Restart=always
RestartSec=5
User=nobody

[Install]
WantedBy=multi-user.target

Il flag --restrict-to impedisce ai client di utilizzare wstunnel come proxy aperto: solo 127.0.0.1:51820 (il nostro WireGuard) sarà consentito. Critico per la sicurezza.

systemctl daemon-reload
systemctl enable --now caddy wstunnel
journalctl -u wstunnel -f  # verifica che stia ascoltando

A questo punto il tuo server espone https://cdn.tuodominio.com (pagina HTML fittizia) e un tunnel WS su wss://cdn.tuodominio.com/ws/*. Nessuna porta UDP esotica esposta esternamente — per un firewall, è un normale sito HTTPS.

Configurazione del client: Linux, Windows, macOS, Android

Il binario client wstunnel è lo stesso del server. Scarichi la versione giusta per il tuo sistema operativo ed esegui un comando diverso.

Linux / macOS:

wstunnel client \
  --local-to-remote 'udp://51820:127.0.0.1:51820' \
  wss://cdn.tuodominio.com/ws

Questo apre un listener UDP locale su 127.0.0.1:51820 e incapsula tutto ciò che arriva lì verso 127.0.0.1:51820 sul server tramite WebSocket sulla porta 443. Poi punti la tua configurazione locale di WireGuard a Endpoint = 127.0.0.1:51820 invece dell'IP pubblico del VPS.

Esempio di configurazione client WireGuard (/etc/wireguard/wg0-via-ws.conf):

[Interface]
PrivateKey = YOUR_CLIENT_PRIVATE_KEY
Address = 10.7.0.2/24
DNS = 1.1.1.1

[Peer]
PublicKey = SERVER_PUBLIC_KEY
AllowedIPs = 0.0.0.0/0
Endpoint = 127.0.0.1:51820   # locale — wstunnel inoltra
PersistentKeepalive = 25

Avvia in questo ordine:

wstunnel client --local-to-remote 'udp://51820:127.0.0.1:51820' wss://cdn.tuodominio.com/ws &
wg-quick up wg0-via-ws

Windows: scarica wstunnel.exe dalla pagina delle release, avvia da un PowerShell amministrativo. Per automatizzare, crea un'attività pianificata wstunnel-client che si avvia al login. L'app ufficiale WireGuard per Windows accetta Endpoint = 127.0.0.1:51820 senza problemi.

Android: non viene distribuito ufficialmente un binario ARM nativo, ma Termux ti permette di compilare o recuperare la build ARM64 (wstunnel_*_linux_arm64). Combinato con WireGuard Android e la funzione "App escluse" per escludere il PID di Termux, funziona. È l'opzione meno pronta all'uso — su mobile, V2Ray Android è più semplice se non hai bisogno specificamente di WireGuard.

Cosa aspettarsi: latenza e throughput

Ogni strato che aggiungi per incapsulare WireGuard in WebSocket/TLS comporta un certo costo in termini di latenza e throughput. La tabella seguente mostra la direzione del compromesso — misura il tuo percorso con iperf3 e ping per numeri esatti, poiché dipendono fortemente dal tuo collegamento e dal datacenter scelto.

Lettura: incapsulare WireGuard in TLS aggiunge un modesto overhead di latenza e riduce significativamente il throughput — è il prezzo da pagare per attraversare un firewall aziendale o un DPI. Mettere Cloudflare davanti aggiunge un altro salto in più.

Per la navigazione web, video Zoom/Meet 720p e Netflix HD: nessuna differenza percepibile. Per 4K, giochi competitivi o trasferimenti di grandi dimensioni, il tunnel WS è subottimale — torna a WireGuard semplice quando possibile.

Casi d'uso tipici

1. Dipendente remoto dietro un firewall aziendale rigido. Configurazione classica: VPS personale Contabo + wstunnel + WireGuard per ricollegarsi alla tua rete domestica (NAS, Home Assistant, box di sviluppo). Il firewall aziendale vede HTTPS verso un dominio personale, non blocca. Compatibile con politiche BYOD ragionevoli.

2. Nomade digitale con Wi-Fi degli hotel imprevedibile. wstunnel è il tuo piano B quando WireGuard non riesce a uscire. Tieni un profilo "WireGuard diretto" per le reti buone, un profilo "via wstunnel" per quelle cattive. Cambio manuale in 5 secondi.

3. CTF / pentest / homelab. Quando vuoi esporre un servizio interno (laboratorio RDP Windows, dev MySQL, bastione SSH) sulla porta 443 di un VPS pubblico senza toccare il proxy inverso dell'applicazione. wstunnel TCP è più semplice del tunneling SSH per i membri del team meno tecnici.

4. Migrazione progressiva da un VPN consumer a uno self-hosted. Se utilizzi ancora un VPN commerciale e vuoi testare l'auto-hosting mantenendo un fallback: metti in piedi il tuo stack Contabo + WireGuard + wstunnel, e mantieni attivo il tuo abbonamento VPN commerciale per un mese come backup. Una volta che la configurazione self-hosted si dimostra stabile, puoi annullare il servizio a pagamento.

Rafforzare la distribuzione

Autenticazione forte del client. Per impostazione predefinita, chiunque conosca l'URL wss://cdn.tuodominio.com/ws può aprire un tunnel. Abilita l'opzione --http-upgrade-path-prefix con un segreto casuale di 32 caratteri:

# Lato server
wstunnel server ws://127.0.0.1:8080 --http-upgrade-path-prefix /secret-abc123xyz

# Lato client
wstunnel client --http-upgrade-path-prefix /secret-abc123xyz ...

Senza il prefisso corretto, il server restituisce 404. Combinato con fail2ban sui log di Caddy, questo blocca gli scanner veloci.

Restringi esplicitamente le destinazioni. Il --restrict-to 127.0.0.1:51820 consente solo il tunneling verso il WireGuard locale. Non ometterlo — altrimenti il tuo VPS diventa un proxy aperto che i bot abuseranno.

fail2ban su 404 di Caddy. Aggiungi una jail che banna un IP dopo 10 risposte 404 in 60 secondi:

# /etc/fail2ban/jail.d/caddy-404.conf
[caddy-404]
enabled = true
port = http,https
filter = caddy-404
logpath = /var/log/caddy/access.log
maxretry = 10
findtime = 60
bantime = 3600

Il filtro caddy-404.conf corrisponde alle righe JSON con "status":404 — vedi documentazione logging di Caddy per lo schema esatto.

Rinnovo del certificato. Caddy gestisce Let's Encrypt automaticamente, nulla da fare. Controlla ogni 60 giorni con caddy adapt che la configurazione sia ancora valida.

wstunnel vs alternative

Verdetto pragmatico:

• Solo / 1–3 utenti / bypass aziendale o DPI leggero → wstunnel.
• Multi-utente / bypass GFW Cina → V2Ray (vedi la nostra guida V2Ray VMess/VLess).
• Vuoi aggiungere un livello TLS su un WireGuard esistente senza rifare tutto → Cloak.
• Vuoi solo uscire da una rete aziendale per SSH / web → sshuttle (nessun VPS richiesto).

Risoluzione dei problemi comuni

Sintomo: wss handshake failed: 502 bad gateway. Il server wstunnel non sta ascoltando su 8080, o Caddy non riesce a trovarlo. Controlla systemctl status wstunnel e ss -tlnp | grep 8080.

Sintomo: il tunnel si attiva ma non fluisce traffico. Il WireGuard lato server non autorizza il peer client. Ricontrolla wg show e il blocco [Peer] del server — di solito un errore di copia-incolla in AllowedIPs.

Sintomo: throughput anormalmente basso (< 30 Mbps). Proxy Cloudflare abilitato (nuvola arancione): Cloudflare limita i WebSocket sul piano gratuito. Disabilita il proxy DNS (nuvola grigia) o spostati su un dominio senza Cloudflare.

Sintomo: disconnessioni ogni 10 minuti. Caddy ha un timeout predefinito sulle sessioni WS lunghe. Aggiungi all'interno del blocco reverse_proxy:

reverse_proxy @ws 127.0.0.1:8080 {
  transport http {
    keepalive 30s
    keepalive_idle_conns 100
  }
}

Ulteriori letture

• VPN self-host su Contabo: guida completa WireGuard 2026
• V2Ray VMess/VLess: configurazione completa 2026
• Cloak: offuscamento TLS per VPN self-host
• Instradamento VPN personalizzato su Contabo: bypass DPI Iran / Cina

Fonti e riferimenti:

• Erebe/wstunnel — repo ufficiale GitHub
• RFC 6455 — Il protocollo WebSocket
• Documentazione Caddy — direttiva reverse_proxy
• Whitepaper WireGuard — Jason A. Donenfeld

Pubblicato il 2026-06-03. Test eseguiti su un VPS Contabo S Norimberga + client fibra residenziale a Parigi, marzo 2026. Le prestazioni possono variare notevolmente a seconda del datacenter Contabo scelto, dell'ISP del client e della qualità del peering — sempre eseguire benchmark nel proprio contesto prima di impegnarsi in una configurazione.

Promemoria: wstunnel e l'auto-hosting di VPN sono perfettamente legali nell'UE, negli Stati Uniti, in Canada e nella maggior parte dei paesi democratici. Controlla le normative locali in Cina, Iran, UAE, Russia prima di distribuire — VPNSmith pubblica questo contenuto a scopo educativo.