Come configurare un server VPN WireGuard con wg-easy
wg-easy è un'applicazione Docker che esegue un server VPN WireGuard insieme a un pannello web. Nel pannello si creano i client, si scaricano i loro file di configurazione o si scansiona un codice QR con lo smartphone e si vede quali client sono connessi. Questa guida mostra come installare la versione attuale, wg-easy v15, su un server Linux con Docker Compose e come collegare il primo dispositivo.
wg-easy v15 differisce dalle versioni precedenti. La password dell'amministratore non viene più passata nella variabile PASSWORD: un container avviato con PASSWORD o PASSWORD_HASH non parte. Nome utente e password vengono ora impostati nel browser al primo avvio.
Requisiti
Basta un VPS con un indirizzo IP pubblico e accesso root o sudo. wg-easy è leggero: 1 vCPU e 1 GB di RAM sono sufficienti per una VPN personale. I comandi di questa guida sono stati verificati su Ubuntu 24.04 LTS. Poiché wg-easy gira in Docker, funzionano allo stesso modo su Ubuntu 22.04, Debian 12, AlmaLinux 9 e Rocky Linux 9.
Se non si vuole installare nulla manualmente, ordinare dall'App Marketplace di INTROSERV un VPS con wg-easy già distribuito e passare direttamente al primo avvio.
Installare Docker
Collegarsi al server via SSH e installare Docker Engine con il plugin Compose tramite lo script ufficiale:
curl -fsSL https://get.docker.com | sudo sh
Verificare che Docker e Compose siano installati:
sudo docker --version sudo docker compose version
Scaricare il file docker-compose.yml
wg-easy si installa con il docker-compose.yml ufficiale del repository del progetto. Creare una cartella per il file e scaricarlo:
sudo mkdir -p /etc/docker/containers/wg-easy sudo curl -o /etc/docker/containers/wg-easy/docker-compose.yml https://raw.githubusercontent.com/wg-easy/wg-easy/master/docker-compose.yml
Le righe principali del file sono l'immagine e le porte:
image: ghcr.io/wg-easy/wg-easy:15 ports: - "51820:51820/udp" - "51821:51821/tcp"
La porta 51820/udp è usata da WireGuard stesso e la porta 51821/tcp dal pannello web. Il tag 15 significa che gli aggiornamenti restano all'interno della versione 15. La configurazione e i client sono archiviati in un volume Docker, quindi vengono conservati quando il container viene ricreato.
Avviare wg-easy
Passare alla cartella contenente il file e avviare il container:
cd /etc/docker/containers/wg-easy sudo docker compose up -d
Verificare che il container sia in esecuzione:
sudo docker compose ps
La colonna STATUS dovrebbe mostrare Up e la colonna PORTS le porte 51820/udp e 51821/tcp.
Aprire la porta nel firewall
I client si collegano al server tramite la porta UDP 51820. Se UFW è abilitato sul server, consentire questa porta:
sudo ufw allow 51820/udp
Su AlmaLinux e Rocky Linux con firewalld, usare:
sudo firewall-cmd --permanent --add-port=51820/udp sudo firewall-cmd --reload
Aprire il pannello web
wg-easy v15 non consente l'accesso al pannello tramite HTTP semplice. Il modo sicuro più semplice è aprire il pannello attraverso un tunnel SSH. Sul proprio computer, eseguire:
ssh -L 51821:localhost:51821 USER@SERVER_IP
Mantenere aperta questa sessione SSH e andare su http://localhost:51821 nel browser.
È possibile consentire l'accesso anche tramite HTTP semplice: in docker-compose.yml rimuovere il commento dal blocco environment, impostare INSECURE=true ed eseguire di nuovo sudo docker compose up -d. In questo caso la password del pannello viene inviata senza cifratura, quindi usare questa opzione solo per i test. Per un accesso permanente tramite nome di dominio, collocare il pannello dietro un reverse proxy con HTTPS.
Completare il primo avvio
Al primo avvio, wg-easy apre una procedura guidata di configurazione. Dopo la schermata di benvenuto, creare un account amministratore: inserire un nome utente e una password, quindi confermare la password.
Quando la procedura guidata chiede se esiste già una configurazione, scegliere No. In questo modo viene creata una nuova configurazione.
Nella schermata successiva, specificare Host e Port che i client useranno per connettersi. In Host inserire l'indirizzo IP pubblico o il nome di dominio del server, non localhost, anche se il pannello è stato aperto tramite il tunnel SSH. Lasciare Port su 51820. Il pulsante Suggest compila l'indirizzo rilevato automaticamente da wg-easy.
L'indirizzo indicato in Host viene inserito nella configurazione di ogni client. Se si inserisce un indirizzo errato, i client non potranno connettersi.
Al termine della procedura guidata, accedere con il nome utente e la password creati.
Creare un client
Nella pagina principale del pannello, fare clic su New Client, inserire un nome per il dispositivo, ad esempio laptop o phone, e confermare. Il client compare nell'elenco. Accanto sono presenti i pulsanti per mostrare il codice QR e scaricare il file di configurazione.
Creare un client separato per ogni dispositivo. In questo modo è possibile disattivare o eliminare l'accesso di un dispositivo senza influire sugli altri.
Collegare un dispositivo
Installare l'app ufficiale WireGuard sul proprio dispositivo. È disponibile per Windows, macOS, Android e iOS nella pagina ufficiale di download di WireGuard.
Su uno smartphone, aprire l'app WireGuard, scegliere di aggiungere un tunnel tramite codice QR e scansionare il codice dal pannello.
Su un computer, scaricare dal pannello il file di configurazione del client e importarlo nell'app WireGuard con Import tunnel(s) from file. Quindi fare clic su Activate.
Su Linux, installare wireguard-tools e openresolv. Senza openresolv, il comando wg-quick fallisce sulla riga DNS del file di configurazione. Su Ubuntu e Debian:
sudo apt install wireguard-tools openresolv sudo wg-quick up ./CLIENT_NAME.conf
Per disconnettersi su Linux, eseguire sudo wg-quick down ./CLIENT_NAME.conf.
Verificare la connessione
Con il tunnel attivo, verificare quale indirizzo IP vede Internet:
curl -4 ifconfig.me
Il comando dovrebbe restituire l'indirizzo IP del server. È anche possibile aprire nel browser un qualsiasi sito di verifica dell'IP. Nel pannello wg-easy, il client connesso mostra l'attività recente e il traffico.
Gestire i client
Tutti i client si gestiscono nella pagina principale del pannello. Ogni client può essere disattivato temporaneamente con l'interruttore accanto: il dispositivo resta nell'elenco ma non può connettersi finché non viene riattivato. Per rimuovere completamente l'accesso, eliminare il client. Il suo file di configurazione e il suo codice QR smettono di funzionare immediatamente. Se un dispositivo viene smarrito o un file di configurazione potrebbe essere stato copiato, eliminare quel client e crearne uno nuovo.
Se qualcosa non funziona
Se il pannello non si apre, verificare con sudo docker compose ps che il container sia in esecuzione e controllare il log:
sudo docker logs wg-easy
Se il pannello si apre ma non è possibile accedere e compare un messaggio su una connessione non sicura, il pannello è stato aperto tramite HTTP semplice. Usare il tunnel SSH descritto nella sezione precedente.
Se il client non riesce a connettersi, verificare che la porta UDP 51820 sia aperta nel firewall del server e nel firewall del pannello del provider, se presente. Aprire inoltre il file di configurazione del client e controllare la riga Endpoint: deve contenere l'indirizzo pubblico del server. Se contiene un indirizzo errato, l'Host è stato inserito in modo scorretto nella procedura guidata.
Se il tunnel è attivo ma il dispositivo non ha accesso a Internet, controllare il log del server con sudo docker logs wg-easy e assicurarsi che il container sia stato avviato dal docker-compose.yml ufficiale senza modifiche nella sezione sysctls.
Su Linux, se wg-quick fallisce con un errore relativo a resolvconf, installare openresolv come descritto nella sezione sul collegamento di un dispositivo.
Aggiornare wg-easy
Per installare una build più recente della versione 15, scaricare la nuova immagine e ricreare il container:
cd /etc/docker/containers/wg-easy sudo docker compose pull sudo docker compose up -d
Client e impostazioni vengono conservati, perché sono archiviati nel volume Docker.
Arrestare e rimuovere wg-easy
Per arrestare il server VPN, eseguire nella cartella con docker-compose.yml:
sudo docker compose down
La configurazione resta nel volume e sudo docker compose up -d riavvia il server con gli stessi client.
Per rimuovere completamente wg-easy, insieme a tutti i client e alle chiavi, aggiungere l'opzione -v:
sudo docker compose down -v
Dopo sudo docker compose down -v, tutte le configurazioni dei client smettono di funzionare. Per usare di nuovo la VPN sarà necessario completare il primo avvio e creare nuovamente i client.
