Come usare un file di configurazione WireGuard

Cosa c'è dentro un file .conf, riga per riga

Ogni configurazione WireGuard ha la stessa struttura in due parti. [Interface] descrive il tuo capo del tunnel; [Peer] descrive la macchina a cui ti connetti. Ecco una configurazione client completa, con i segreti sostituiti da segnaposto:

[Interface]
PrivateKey = YOUR_PRIVATE_KEY_KEEP_THIS_SECRET
Address    = 10.7.0.4/32
DNS        = 10.7.0.1

[Peer]
PublicKey           = THE_SERVER_PUBLIC_KEY_FROM_YOUR_PROVIDER
Endpoint            = 198.51.100.10:51820
AllowedIPs          = 0.0.0.0/0, ::/0
PersistentKeepalive = 25

Il blocco [Interface]: il tuo lato

• PrivateKey: questa è la tua identità sulla VPN. Chiunque la possieda può spacciarsi per te. Sono 44 caratteri base64 che terminano con =; se la tua ha una lunghezza diversa, il file è stato troncato da qualche parte durante la copia.
• Address: l'IP che il tuo dispositivo ha dentro il tunnel, non il tuo IP pubblico. Il /32 significa "solo questo indirizzo", ed è normale per un client.
• DNS: il resolver usato mentre il tunnel è attivo. Senza, il dispositivo continua a interrogare il resolver precedente, il che rivela cosa stai cercando e spesso impedisce di risolvere qualsiasi cosa dall'altra parte.
• MTU: facoltativa, ed è la riga più utile da conoscere. Manca nella maggior parte dei file perché il valore predefinito è quello giusto; vedi la sezione risoluzione dei problemi per il caso in cui non lo è.

Il blocco [Peer]: il lato del server

• PublicKey: la chiave pubblica del server. La tua non compare mai nel tuo file; la conserva il server.
• Endpoint: dove inviare i pacchetti, nel formato host:port. WireGuard funziona solo in UDP, e 51820 è la porta convenzionale, non una porta obbligatoria.
• AllowedIPs: quali destinazioni passano nel tunnel. 0.0.0.0/0, ::/0 significa tutto, ed è proprio lo scopo di una VPN per la privacy. Un elenco più ristretto (ad esempio solo la rete interna della tua azienda) fa passare nel tunnel solo quello e lascia il resto sulla connessione normale. Questa configurazione si chiama split tunnel, ed è una scelta deliberata, non un tunnel completo che non funziona.
• PersistentKeepalive: invia un piccolo pacchetto ogni 25 secondi perché il dispositivo NAT tra te e il server mantenga aperto il percorso di ritorno. Serve ogni volta che sei dietro un NAT, e su uno smartphone o una connessione di casa lo sei sempre.

Windows: importa il tunnel

Windows ha un'app WireGuard ufficiale, e importarci un file è tutto il lavoro.

1. Installa WireGuard da wireguard.com/install.
2. Fai clic su Aggiungi tunnel in basso a sinistra: si apre una finestra di selezione filtrata su File di configurazione (*.zip, *.conf). Scegli il tuo .conf e comparirà nell'elenco dei tunnel, con il nome del file.
3. Oppure incollalo. La freccia accanto ad Aggiungi tunnel offre Aggiungi tunnel vuoto..., che ti dà una casella di testo: utile quando la configurazione ti è arrivata in un messaggio invece che come file. È precompilata con una nuova chiave privata, quindi cancella quella riga e incollaci sopra la tua configurazione.
4. Fai clic su Attiva. Lo stato passa ad Attivo e il pannello inizia a contare i byte trasferiti. Quel contatore è il controllo più rapido che hai: se mostra dati in uscita e niente in entrata, l'handshake non si sta completando.

Android e iPhone: scansiona il codice QR o importa il file

Su uno smartphone hai due strade, e il codice QR esiste proprio perché digitare una chiave di 44 caratteri su un touchscreen è un tormento.

Android

1. Installa WireGuard dal Play Store e tocca il pulsante +.
2. La schermata Crea un tunnel WireGuard offre Scansiona da codice QR, Importa da file o archivio e la creazione da zero. Scegli l'opzione che corrisponde a ciò che ti è stato dato.
3. Dai un nome al tunnel se richiesto, poi attiva il suo interruttore. Android chiede una sola volta il permesso di aggiungere una configurazione VPN: quella richiesta è del sistema operativo, non dell'app.

iPhone e iPad

1. Installa WireGuard dall'App Store e tocca Aggiungi un tunnel.
2. In Aggiungi un nuovo tunnel WireGuard, scegli Crea da codice QR oppure Crea da file o archivio. La schermata dello scanner si chiama Scansione codice QR; dopo una scansione riuscita ti chiede di dare un nome al tunnel.
3. Attivalo e consenti la configurazione VPN quando iOS lo chiede.

Creare un codice QR da un file di configurazione che hai già

Il codice QR non è qualcosa che il provider deve per forza darti: è solo il tuo file di configurazione disegnato come immagine, e puoi generarlo da solo con un comando. È la stessa app WireGuard a suggerirlo:

# prints the code straight into the terminal, ready to scan off the screen
qrencode -t ansiutf8 < wg0.conf

# or write it to an image file
qrencode -o wg0.png < wg0.conf

Su Debian o Ubuntu, qrencode si installa con apt install qrencode; su macOS, con brew install qrencode.

macOS e Linux

macOS

Installa WireGuard dal Mac App Store. L'app per Mac non è l'app per iPhone su uno schermo più grande: vive nella barra dei menu, e la sua finestra si apre da Gestisci i tunnel. Fai clic su Importa tunnel da file (nella barra dei menu la stessa voce si chiama Importa tunnel da file…), scegli il tuo .conf, poi seleziona il tunnel e fai clic su Attivato. Sul Mac non c'è uno scanner QR (i codici QR sono pensati per gli smartphone), quindi usa direttamente il file, oppure scegli Aggiungi tunnel vuoto… e incollaci la configurazione.

Se preferisci lavorare nel terminale, brew install wireguard-tools ti dà gli stessi comandi wg-quick di Linux, descritti qui sotto.

Linux

1. Installa gli strumenti. Su Debian o Ubuntu: sudo apt install wireguard. La maggior parte delle distribuzioni ha un pacchetto con lo stesso nome.
2. Metti il file dove wg-quick lo cerca. È il passaggio in cui si sbaglia più spesso, perché il nome del file diventa il nome dell'interfaccia:

   sudo install -m 600 -o root -g root wg0.conf /etc/wireguard/wg0.conf

   Il 600 è importante: il file contiene la tua chiave privata e non deve essere leggibile dagli altri utenti della macchina. Usa un nome breve e semplice; deve essere un nome di interfaccia di rete valido.
3. Attivalo:

   sudo wg-quick up wg0
   sudo wg show

   wg show è l'unico comando che vale la pena ricordare. Mostra il peer, l'endpoint, una riga latest handshake e i contatori di traffico. Un timestamp di handshake che non compare mai è il segno distintivo del problema descritto nella prossima sezione.
4. Avvio automatico: sudo systemctl enable --now wg-quick@wg0. Per fermare il tunnel a mano, sudo wg-quick down wg0.

Sul router, per coprire tutta la casa

Mettere il tunnel sul router copre tutti i dispositivi collegati, compresi quelli che non possono proprio eseguire un'app VPN: una console, una TV, uno smart speaker. Se puoi farlo dipende interamente dal firmware.

Se il tuo router è quello che ti ha dato l'operatore, le opzioni realistiche sono mettere dietro un router che controlli tu, oppure continuare con le configurazioni per singolo dispositivo. Nessuna delle due è una sconfitta; anzi, la configurazione per dispositivo spesso è migliore, perché puoi lasciare il tunnel spento sui dispositivi che non ne hanno bisogno.

Una cosa da decidere prima di far passare tutta la casa in un tunnel: da quel momento ci passa tutto. I siti delle banche che non amano gli indirizzi esteri, lo streaming che controlla la tua regione e qualsiasi cosa comunichi con i dispositivi della tua rete possono comportarsi diversamente. È qui che un AllowedIPs più ristretto si rivela prezioso: fai passare solo ciò che serve e lascia stare il resto.

Si connette ma non carica nulla, e altri problemi reali

WireGuard è insolitamente silenzioso quando qualcosa va storto, ed è una scelta di progettazione voluta: un pacchetto non autenticato non riceve alcuna risposta, così uno scanner non può capire se c'è qualcosa in ascolto. L'effetto collaterale è che una chiave sbagliata, una porta sbagliata e una rete bloccata sembrano identiche dal tuo lato: silenzio. Parti dal sintomo.

"Handshake did not complete"

Il tuo dispositivo ha inviato un pacchetto di avvio e non ha ricevuto nulla in risposta. Controlla, in quest'ordine:

• L'endpoint. Host giusto, porta giusta, e la porta dev'essere UDP. Un errore di battitura qui produce esattamente questo sintomo e nessun altro.
• Che l'UDP arrivi davvero all'esterno. Wi-Fi per ospiti, reti degli hotel, alcune reti aziendali e qualche operatore mobile consentono solo TCP sulle porte comuni. Se la stessa configurazione funziona sulla connessione di casa e non su una rete specifica, la configurazione è a posto e il problema è la rete.
• Che le chiavi siano al posto giusto. La PublicKey in [Peer] è la chiave pubblica del server, e il server deve avere, separatamente, la chiave pubblica che corrisponde alla tua PrivateKey. Una configurazione copiata da un altro dispositivo fallisce qui.
• L'orologio. L'handshake di WireGuard include un timestamp e rifiuta quelli troppo sfasati. Succede di rado, ma capita sui dispositivi che hanno perso l'ora.

Se il tunnel funziona da casa ma mai da una connessione mobile, la causa potrebbe essere dal lato del tuo operatore e non dal tuo: il CGNAT e soluzioni simili cambiano ciò che può raggiungerti. La guida al port forwarding spiega come verificarlo dal tuo router in un paio di minuti.

Il problema dell'MTU, che vale la pena capire una volta per tutte

È il classico caso "connesso ma internet non va", e lo schema è inconfondibile: il ping funziona, il DNS funziona, le pagine leggere si caricano e tutto ciò che è un po' più pesante resta bloccato all'infinito.

La causa è la dimensione. Incapsulare il traffico per il tunnel aggiunge intestazioni, quindi un pacchetto che entrava perfettamente nella connessione normale non ci sta più una volta dentro WireGuard. I pacchetti piccoli passano senza problemi; quelli grandi vengono scartati. Di norma la rete avvisa il mittente di usare pacchetti più piccoli, ma il messaggio che lo fa viene spesso filtrato, così invece di un errore resti semplicemente ad aspettare.

La soluzione è dire a WireGuard di usare pacchetti più piccoli fin dall'inizio. wg-quick ci prova già: prende l'MTU del tuo percorso normale e sottrae 80 byte per l'overhead del tunnel, quindi su una normale connessione da 1500 byte ottieni 1420. Quando è ancora troppo (alcune reti mobili, la maggior parte delle connessioni che passano già dentro un altro tunnel), impostalo esplicitamente e scendi a gradini:

[Interface]
MTU = 1420      # what wg-quick would have picked
# still stalling? try 1380, then 1280

1280 è il minimo che vale la pena provare, perché è la dimensione di pacchetto più piccola che IPv6 impone a tutti di trasportare, quindi supera praticamente qualsiasi percorso. Costa un po' di efficienza ed è molto meglio di un tunnel che si blocca.

Il tunnel è attivo ma non ci passa niente

Controlla prima AllowedIPs. Non è un firewall né un elenco di permessi: decide quali destinazioni vengono instradate nel tunnel. Se non include 0.0.0.0/0, il traffico verso il resto di internet non doveva mai passarci, e la connessione si comporta esattamente come è stata configurata. Su Linux, ip route show table all | grep wg0 mostra cosa è stato davvero instradato.

Se l'instradamento è corretto e sono i nomi a non risolversi, è la riga DNS: manca, oppure c'è ma non viene applicata perché resolvconf non è installato.

Da dove arriva il file di configurazione

Tutto ciò che hai letto finora presuppone che tu abbia un file. Ci sono esattamente due modi per ottenerlo.

Gestire il server da solo

Generi una coppia di chiavi, installi WireGuard su una macchina con un indirizzo pubblico, aggiungi il tuo dispositivo come peer e scrivi a mano la configurazione client. Non è difficile ed è davvero una bella cosa da imparare. Il costo è continuo: un server da pagare e tenere aggiornato, e una modifica manuale su entrambi i lati ogni volta che aggiungi un dispositivo, perché, ricorda, un peer è un dispositivo.

Ottenerlo da un provider

L'alternativa è che il file venga generato per te e tu lo scarichi e basta. Con HytHost VPN, da €0.99/mese, lo trovi qui:

1. Ordina il servizio e accedi all'area clienti, poi apri il tuo servizio VPN dall'elenco.
2. Trova la sezione WireGuard Configuration. Ti offre due pulsanti: Copy to Clipboard, che copia il testo della configurazione negli appunti, e Download Configuration, che ti consegna il file già pronto.
3. Se l'hai copiato, incollalo in un editor di testo semplice e salvalo con l'estensione .conf; wg0.conf è un buon nome. Assicurati che l'editor non abbia aggiunto .txt alla fine.
4. Importalo seguendo la sezione qui sopra relativa al tuo dispositivo. Su uno smartphone, trasformalo prima in un codice QR con qrencode.

La stessa pagina mostra se il tunnel è attualmente connesso al server, il che risolve il dubbio "è colpa mia o loro?" prima che inizi a cambiare impostazioni. Non c'è un pulsante per il codice QR: generalo tu dal file, il che significa anche che il codice non viaggia mai dove non serve.