WireGuard PersistentKeepalive: mantenere il tunnel raggiungibile dietro NAT (2026)

Divulgazione affiliazione - Questo articolo contiene link affiliati Contabo. Se prendi un VPS tramite loro, guadagniamo una commissione senza costi aggiuntivi per te. Ogni valore e comportamento qui sotto è documentato dalle fonti ufficiali WireGuard e scritto per essere riproducibile sulla tua macchina.

Il tuo client WireGuard si connette, funziona per un minuto, poi si zittisce: raggiungi il server dal client, ma il server non riesce più a rimandarti nulla. Un SSH dal lato server si blocca, un dispositivo della LAN dietro il client diventa irraggiungibile, l'handshake scade in silenzio. La correzione è quasi sempre una riga sul client: PersistentKeepalive = 25. Questa guida spiega esattamente cosa fa quell'opzione, perché 25 secondi è il numero magico, e su quale lato del tunnel va messa.

La risposta breve

Se un peer sta dietro NAT e deve restare raggiungibile, aggiungi questo al blocco [Peer] nella configurazione di quel peer:

[Peer]
PublicKey = ...
Endpoint = server.example.com:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

Riavvia il tunnel e il problema del tunnel muto dopo l'inattività sparisce. Tutto ciò che segue è il perché.

Cosa fa PersistentKeepalive

Per progettazione, WireGuard è silenzioso: quando non c'è nulla da inviare, non invia nulla. Niente keepalive, niente heartbeat, nessun chiacchiericcio. Questo lo rende efficiente e difficile da rilevare tramite fingerprint - ma rompe uno scenario preciso.

Quando un client è dietro NAT (un router domestico, un operatore mobile, un firewall aziendale), il dispositivo NAT crea un mapping temporaneo la prima volta che il client invia un pacchetto verso l'esterno. È quel mapping che permette al server di rimandare le risposte verso l'indirizzo interno giusto - pensalo come un foro aperto nel NAT. Fondamentale: quel foro scade dopo un periodo di inattività, spesso tra 30 secondi e un paio di minuti per l'UDP. Una volta chiuso, i pacchetti del server non hanno più dove andare, e il peer diventa irraggiungibile finché il client non parla di nuovo per primo.

PersistentKeepalive risolve questo inviando un piccolo pacchetto keepalive vuoto al peer ogni N secondi. Quel minimo di traffico mantiene aggiornato il mapping NAT, così il foro non si chiude mai e il peer resta raggiungibile anche a riposo.

Cablaggio e apparecchiature di rete in un rack di data center - il lato con IP pubblico di un tunnel WireGuard autogestito

Perché 25 secondi

La raccomandazione ufficiale di WireGuard è 25 secondi, e il ragionamento è semplice. I timeout NAT UDP comuni si raggruppano tra 30 secondi e qualche minuto, e il valore più breve che si incontra regolarmente è intorno ai 30 secondi. Inviare un keepalive ogni 25 secondi aggiorna il mapping con un piccolo margine prima di quella soglia dei 30 secondi - abbastanza frequente da non lasciare mai chiudere il foro, abbastanza raro da non costare quasi nulla.

Puoi scendere più in basso se il tuo NAT è insolitamente aggressivo (15 è un passo successivo ragionevole), o salire per risparmiare batteria sul mobile, ma 25 è il valore predefinito documentato, e non è un caso. Non pensarci troppo.

Dove metterlo: client vs server

È qui che la gente sbaglia. Il keepalive va sul peer che deve restare raggiungibile attraverso un NAT:

Configurazione	Keepalive sul client?	Keepalive sul server?
Client mobile dietro NAT -> server con IP pubblico	Sì (`= 25`)	No
Server con IP pubblico pulito	(non applicabile)	Non necessario
Entrambe le estremità dietro NAT (peer-to-peer)	Sì	Sì

Nel caso normale - un laptop o un telefono dietro un router che parla con un VPS dotato di IP pubblico reale - solo il client ha bisogno di PersistentKeepalive = 25, nel blocco [Peer] che descrive il server. Il server non ne ha bisogno verso i suoi client: il client inizia sempre, e il server risponde semplicemente all'indirizzo di origine da cui è arrivato l'ultimo pacchetto. Un server con IP pubblico pulito è esattamente la configurazione in cui eviti del tutto il problema NAT lato server.

Esempio di configurazione [Peer]

Ecco un blocco peer completo lato client con il keepalive al suo posto:

[Interface]
PrivateKey = <client-private-key>
Address = 10.66.66.2/32
DNS = 10.66.66.1

[Peer]
PublicKey = <server-public-key>
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25

Applicalo con un riavvio del tunnel:

sudo wg-quick down wg0 && sudo wg-quick up wg0

Conferma che ha avuto effetto - wg show elenca l'intervallo sotto il peer:

sudo wg show
# persistent keepalive: every 25 seconds

Se stai assemblando configurazioni da zero, i modelli di configurazione WireGuard pronti all'uso includono già la riga keepalive nel blocco giusto per ogni piattaforma.

L'errore "interval must be in range"

PersistentKeepalive si aspetta un semplice numero intero di secondi, validato rispetto all'intervallo 0-65535. Se vedi interval must be in range o must be in range 0 to 65535, hai passato qualcosa che non è un intero valido in quella finestra:

Un suffisso di unità - scrivi 25, non 25s.
Un decimale - 25, non 25.0.
Un numero negativo, o un valore superiore a 65535.
Uno spazio estraneo o un carattere invisibile incollato da una pagina web.

Un valore di 0 è legale e significa disabilitato - lo stesso che lasciare fuori del tutto la riga. Quindi PersistentKeepalive = 0 non serve a nulla; usa un intervallo reale come 25.

Keepalive impostato ma ancora non funziona

Se hai aggiunto la riga e il tunnel si zittisce ancora dopo l'inattività, scorri queste cause oneste in ordine:

Impostato sul lato sbagliato. È il peer dietro NAT quello che ne ha bisogno. Un keepalive solo sul server con IP pubblico non tiene aperto il foro NAT di un client.
Timeout NAT più breve del tuo intervallo. Alcuni carrier-grade NAT chiudono i mapping UDP più in fretta di 30 secondi. Scendi con l'intervallo a 15 e ritesta.
Un firewall blocca il percorso. Se la porta UDP sottostante è filtrata, nessun keepalive passerà - conferma che la porta WireGuard sia effettivamente aperta su entrambe le estremità.
L'endpoint è cambiato (roaming). Se il client ha cambiato rete e il suo indirizzo pubblico è cambiato, il server potrebbe puntare ancora al vecchio Endpoint. Il keepalive aiuta il server a seguire la nuova origine, ma un Endpoint obsoleto lato client può comunque fallire.

Keepalive vs handshake WireGuard

Sono due timer diversi, e conviene distinguerli. WireGuard rinnova il suo handshake crittografico circa ogni due minuti - ma solo quando c'è traffico reale da proteggere. Su un collegamento inattivo senza keepalive, nessun traffico significa nessun rinnovo dell'handshake, e nel frattempo il foro NAT si richiude in silenzio.

PersistentKeepalive colma esattamente quel vuoto: mantiene un filo di traffico su un collegamento altrimenti inattivo, tenendo aperto il mapping NAT tra gli handshake affinché il tunnel sia pronto nell'istante in cui dei dati reali devono muoversi. Il keepalive non sostituisce l'handshake; mantiene vivo il percorso perché l'handshake possa avvenire quando serve.

Un server con IP pubblico elimina metà del problema

La maggior parte dei grattacapi da keepalive viene dal NAT sul lato server - un box VPN dietro un router domestico, doppio NAT, un firewall del fornitore. Metti il server su un IPv4 pubblico pulito e l'unico NAT rimasto è quello del client, dove un singolo PersistentKeepalive = 25 è tutto ciò che serve. Un Contabo Cloud VPS 10 a 5,50 EUR/mese ti dà root completo e un vero IP pubblico senza firewall del fornitore da combattere - esattamente le condizioni in cui il keepalive lato client è l'unica cosa da impostare. Per capire la meccanica NAT che questa opzione aggira, vedi la spiegazione semplice di cos'è il NAT.

Per approfondire

Fonti e riferimenti:

Pubblicato il 2026-06-29. La raccomandazione dei 25 secondi e il comportamento di PersistentKeepalive provengono dalla documentazione ufficiale WireGuard; gli intervalli di timeout NAT variano a seconda del dispositivo, quindi verifica sul tuo router o operatore se serve un intervallo più breve.

Promemoria: usare WireGuard e autogestire un VPN è legale nell'UE, negli Stati Uniti, in Canada e nella maggior parte dei paesi democratici. VPNSmith pubblica questi contenuti a scopo educativo.

★ Datacenter GDPR di Norimberga · ✓ IPv4 dedicato incluso · 200+ Mbps garantiti

Ospita la tua VPN sul tuo VPS → ContaboAccesso root completo · IPv4 pubblico · scegli la tua regione→

Domande frequenti

Cosa fa PersistentKeepalive in WireGuard?

PersistentKeepalive è un'opzione della sezione [Peer] di una configurazione WireGuard che fa inviare all'interfaccia un piccolo pacchetto keepalive vuoto verso quel peer ogni N secondi, anche quando non c'è traffico reale. Per impostazione predefinita WireGuard è silenzioso: su un collegamento inattivo non invia nulla. Quel silenzio è un problema quando un client sta dietro NAT, perché il mapping NAT - il foro che permette al server di raggiungere il client - scade dopo un breve periodo di inattività. Il keepalive periodico mantiene aperto quel mapping, così il peer resta raggiungibile. Lo abiliti con una riga: PersistentKeepalive = 25.

Perché il valore consigliato di PersistentKeepalive è 25 secondi?

La raccomandazione ufficiale di WireGuard è 25 secondi. I mapping NAT UDP sui router domestici e nel carrier-grade NAT scadono di solito tra 30 secondi e un paio di minuti, e il timeout più breve che si incontra comunemente è intorno ai 30 secondi. Inviare un keepalive ogni 25 secondi mantiene aggiornato il mapping con un piccolo margine di sicurezza prima di quella soglia dei 30 secondi. Valori più bassi funzionano anche, ma sprecano un po' di banda e batteria; 25 è il punto di equilibrio documentato. Se il tuo NAT specifico è più aggressivo, scendere a 15 può aiutare.

PersistentKeepalive va sul client o sul server?

Mettilo sul peer che deve restare raggiungibile attraverso un NAT - quasi sempre il client mobile (il tuo laptop, telefono o box di casa dietro un router). Il client aggiunge PersistentKeepalive = 25 nel blocco [Peer] che descrive il server. Un server con IP pubblico reale non ha bisogno di keepalive verso i suoi client, perché il client inizia sempre e il server risponde semplicemente verso l'indirizzo da cui è arrivato l'ultimo pacchetto. Se entrambe le estremità sono dietro NAT, impostalo su tutte e due.

Perché ricevo 'interval must be in range 0 to 65535'?

PersistentKeepalive prende un numero intero di secondi, e WireGuard lo valida rispetto all'intervallo 0-65535. L'errore 'interval must be in range' o 'must be in range 0 to 65535' significa che hai passato qualcosa fuori da quel range - un numero negativo, un decimale, un suffisso di unità come '25s' o un carattere estraneo. Usa un intero semplice: PersistentKeepalive = 25. Un valore di 0 (o l'assenza della riga) disabilita del tutto la funzione.

PersistentKeepalive scarica la batteria o consuma dati?

In termini di banda è trascurabile: un keepalive è un piccolo pacchetto vuoto di circa 32 byte inviato ogni 25 secondi, pochi kilobyte all'ora. Il costo reale è sul mobile, dove ogni keepalive risveglia la radio dal suo sonno a basso consumo, e risvegli frequenti possono ridurre la durata della batteria. Per questo alcuni alzano l'intervallo sui telefoni per risparmiare energia, accettando che il tunnel possa restare brevemente irraggiungibile a riposo. Su un desktop o server sempre acceso il costo è di fatto zero.