WireGuard PersistentKeepalive 25 e PresharedKey su un VPS

In breve: `PersistentKeepalive = 25` dice a WireGuard di inviare al peer un piccolo pacchetto autenticato ogni 25 secondi, il che mantiene vive le mappature del NAT e dei firewall stateful così l'altro lato può ancora raggiungerti. Di norma lo imposti solo sul peer che sta dietro NAT (un portatile, un telefono o un router di casa), non su un VPS con IP pubblico. `PresharedKey` è un segreto simmetrico aggiuntivo e facoltativo da 256 bit per ogni coppia di peer, generato con `wg genpsk`, che viene mescolato nell'handshake come protezione contro futuri attacchi quantistici a Curve25519.

Questa guida spiega entrambe le opzioni e fornisce una configurazione funzionante di server e client per un VPS WireGuard. Per il setup VPN completo con NAT e DNS, vedi la guida alla VPN WireGuard.

Cosa fa davvero PersistentKeepalive = 25

WireGuard è silenzioso per progettazione: quando non passano dati, non invia nulla. È un bene per privacy e batteria, ma i router che fanno NAT e connection tracking eliminano le mappature UDP inattive, spesso dopo 30 secondi e a volte dopo qualche minuto. Una volta sparita la mappatura, i pacchetti del server non riescono più a raggiungere un client dietro NAT finché il client non invia di nuovo qualcosa.

`PersistentKeepalive` è un intervallo in secondi. Con `25`, il peer invia un keepalive vuoto e cifrato ogni volta che non ha inviato nulla per 25 secondi. Il valore 25 è quello raccomandato dalla documentazione di WireGuard, perché resta con sicurezza sotto i timeout UDP comuni più brevi. L'impostazione è disattivata per impostazione predefinita (`0`), e il costo è un piccolo pacchetto circa ogni 25 secondi per peer.

Quale lato ha bisogno di PersistentKeepalive

Imposta il keepalive sul peer che non può essere raggiunto direttamente, cioè quello dietro NAT. È quel peer a inviare i pacchetti verso l'esterno, aggiornando la propria mappatura NAT. Un VPS con un indirizzo IPv4 pubblico non ha NAT davanti, quindi non ha bisogno dell'opzione per restare raggiungibile, e non può tenere aperto da solo un NAT remoto perché conosce l'endpoint del client solo dai pacchetti del client.

Se il client si limita a navigare attraverso il tunnel, si riconnette all'istante ogni volta che invia traffico, quindi il keepalive è facoltativo. Ti serve quando il server o altri peer devono avviare connessioni verso il client, per esempio SSH verso una macchina di casa, monitoraggio o un collegamento site-to-site.

• ▹Portatile o telefono dietro NAT verso un VPS: imposta `PersistentKeepalive = 25` solo sul client.
• ▹Da VPS a VPS, entrambi con IP pubblici: di solito lascialo non impostato; vedi la [guida alla mesh WireGuard](/guides/wireguard-mesh-vps-cluster).
• ▹Server di casa dietro CGNAT esposto tramite un VPS: impostalo sul server di casa, altrimenti il VPS perde il percorso nel giro di pochi minuti.
• ▹Client mobili: un keepalive consuma un po' di batteria; attivalo solo se il dispositivo deve essere raggiungibile.

PresharedKey: il livello simmetrico facoltativo

L'handshake di WireGuard usa lo scambio di chiavi Curve25519. Un computer quantistico abbastanza grande potrebbe, in teoria, violare quello scambio, e un avversario potrebbe registrare il traffico oggi e decifrarlo in futuro. `PresharedKey` mescola nell'handshake una chiave simmetrica aggiuntiva da 256 bit. Le chiavi simmetriche di questa dimensione non sono considerate praticamente violabili dagli algoritmi quantistici noti, quindi se la PSK resta segreta, il traffico registrato resta protetto anche se la parte a chiave pubblica viene violata.

La PSK è per coppia di peer, deve essere identica nelle sezioni `[Peer]` di entrambi e dovrebbe essere unica per ogni coppia. Non sostituisce le chiavi private: è un livello in più. Se le PSK non corrispondono, l'handshake fallisce in silenzio e in `wg show` non compare alcun `latest handshake`.

• ▹Generala con `wg genpsk`, che produce una chiave casuale di 32 byte codificata in base64.
• ▹Trasferiscila su un canale di cui ti fidi già, come SSH, mai via chat o email.
• ▹Usa una PSK per coppia: in una mesh di cinque nodi sono dieci PSK diverse.
• ▹Ruotala come qualsiasi altro segreto quando un dispositivo viene perso o dismesso.

Genera le chiavi e una PresharedKey

Installa gli strumenti su Debian 12/13 o Ubuntu 24.04 con `apt install wireguard`, poi genera le chiavi sulla macchina dove risiederà ciascuna chiave privata. La PSK può essere generata su uno dei due lati e copiata sull'altro. `umask 077` garantisce che i file siano leggibili solo da root.

umask 077
cd /etc/wireguard

# on the VPS
wg genkey | tee server.key | wg pubkey > server.pub

# on the client
wg genkey | tee client.key | wg pubkey > client.pub

# once, on either side; copy to the other over SSH
wg genpsk > client.psk

Configurazione del server sul VPS: /etc/wireguard/wg0.conf

Il server ha una porta di ascolto fissa, nessun keepalive e nessun `Endpoint` per il client, perché ricava l'indirizzo attuale del client dai pacchetti autenticati.

[Interface]
Address = 10.8.0.1/24, fd08::1/64
ListenPort = 51820
PrivateKey = <contents of server.key>

[Peer]
# laptop
PublicKey = <contents of client.pub>
PresharedKey = <contents of client.psk>
AllowedIPs = 10.8.0.2/32, fd08::2/128

Note · Apri UDP 51820 nel firewall del VPS e avvia il tunnel con `systemctl enable --now wg-quick@wg0`. Prima di esporre qualsiasi altra cosa, proteggi SSH come descritto nella guida all'hardening SSH e controlla i permessi delle chiavi con la guida a StrictModes.

Configurazione del client dietro NAT

Il client punta all'indirizzo pubblico del VPS e porta il keepalive. Usa `AllowedIPs = 10.8.0.0/24, fd08::/64` per un tunnel solo privato, oppure `0.0.0.0/0, ::/0` per far passare tutto il traffico dal VPS.

[Interface]
Address = 10.8.0.2/32, fd08::2/128
PrivateKey = <contents of client.key>

[Peer]
PublicKey = <contents of server.pub>
PresharedKey = <contents of client.psk>
Endpoint = 203.0.113.10:51820
AllowedIPs = 10.8.0.0/24, fd08::/64
PersistentKeepalive = 25

Note · Un VPS Wisp di NoctisNode (1 vCPU, 1 GB di RAM, $6 per ciclo di 28 giorni) con IPv4 dedicato basta per un endpoint WireGuard personale, e si può pagare in Monero o altre cripto con solo email e password alla registrazione.

Verifica e risoluzione dei problemi

Esegui `wg show` su entrambi i lati. Un client sano mostra un `latest handshake` recente, `persistent keepalive: every 25 seconds` e `preshared key: (hidden)` per il peer.

1. 01.Nessun handshake: controlla che UDP 51820 sia aperto sul VPS e che `Endpoint` usi IP e porta corretti.
2. 02.L'handshake funziona senza PSK ma non con: la PresharedKey è diversa tra le due configurazioni; copiala di nuovo.
3. 03.Il tunnel funziona, poi dopo un minuto il server non raggiunge più il client: aggiungi `PersistentKeepalive = 25` sul client.
4. 04.Cambia il keepalive senza riavviare: `wg set wg0 peer <server-public-key> persistent-keepalive 25`.
5. 05.Aggiungi una PSK da file a runtime: `wg set wg0 peer <public-key> preshared-key /etc/wireguard/client.psk`.

FAQ