Come configurare DuckDNS per Home Assistant

DuckDNS è un servizio di DNS dinamico: associa un sottodominio duckdns.org all’indirizzo pubblico variabile del router. Non è una VPN, non crea HTTPS da solo e non sostituisce un reverse proxy o un certificato TLS. Questa guida configura il nome DNS in Home Assistant e prepara una base corretta per l’accesso remoto cifrato.

Prerequisiti & Hardware Necessario

• Home Assistant funzionante e raggiungibile nella LAN, per esempio http://192.168.1.10:8123.
• Router con accesso alla configurazione DNS/NAT e connessione Internet con IPv4 pubblico oppure IPv6 raggiungibile. Con CGNAT il port forwarding IPv4 può non funzionare.
• Account DuckDNS, un sottodominio libero e il relativo token.
• Un metodo HTTPS: reverse proxy NGINX, Caddy, Let’s Encrypt o Home Assistant Cloud. DuckDNS da solo non cifra il traffico.
• Nessun prodotto hardware è necessario per questa configurazione software.

Procedura passo-passo

1. Crea il sottodominio. Accedi al sito DuckDNS, autentica il tuo account, crea un nome univoco e copia il token. Nell’esempio il nome completo sarà casa-domotica.duckdns.org. Non pubblicare il token e non inserirlo in repository o screenshot.
2. Verifica l’indirizzo pubblico. Dal router annota l’IPv4 WAN e confrontalo con quello mostrato da un servizio di verifica IP. Se il router riceve un indirizzo privato o condiviso, il provider può usare CGNAT: in quel caso DuckDNS aggiornerà il nome ma il traffico in ingresso non arriverà alla rete.
3. Aggiungi l’integrazione Duck DNS. In Home Assistant apri Impostazioni → Dispositivi e servizi → Aggiungi integrazione, cerca Duck DNS, inserisci il sottodominio senza il suffisso .duckdns.org e incolla il token. L’integrazione aggiorna periodicamente il record; non aggiungere il suffisso nel campo dominio se l’interfaccia lo chiede senza di esso.
4. Verifica la sincronizzazione. Attendi il primo aggiornamento e controlla che il record DuckDNS risolva all’IP pubblico attuale. Se hai ricreato il token, aggiorna la configurazione dell’integrazione: un token precedente non torna valido automaticamente.
5. Scegli il metodo HTTPS. Se usi NGINX o Caddy, fai terminare TLS sul reverse proxy e inoltra verso 192.168.1.10:8123. Se usi Home Assistant Cloud, non serve DuckDNS per l’accesso remoto. Non pubblicare Home Assistant in HTTP semplice sulla porta 8123.
6. Configura il port forwarding solo per il proxy. Con un reverse proxy inoltra TCP 80 e TCP 443 verso l’host proxy. Non inoltrare TCP 8123 direttamente a Home Assistant. Se il certificato usa una challenge DNS, segui le porte richieste dal metodo scelto.
7. Imposta l’URL Internet di Home Assistant. In Impostazioni → Sistema → Rete inserisci https://casa-domotica.duckdns.org come URL Internet. L’URL deve corrispondere al certificato e non deve contenere un percorso aggiuntivo.
8. Configura il proxy, se presente. Se Home Assistant riceve richieste da NGINX/Caddy, abilita in configuration.yaml use_x_forwarded_for: true e inserisci in trusted_proxies solo l’IP o la subnet reale del proxy. Questa impostazione non serve per DuckDNS da solo e non deve essere copiata in una configurazione VPN.
9. Testa dentro e fuori casa. Dalla LAN verifica il nome solo se il router gestisce hairpin NAT o split DNS. Da rete mobile apri https://casa-domotica.duckdns.org, controlla certificato, login, WebSocket e dashboard. Se il test esterno fallisce, non aumentare l’esposizione delle porte senza prima verificare CGNAT, DNS e routing.

Verifica del funzionamento

1. Risolvi il nome con nslookup casa-domotica.duckdns.org o dig casa-domotica.duckdns.org e confronta il risultato con l’IP WAN.
2. Controlla in Home Assistant che l’integrazione Duck DNS non riporti errori di autenticazione o aggiornamento.
3. Da rete mobile verifica che il certificato sia valido per il nome DuckDNS e che l’URL usi https://.
4. Controlla nel router che non esista una regola WAN verso 192.168.1.10:8123.
5. Simula un cambio IP riavviando la connessione WAN solo se il provider lo consente e verifica che il nome venga aggiornato dopo l’intervallo previsto; l’aggiornamento non è necessariamente istantaneo.

Problemi comuni

FAQ essenziali

DuckDNS rende Home Assistant sicuro?

No. Aggiorna solo il nome DNS. Per l’accesso pubblico serve HTTPS con certificato valido oppure una VPN come Tailscale o WireGuard.

DuckDNS elimina il problema CGNAT?

No. Il nome può aggiornarsi all’indirizzo condiviso, ma senza un percorso in ingresso il router non riceve le connessioni. Usa un IP pubblico, una VPN overlay o Home Assistant Cloud.