Come configurare WireGuard per accedere a Home Assistant da remoto

WireGuard crea una VPN privata tra il dispositivo remoto e la rete di casa. Home Assistant resta raggiungibile sul proprio indirizzo LAN e non viene pubblicato direttamente su Internet. Questa guida usa un host Linux come endpoint WireGuard; se l’host non è anche il router LAN, serve una rotta di ritorno verso la rete VPN oppure il NAT sul gateway.

Prerequisiti & Hardware Necessario

• Home Assistant funzionante su 192.168.1.10, porta interna 8123/TCP.
• Host Debian o Ubuntu sempre acceso, con IP LAN riservato 192.168.1.2.
• Router con firewall e port forwarding; un nome DNS o IP pubblico raggiungibile dall’esterno.
• Un client WireGuard per ogni telefono o computer. WireGuard è il software VPN; Raspberry Pi, mini PC o router sono l’hardware che lo esegue.

Procedura passo-passo

1. Riserva gli indirizzi. Imposta nel router 192.168.1.2 per il server VPN e 192.168.1.10 per Home Assistant. Usa per la VPN la rete 10.6.0.0/24 e verifica che non coincida con altre reti usate dai client.
2. Installa WireGuard su Debian o Ubuntu.

   sudo apt update
   sudo apt install wireguard

3. Genera le chiavi. Proteggi le chiavi private e non condividerle:

   sudo install -d -m 700 /etc/wireguard/keys
   cd /etc/wireguard/keys
   sudo sh -c 'umask 077; wg genkey | tee server_private.key | wg pubkey > server_public.key; wg genkey | tee client_private.key | wg pubkey > client_public.key'

4. Abilita il forwarding IPv4.

   echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-wireguard-forward.conf
   sudo sysctl --system
   sysctl net.ipv4.ip_forward

   Il valore atteso è 1.
5. Crea il server. In /etc/wireguard/wg0.conf sostituisci i segnaposto con le chiavi reali:

   [Interface]
   Address = 10.6.0.1/24
   ListenPort = 51820
   PrivateKey = SERVER_PRIVATE_KEY
   
   [Peer]
   PublicKey = CLIENT_PUBLIC_KEY
   AllowedIPs = 10.6.0.2/32

   Proteggi il file con sudo chmod 600 /etc/wireguard/wg0.conf.
6. Configura il routing. Se il server VPN non è il gateway LAN, aggiungi sul router una rotta statica per 10.6.0.0/24 via 192.168.1.2. In alternativa configura sul gateway VPN il NAT e il firewall tra wg0 e la LAN. Consenti almeno il traffico dalla VPN a 192.168.1.10:8123/TCP.
7. Avvia il servizio.

   sudo systemctl enable --now wg-quick@wg0
   sudo wg show

8. Inoltra la porta. Nel router inoltra solo UDP 51820 verso 192.168.1.2:51820. Non inoltrare la porta 8123. Con CGNAT il port forwarding IPv4 può non funzionare.
9. Configura il client. Importa nell’app WireGuard, sostituendo i segnaposto:

   [Interface]
   Address = 10.6.0.2/32
   PrivateKey = CLIENT_PRIVATE_KEY
   
   [Peer]
   PublicKey = SERVER_PUBLIC_KEY
   Endpoint = vpn.example.net:51820
   AllowedIPs = 10.6.0.0/24, 192.168.1.10/32
   PersistentKeepalive = 25

   PersistentKeepalive = 25 aiuta i client dietro NAT a ricevere traffico dopo l’inattività. Gli AllowedIPs instradano nel tunnel solo VPN e Home Assistant, non tutto Internet.
10. Accedi a Home Assistant. Disattiva il Wi-Fi, attiva il tunnel e apri http://192.168.1.10:8123. Nell’app Companion usa lo stesso URL locale come URL esterno solo se la VPN è sempre attiva fuori casa. Non aggiungere trusted_proxies o use_x_forwarded_for: sono impostazioni per reverse proxy, non per WireGuard.
11. Rafforza l’account. Usa password unica, MFA e account con privilegi minimi. La VPN protegge il trasporto, ma non sostituisce l’autenticazione di Home Assistant.

Verifica del funzionamento

1. Con il tunnel attivo esegui ping 10.6.0.1, se l’ICMP è consentito.
2. Sul server controlla sudo wg show: latest handshake deve aggiornarsi dopo il traffico.
3. Apri http://192.168.1.10:8123 da rete mobile e verifica il caricamento completo del frontend.
4. Disattiva il tunnel: dall’esterno Home Assistant deve risultare irraggiungibile, poiché la porta 8123 non è esposta.

Problemi comuni

FAQ essenziali

Devo aprire la porta 8123?

No. Inoltra solo la porta UDP di WireGuard, normalmente 51820.

Posso usare lo stesso profilo su più dispositivi?

No. Crea una coppia di chiavi e un indirizzo VPN distinti per ogni dispositivo; così puoi revocare un solo peer in caso di smarrimento.