Codice QR WireGuard: generarlo da un .conf (qrencode)

Informativa sull'affiliazione: questo articolo contiene link di affiliazione Contabo e Ultahost. Se prendi un VPS tramite questi link, riceviamo una commissione senza alcun costo aggiuntivo per te.

Digitare una chiave privata in base64 sulla tastiera di un telefono è così scomodo che molti finiscono per copiare le configurazioni tramite app di chat, il che è peggio. Il codice QR esiste per evitare entrambe le cose.

È un solo comando, e la parte che vale la pena leggere è cosa succede dopo la scansione.

Non hai ancora una configurazione, o non hai un terminale a portata di mano? Il nostro generatore di configurazioni WireGuard crea il file del server e una configurazione client per ogni dispositivo, ciascuna con il suo codice QR, interamente nel browser: le chiavi vengono generate in locale con Curve25519 e nulla viene inviato a un server. Non converte un .conf esistente: per quello, incolla il file nel riquadro qui sotto (resta nel tuo browser) oppure usa qrencode. Non hai ancora nemmeno un server? I file che genera funzionano su qualsiasi VPS con un IPv4 pubblico, ad esempio un VPS Cloud 4 di Contabo a 5,50 €/mese (link di affiliazione, durata 24 mesi, IVA inclusa). Se preferisci un hosting statunitense con 30 giorni soddisfatti o rimborsati, il VPS Basic di Ultahost costa 5,52 $ al mese su 24 mesi (1 GB di RAM, IPv4 dedicato, rilevato il 21 ottobre 2026).

Generarne uno

Installa l'encoder:

apt install qrencode      # Debian, Ubuntu
dnf install qrencode      # Fedora, RHEL

Poi, sulla macchina che contiene la configurazione client:

qrencode -t ansiutf8 < /etc/wireguard/client1.conf

Il codice compare nel terminale, disegnato con caratteri a blocchi. Apri WireGuard sul telefono, aggiungi un tunnel, scegli la scansione da codice QR e punta la fotocamera verso lo schermo. Il tunnel viene aggiunto completo di nome, indirizzi, chiavi e peer.

Non c'è nessun formato speciale. Il codice QR contiene il file di configurazione in testo semplice. Qualunque cosa sappia leggere un codice QR può leggere la tua configurazione.

La dimensione raramente è un limite. Una tipica configurazione client WireGuard occupa qualche centinaio di byte, e lo standard QR arriva fino alla versione 40, una griglia di 177 per 177 moduli che contiene 2 953 byte al più basso dei suoi quattro livelli di correzione degli errori. Una configurazione ci sta comodamente, ed è proprio per questo che tutto, chiave privata compresa, viaggia in un'unica immagine.

Per ottenere un file invece di un disegno nel terminale:

qrencode -o client1.png < /etc/wireguard/client1.conf

Se il codice non si lascia scansionare, le cause abituali sono un font del terminale che deforma i blocchi, o una configurazione molto lunga. -t utf8 al posto di ansiutf8 produce un rendering più piccolo, e ridurre la dimensione del font del terminale aiuta più di qualsiasi altra cosa.

La parte che conta

Una configurazione client WireGuard contiene PrivateKey: una chiave Curve25519 da 32 byte, scritta come 44 caratteri base64 su una sola riga. Il codice QR contiene la configurazione. Quindi il codice QR è la chiave privata, in un formato pensato per essere letto a distanza da una fotocamera.

Questo cambia il modo in cui va gestito:

• Non fotografarlo. Una foto finisce nel rullino e, sulla maggior parte dei telefoni, dritta in un backup cloud.
• Non metterlo in un messaggio di chat o in un'email. Entrambi sono copie archiviate che non controlli.
• Pulisci il terminale dopo la scansione. clear da solo non svuota il buffer di scorrimento. Usa reset, o chiudi del tutto la finestra del terminale.
• Elimina subito i file PNG. Un client1.png lasciato nella home directory sopravvive al motivo per cui è stato creato.
• Non mostrarlo dove una fotocamera può vederlo, il che in un ufficio condiviso include la finestra alle tue spalle.

Una chiave privata per client è la regola che il codice QR rende facile violare. Generare una sola configurazione e scansionarla su tre telefoni dà a tutti e tre la stessa identità: il server non riesce più a distinguerli, non può revocarne uno e instraderà male il traffico quando due sono connessi contemporaneamente. Come aggiungere un peer distinto per ogni dispositivo è spiegato in aggiungere un peer WireGuard.

Generare prima la configurazione, se non ne hai una

Il codice QR è l'ultimo passaggio. Prima, il client ha bisogno di una coppia di chiavi e di una voce peer sul server:

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

Poi una configurazione che faccia riferimento alla chiave pubblica del server, all'endpoint e agli AllowedIPs, e un blocco [Peer] corrispondente sul server che contenga client1.pub. Saltare la parte server è il motivo più comune per cui un tunnel scansionato non si connette a nulla: il telefono è configurato, ma il server non ne ha mai sentito parlare.

Se preferisci non costruire i file a mano, il generatore di configurazioni scrive entrambi i lati in una volta sola (l'[Interface] del server con ogni blocco [Peer], più un file client e un codice QR per dispositivo), così il telefono che scansioni e il server con cui comunica sono coerenti fin dall'inizio.

Il server ha bisogno di un indirizzo IP pubblico che il telefono possa raggiungere da una rete mobile. Una connessione domestica dietro CGNAT non ne ha uno (verifica la tua con il verificatore di porta WireGuard); un piccolo VPS sì, per circa 5 € al mese.

Le guide complete, compresa la parte server, sono in configurazione di PiVPN con WireGuard per un Raspberry Pi e in self-hosting su un VPS per un server a noleggio. Entrambe generano configurazioni client che puoi passare direttamente a qrencode.

Se la scansione funziona ma il tunnel no

Il codice QR ha fatto il suo lavoro nel momento in cui il tunnel compare nell'app. Tutto ciò che viene dopo è WireGuard ordinario.

Controlla che il telefono mostri un handshake recente. Un peer in salute ripete l'handshake all'incirca ogni 120 secondi, quindi qualsiasi valore più vecchio di circa due minuti su un tunnel attivo è un sintomo, non una pausa. Se non è così, segui la risoluzione dei problemi di handshake: indirizzo dell'endpoint, porta raggiungibile dall'esterno (51820/UDP per impostazione predefinita), firewall del server e voce peer. Se l'handshake riesce ma le pagine restano bloccate, il problema è l'MTU, ed è particolarmente frequente sulle reti mobili.

Le note di configurazione specifiche per piattaforma sono in configurazione di WireGuard su Android e configurazione di WireGuard su iOS.