WireGuard «handshake did not complete»: la lista completa di soluzioni (2026)

Informativa affiliazione — Questo articolo contiene link di affiliazione Contabo. Se prendi un VPS tramite loro, guadagniamo una commissione senza costi extra per te. Ogni comando e configurazione qui sotto è documentato da fonti ufficiali WireGuard e scritto per essere riproducibile sul tuo VPS.

Scrivi wg show, vedi il tuo peer, e proprio sotto c'è la riga che ti rovina la serata: latest handshake è vuota, o wg-quick ti avverte handshake did not complete. Il tuo tunnel è su sulla carta ma non passa traffico. La buona notizia: WireGuard fallisce per un elenco breve e finito di ragioni, e arrivano in un ordine prevedibile. Questa guida percorre quell'ordine dal più comune al più raro, per smettere di indovinare e risolvere in minuti.

WireGuard è silenzioso per scelta — non invia nulla finché non ci sono dati da trasportare, e non registra mai un gentile «connection refused». Questo silenzio rende misterioso un handshake fallito. Quasi sempre è un problema di raggiungibilità di rete (firewall, porta, NAT, routing), non di crittografia. Percorri l'elenco dall'alto in basso e lo prenderai.

Prima, leggi lo stato reale con wg show

Prima di cambiare qualsiasi cosa, guarda cosa WireGuard ti dice già. Su entrambi i lati:

sudo wg show

Stai leggendo tre cose:

• latest handshake — vuoto o più vecchio di ~2 minuti = tunnel giù. Sano = negli ultimi 120 secondi.
• transfer — 0 B received significa che i tuoi pacchetti non sono mai tornati. Inviato-ma-niente-ricevuto è la firma di un firewall o NAT a senso unico.
• endpoint — sul server, deve mostrare l'IP:porta pubblico attuale del client appena arriva un pacchetto. Se non si popola mai, l'iniziazione del client non ti ha raggiunto.

Tieni aperto questo terminale. Dopo ogni soluzione qui sotto, riesegui wg show e osserva la riga latest handshake. È la tua unica fonte di verità — non l'icona di connessione, non l'app.

Causa 1 — La porta UDP è bloccata (il colpevole n.1)

WireGuard parla UDP su una singola porta — 51820 di default. Se quella porta è filtrata da qualche parte sul percorso, il pacchetto di iniziazione muore e ottieni esattamente il tuo sintomo. Per capire questo default, come cambiarlo e aprirlo correttamente, vedi quale porta usa WireGuard e come aprirla. Di solito ci sono due firewall da controllare, e si dimentica il primo:

Firewall del provider cloud (il più spesso dimenticato). Contabo, Hetzner, OVH, AWS — hanno tutti un firewall di rete o security group davanti al tuo VPS. Una regola che consenta UDP 51820 da ovunque deve esistere lì, separata dal firewall di sistema. Sulla maggior parte delle immagini VPS Contabo non c'è un firewall del provider di default (bene), ma se ne hai attivato uno, aggiungi la regola UDP.

Firewall di sistema sul server. Controlla e consenti:

# ufw (Debian/Ubuntu)
sudo ufw allow 51820/udp
sudo ufw reload

# firewalld (Rocky/Alma/Fedora)
sudo firewall-cmd --add-port=51820/udp --permanent
sudo firewall-cmd --reload

Prova rapida che la porta sia raggiungibile dall'esterno — dalla tua macchina client:

# invia una sonda UDP; "open|filtered" senza risposta non è conclusivo,
# ma "open" o un pacchetto restituito conferma la raggiungibilità
nc -u -z -v IP_DEL_TUO_SERVER 51820

Test più pulito: esegui sudo tcpdump -n -i eth0 udp port 51820 sul server, poi connettiti dal client. Se vedi pacchetti in entrata, la porta è aperta e passi alla causa successiva. Se non vedi nulla, il pacchetto viene scartato prima di raggiungere WireGuard — resta su questa causa.

Causa 2 — Endpoint errato sul client

Il blocco [Peer] del client ha bisogno dell'IP pubblico reale del server (o del nome DNS) e del ListenPort esatto:

[Peer]
PublicKey = CHIAVE_PUBBLICA_SERVER
Endpoint = 203.0.113.10:51820
AllowedIPs = 0.0.0.0/0

Errori comuni che producono un handshake morto:

• L'Endpoint punta all'IP LAN privato del server (10.x / 192.168.x) invece di quello pubblico.
• Un refuso nella porta, o il server in realtà ascolta su un altro ListenPort.
• L'IP pubblico del server è cambiato (alcune reinstallazioni di VPS lo riassegnano). Conferma con curl -4 ifconfig.co sul server, poi confronta con l'Endpoint del client.

Il blocco peer sul server non ha la riga Endpoint (il server la impara quando arriva il pacchetto del client) — aggiungerne una lì è un errore di copia-incolla frequente.

Causa 3 — AllowedIPs errati

AllowedIPs è una tabella di routing crittografica, non un elenco di permessi, e un errore rompe in silenzio il traffico di ritorno:

• Sul server, l'AllowedIPs del peer deve elencare solo l'indirizzo tunnel di quel client, es. 10.66.66.2/32. Se due peer condividono un intervallo che si sovrappone, il server invia le risposte a quello sbagliato e l'handshake «si completa» e poi muore.
• Sul client, AllowedIPs = 0.0.0.0/0 instrada tutto nel tunnel (VPN completa). Per lo split tunneling, elenca solo le subnet che instradi davvero — vedi la nostra guida al routing in split-tunnel.

Un handshake che riesce brevemente e poi si blocca è la firma classica di AllowedIPs sovrapposti lato server. Rendi unico l'intervallo di ogni peer.

Causa 4 — Timeout NAT (funziona 2 minuti, poi muore)

Se il tuo client è dietro NAT (router di casa, 4G/5G, Wi-Fi d'hotel) e il collegamento diventa inattivo, il router elimina il mapping UDP. Il server non ha più un percorso di ritorno verso il client e l'handshake scade in silenzio. La soluzione vive sul peer dietro il NAT:

[Peer]
PublicKey = CHIAVE_PUBBLICA_SERVER
Endpoint = 203.0.113.10:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

PersistentKeepalive = 25 invia un pacchetto minuscolo ogni 25 secondi, tenendo aperto il mapping NAT. Venticinque secondi sono sotto ogni timeout NAT comune. Aggiungilo sui client nomadi e su qualsiasi peer dietro un router restrittivo. Il peer lato server di solito non ne ha bisogno.

Causa 5 — L'inoltro IP è spento sul server

Se l'handshake si completa ma non raggiungi Internet attraverso il tunnel, il server non inoltra i pacchetti tra l'interfaccia WireGuard ed eth0. Abilitalo:

echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-wireguard.conf
sudo sysctl --system

Conferma: sysctl net.ipv4.ip_forward deve restituire 1. Abbinalo alla regola di masquerade nel tuo PostUp (i modelli di configurazione pronti all'uso includono queste righe correttamente):

PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

Causa 6 — Sfasamento dell'orologio

L'handshake di WireGuard usa timestamp per bloccare gli attacchi di replay. Se l'orologio del server devia di più di un paio di minuti — comune su immagini VPS fresche o VM messe in pausa — gli handshake vengono rifiutati come scaduti. Correggi l'orologio:

sudo timedatectl set-ntp true
timedatectl status   # System clock synchronized: yes

Questa è subdola perché tutto il resto sembra perfetto. Se hai triplo-controllato porta, chiavi e routing e ancora non ottieni nulla, controlla l'orologio prima di disperare.

Causa 7 — Chiavi non corrispondenti (controlla questo per ultimo)

Si va prima sulle chiavi; controllale per ultime, perché un errore di chiave è più raro delle sei cause sopra e produce lo stesso sintomo. La regola è semplice:

• La [Peer] PublicKey del server = la chiave pubblica derivata dalla PrivateKey del client.
• La [Peer] PublicKey del client = la chiave pubblica derivata dalla PrivateKey del server.

Rigenera e ri-deriva per essere certo:

# su ogni macchina, deriva la chiave pubblica dalla propria chiave privata
echo "CHIAVE_PRIVATA_DI_QUESTO_HOST" | wg pubkey

Confronta quell'output con la PublicKey che l'altro lato ha per te. Una sola chiave scambiata o troncata rompe completamente l'handshake. Già che ci sei, una PresharedKey (se usata) deve essere identica su entrambi i peer — una differenza lì uccide anch'essa l'handshake.

Causa 8 — L'MTU rompe il tunnel subito dopo l'handshake

A rigore, l'MTU blocca raramente l'handshake (i suoi pacchetti sono piccoli). Ma rompe spesso le cose appena scorre traffico reale: l'handshake si completa, il ping funziona, poi le pagine web si bloccano per sempre. È frammentazione. Abbassa l'MTU del client:

[Interface]
MTU = 1380

Trova il valore giusto con un ping «do-not-fragment» verso l'IP tunnel del server, riducendolo finché passa:

ping -M do -s 1372 10.66.66.1

1420 va bene per la maggior parte dei collegamenti in fibra; 1380 è un default sicuro; PPPoE e alcuni operatori mobili richiedono 1280. La nostra guida ai modelli di configurazione spiega la regolazione dell'MTU per tipo di collegamento.

L'ordine di diagnosi in 60 secondi

Quando un handshake fallisce, esegui questa sequenza esatta e fermati alla prima cosa sbagliata:

1. wg show su entrambi i lati — c'è un qualsiasi latest handshake, qualche byte received?
2. tcpdump udp port 51820 sul server mentre il client si connette — arrivano pacchetti?
3. Se non arriva nessun pacchetto → firewall / porta / Endpoint (cause 1-2).
4. Se arrivano pacchetti ma nessuna risposta torna → AllowedIPs lato server, NAT, rotta di ritorno (cause 3-4).
5. Se l'handshake si completa ma niente Internet → ip_forward + masquerade (causa 5).
6. Se tutto sembra giusto e ancora niente → sfasamento orologio, poi chiavi, poi MTU (cause 6-8).

Quest'ordine segue la frequenza reale di ogni causa nelle installazioni self-host reali — percorrilo dall'alto in basso e non perderai tempo.

Costruiscilo bene dall'inizio

La maggior parte degli handshake falliti nasce da una config cucita a mano da tre tutorial contraddittori. Partire da una base nota e buona su un VPS pulito elimina il 90% delle sorprese. Un VPS Contabo S a 4,99 €/mese ti dà un IPv4 pubblico, root completo, e nessun firewall del provider da combattere — esattamente le condizioni in cui WireGuard «funziona e basta». Segui il setup Contabo + WireGuard passo passo e incolla una config verificata dalla guida ai modelli, e l'handshake riesce al primo tentativo.

Per approfondire

• VPN autogestito su Contabo: guida completa a WireGuard 2026
• Modelli di configurazione WireGuard pronti all'uso 2026
• Fughe DNS in WireGuard: rilevare, diagnosticare, eliminare
• Kill-switch WireGuard su Linux: iptables + systemd
• VPN in split-tunnel con tabelle di routing
• Glossario VPN self-hosted — AllowedIPs, MTU, NAT spiegati

Fonti e riferimenti:

• Whitepaper di WireGuard — Jason A. Donenfeld
• Quickstart di WireGuard e docs di wg-quick
• Pagine di manuale wg(8) e wg-quick(8)
• Arch Wiki — risoluzione problemi WireGuard

Pubblicato il 2026-06-23. Ordine di diagnosi validato su server Debian 12 e Ubuntu 24.04 con un VPS Contabo S, contro client WireGuard su Linux, Windows 11, macOS e Android. Le tue condizioni di collegamento possono variare — conferma sempre con wg show e tcpdump prima di considerare definitiva una soluzione.

Promemoria: eseguire WireGuard e auto-ospitare una VPN è legale nell'UE, negli USA, in Canada e nella maggior parte dei paesi democratici. VPNSmith pubblica questo contenuto a scopo educativo.