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

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.

Carta bancaria rifiutata? Ultahost accetta anche Bitcoin e altre criptovalute, Alipay, WeChat Pay e Qiwi (pagina dei pagamenti, letta il 25 ottobre 2026). Link di affiliazione; controlla le sue condizioni per il tuo paese prima di ordinare.

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

Questa guida presuppone un Contabo Cloud VPS 4 (4 vCPU, 8 GB RAM, €5,50/mese) che esegue Ubuntu 24.04 LTS. Se non hai ancora un VPS, controlla l'offerta Contabo Cloud VPS 4 24 mesi. Puoi condividere questo VPS con il tuo WireGuard esistente: wstunnel è un singolo binario leggero.

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 \
  --http-upgrade-path-prefix ws \
  --local-to-remote 'udp://51820:127.0.0.1:51820?timeout_sec=0' \
  wss://cdn.tuodominio.com

Due dettagli contano. --http-upgrade-path-prefix ws fa passare il client da /ws/, il percorso che Caddy inoltra; senza, il client usa il prefisso predefinito v1 e Caddy risponde con il sito statico. ?timeout_sec=0 disattiva il timeout UDP predefinito di 30 secondi di wstunnel, che altrimenti chiude un tunnel WireGuard inattivo (README di wstunnel). Se passi a un prefisso segreto (più sotto), cambia anche il matcher Caddy path /ws/* in path /tuo-segreto/*.

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.

Non hai ancora una configurazione WireGuard, né sul server né sul client? Il nostro generatore di configurazione WireGuard gratuito crea le coppie di chiavi nel tuo browser (non ci viene inviato nulla) e scrive i file server e client; una volta generati, sostituisci la riga Endpoint del client con 127.0.0.1:51820 come sopra.

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 --http-upgrade-path-prefix ws --local-to-remote 'udp://51820:127.0.0.1:51820?timeout_sec=0' wss://cdn.tuodominio.com &
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 e le normali videochiamate il sovraccarico aggiunto è di solito tollerabile, ma non lo abbiamo misurato: prova il tuo collegamento. 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 --restrict-to 127.0.0.1:51820 \
  --restrict-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 molto inferiore a WireGuard semplice. Se il proxy Cloudflare è abilitato (nuvola arancione), ogni pacchetto fa un salto in più attraverso Cloudflare. Disabilita il proxy DNS (nuvola grigia) per confrontare, 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
  }
}

Per avere la decisione a portata di mano: la nostra Home Server Remote Access Cheat Sheet gratuita (PDF di 4 pagine in inglese, download diretto, senza registrazione) spiega come distinguere CGNAT, doppio NAT e IP dinamico, quale metodo scegliere in ogni caso, e i comandi per DDNS, un relay WireGuard su un VPS, Cloudflare Tunnel o Pangolin, e wstunnel. Scarica la scheda.

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. 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. Controlla le normative locali in Cina, Iran, UAE, Russia prima di distribuire - VPNSmith pubblica questo contenuto a scopo educativo.