Aggiungere un peer WireGuard a caldo, senza riavviare il tunnel

La maggior parte delle guide risponde a "come aggiungo un peer WireGuard?" con wg-quick down wg0 && wg-quick up wg0. Funziona, ma disconnette anche chiunque stia usando il tunnel in quel momento, solo per aggiungere una riga a un file. Su un server con pochi client è un fastidio passeggero. Su un server su cui fai davvero affidamento, è il motivo per cui si evita del tutto di aggiungere peer.

Esiste un comando che lo fa a caldo.

Come si aggiunge un peer a WireGuard?

Una riga, sull'interfaccia attiva:

wg set wg0 peer <CLIENT_PUBLIC_KEY> allowed-ips 10.0.0.5/32

Il peer esiste da quel momento. Nessun riavvio, nessun handshake perso, nessuna interruzione per chi è già connesso. wg set parla direttamente con il modulo del kernel e modifica la configurazione attiva dell'interfaccia.

Verifica che sia andato a buon fine:

wg show wg0

La nuova chiave pubblica compare nell'elenco, ancora senza handshake, ed è normale: l'handshake avviene quando il client invia traffico per la prima volta.

Come si aggiunge un peer da riga di comando, dall'inizio alla fine?

Sulla macchina client, genera la coppia di chiavi:

wg genkey | tee client.key | wg pubkey > client.pub

client.key è la chiave privata e non lascia mai quella macchina. client.pub è ciò di cui ha bisogno il server.

Sul server:

wg set wg0 peer "$(cat client.pub)" allowed-ips 10.0.0.5/32

Di nuovo sul client, il file di configurazione deve contenere la chiave pubblica del server, il suo endpoint e l'indirizzo che hai appena assegnato:

[Interface]
PrivateKey = <contents of client.key>
Address = 10.0.0.5/32

[Peer]
PublicKey = <SERVER_PUBLIC_KEY>
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

Le due chiavi sono il passaggio in cui si sbaglia più spesso: ogni lato contiene la chiave pubblica dell'altro lato, mai la propria.

Se il nuovo client è un telefono, o una macchina senza wg installato, puoi produrre la sua parte senza terminale. Imposta il nostro generatore di configurazioni WireGuard gratuito su un client, con l'endpoint e la sottorete del tuo server: crea la coppia di chiavi nel browser e ti fornisce il file del client, il suo QR code e il blocco [Peer] corrispondente per il server. Due cose da controllare prima dell'uso. Il generatore inventa una propria coppia di chiavi per il server, quindi sostituisci PublicKey nel blocco [Peer] del client con la tua chiave reale, ottenuta da wg show wg0 public-key. E assegna al primo client l'indirizzo .2 della sottorete, quindi modifica Address (e l'allowed-ips che passi a wg set) se quell'indirizzo è già occupato. La chiave privata del client e la chiave pubblica da consegnare al server sono pronte così come sono. Il generatore è gratuito fino a 10 dispositivi; oltre, WireGuard Pro (un nostro prodotto, 9 EUR una tantum, nessun abbonamento) porta il limite a 250 e aggiunge un unico ZIP con il .conf di ogni client e il suo QR code in PNG, comodo per configurare un intero ufficio o una famiglia in un colpo solo.

Cosa va in AllowedIPs quando aggiungi un peer?

Dipende da quale lato ti trovi, e questa asimmetria è la fonte della maggior parte della confusione.

La regola della non sovrapposizione è strutturale, non una questione di ordine. AllowedIPs è ciò che dice a WireGuard a quale peer appartiene una data destinazione, quindi un indirizzo elencato su due peer rende ambigua quella decisione, e il sintomo pratico è che aggiungere un client mette silenziosamente offline il precedente.

Sul lato client, il tunnel completo 0.0.0.0/0 è semplice; "tutto tranne la mia LAN" no, perché AllowedIPs non ha una sintassi di esclusione. Il nostro calcolatore AllowedIPs gratuito trasforma "tutto tranne X" nell'elenco più breve di intervalli IPv4 e IPv6 da incollare nel blocco [Peer] del nuovo client.

Come fai a far sopravvivere il nuovo peer a un riavvio?

wg set modifica l'interfaccia attiva. Non tocca /etc/wireguard/wg0.conf, quindi un riavvio lo dimentica. Due modi per renderlo persistente:

Aggiungi il blocco al file a mano:

[Peer]
PublicKey = <CLIENT_PUBLIC_KEY>
AllowedIPs = 10.0.0.5/32

Non riscrivere lo stato attivo nel file con wg showconf wg0 > /etc/wireguard/wg0.conf, una scorciatoia molto diffusa. wg showconf conosce solo ciò che conosce il kernel: la chiave privata, la porta di ascolto e i peer. Non contiene nessuna delle righe di wg-quick: Address, DNS, MTU, PostUp, PostDown. Se sovrascrivi il file con il suo output, il successivo wg-quick up avvia wg0 senza indirizzo del tunnel e senza regole NAT, quindi ogni client completa l'handshake e niente viene instradato.

Se vuoi che lo stato attivo venga salvato al posto tuo, imposta SaveConfig = true in [Interface]. wg-quick riscrive allora i peer nel file quando l'interfaccia viene spenta e conserva le proprie righe. Il rovescio della medaglia: in quel momento riscrive l'intero file, quindi un commento o una modifica manuale fatta mentre il tunnel è attivo va persa. Scegli un metodo, file modificato a mano oppure SaveConfig, non entrambi.

Per ricaricare un file modificato senza interrompere le sessioni:

wg syncconf wg0 <(wg-quick strip wg0)

syncconf applica le differenze. wg-quick down/up no: ricostruisce l'interfaccia da zero, che è esattamente ciò che stavi cercando di evitare.

Come si automatizza l'aggiunta di peer su Linux?

La sequenza non ha passaggi interattivi, quindi si trasforma direttamente in uno script:

#!/usr/bin/env bash
set -euo pipefail
NAME="$1"; IP="$2"          # ./addpeer.sh laptop 10.0.0.7
umask 077
wg genkey | tee "$NAME.key" | wg pubkey > "$NAME.pub"
wg set wg0 peer "$(cat "$NAME.pub")" allowed-ips "$IP/32"
printf '\n[Peer]\n# %s\nPublicKey = %s\nAllowedIPs = %s/32\n' \
  "$NAME" "$(cat "$NAME.pub")" "$IP" >> /etc/wireguard/wg0.conf
echo "added $NAME at $IP"

umask 077 è importante: senza, la chiave privata appena scritta è leggibile da tutti gli account della macchina. Anche set -euo pipefail è importante: senza, un wg set fallito ti lascia comunque i file delle chiavi e un allegro messaggio di successo. La riga printf aggiunge il peer in coda al file invece di riscriverlo, per il motivo spiegato nella sezione precedente.

Una versione più completa di questo script è disponibile gratis su GitHub: wg-newpeer.sh genera anche una chiave precondivisa, scrive il .conf del client in ./clients/, applica la modifica con wg syncconf e mostra un QR code quando qrencode è installato. È incluso nel nostro WireGuard Self-Hosting Kit a pagamento (9 USD), insieme ai modelli per server e client, alla checklist di risoluzione dei problemi con 12 cause e alla checklist di hardening, se vuoi l'intero set sotto forma di file.

Una mano appoggiata sulla tastiera mentre il monitor resta nero: aggiungere un peer con wg set non produce alcuna conferma visibile, ed è per questo che wg show è l'unica cosa che ti dice se ha funzionato.

Perché il nuovo peer non si connette?

Il comando è andato a buon fine e non succede niente. In pratica si tratta quasi sempre di una di quattro cose, e tutte e quattro si possono verificare invece di tirare a indovinare.

1. Le chiavi sono scambiate. Il server contiene la chiave pubblica del client; il client quella del server. Mettere una chiave privata dove va una pubblica fallisce in silenzio.
2. Il client è dietro NAT senza PersistentKeepalive. Il server non ha un percorso di ritorno finché il client non parla per primo, e nel frattempo il mapping NAT scade. PersistentKeepalive = 25 sul lato client lo tiene aperto.
3. L'indirizzo è già occupato. Due peer con lo stesso AllowedIPs è il caso che sembra più misterioso, perché è il peer più vecchio a smettere di funzionare.
4. La porta UDP del server non è raggiungibile dall'esterno. I peer esistenti nella LAN continuano a funzionare, quindi il server sembra a posto, ma un nuovo peer su rete mobile non ottiene mai un handshake. Il nostro WireGuard port checker gratuito ti dice se il tuo router può davvero inoltrare la porta (rileva CGNAT e doppio NAT) e ti fornisce la regola firewall per il tuo sistema. Se la risposta è CGNAT, nessun port forwarding risolverà il problema: la soluzione abituale è far girare il server su un VPS con un proprio IPv4 pubblico, come un Contabo Cloud VPS (link di affiliazione), e aggiungere lì i tuoi peer. Se preferisci un provider statunitense con garanzia soddisfatti o rimborsati di 30 giorni, Ultahost VPS Basic costa 5,52 $ al mese con un impegno di 24 mesi (1 GB di RAM, IPv4 dedicato, verificato il 21 ottobre 2026), sufficiente per un server WireGuard con pochi dispositivi.

Il terzo guasto è il motivo per cui esiste wg-clients-audit. Legge una cartella di configurazioni client e segnala indirizzi duplicati, chiavi private riutilizzate e intervalli AllowedIPs abbastanza ampi da inghiottire la rete locale, i tre difetti che producono un tunnel che si connette e poi si comporta in modo strano. Eseguirlo prima di consegnare una configurazione a qualcuno è più rapido che diagnosticare il problema dopo.

Parti da wg show wg0. Un peer senza latest handshake non ne ha mai completato uno, il che indica le chiavi o la raggiungibilità. Un peer che completa l'handshake ma non trasporta dati indica AllowedIPs.

Mentre modifichi un blocco peer, è il momento giusto per valutare una chiave precondivisa: un wg genpsk per ogni coppia di peer, mescolato nell'handshake, e deve coincidere su entrambi i lati, altrimenti il tunnel tace.

Una VPN cambia il tuo IP. Non cambia il tuo browser.

Un tunnel sostituisce l'indirizzo che un servizio vede. Non cambia nulla di ciò che il tuo browser dichiara da solo (font, schermo, fuso orario, stack grafico), e questa combinazione è spesso abbastanza stabile da riconoscerti da una sessione all'altra, con o senza tunnel.

Misura l'impronta del tuo browser: passiva, nessuna domanda, nessun account, nessuna email.

Cosa ricordare

wg set aggiunge un peer a caldo; wg-quick down/up disconnette tutti per fare lo stesso lavoro. Tutto ciò che aggiungi a caldo sparisce al riavvio, a meno che tu non lo scriva anche nella configurazione, e wg showconf non è un file di configurazione: reindirizzalo sopra wg0.conf e perdi Address e PostUp. Un /32 per client, mai sovrapposto. E quando un nuovo peer si comporta male, controlla wg show prima di cambiare qualsiasi cosa: la differenza tra "nessun handshake" e "handshake ma nessun traffico" ti dice quale metà della configurazione guardare.

E se stavi per copiare una configurazione su un secondo dispositivo invece di aggiungere un peer, il sintomo che ne segue è documentato: due dispositivi, una sola chiave WireGuard (in inglese).