community italiana di domotica personale
 
Installare e configurare Caddy (reverse proxy) su Home Assistant OS/Supervised
Guide

Installare e configurare Caddy (reverse proxy) su Home Assistant OS/Supervised

 , , , , ,
SCOPI DELLA GUIDA:
  • Installare e configurare un servizio reverse proxy per la propria rete domestica basato su Caddy, usando gli add-on di Home Assistant OS/Supervised
  • Livello di difficoltà: medio
CONCETTI AFFRONTATI:
  • Utilizzo e configurazione software
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
GUIDA indicatA per UTENTI:

Ambiente HassOS
NOTE E DISCLAIMER
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata e realizzata SOLO da personale qualificato;
  • qualsiasi modifica non prevista attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno infatti puro scopo didattico) e fa decadere garanzia, omologazioni e certificazioni di qualità; dei dispositivi interessati;
  • tutte le tecniche descritte si intendono applicate a software e firmware aggiornati alle ultime versioni disponibili;
  • gli articoli di inDomus sono totalmente indipendenti e non sponsorizzati. Se mai questo cambiasse, verrà segnalato chiaramente sulle pagine oggetto di sponsorizzazione;
  • questa pagina è materialmente scritta e manutenuta da più individui: non ci si aspetti né si pretenda un supporto personale. In caso di difficoltà, chiedere supporto alla community sul nostro forum o sulla nostra chat;
  • se hai bisogno di orientarti, c'è la mappa.
Revisione guida: 1.1

Caddy - HassOS

Abstract

Tramite Home Assistant OS/Supervised è relativamente facile dotarsi di un servizio reverse proxy per la propria rete domestica.

L’adozione di un add-on gratuito come Caddy, per esempio, consente di realizzare tale funzionalità di rete in pochi e semplici passi; tale strumento può poi essere configurato e utilizzato per le sue tipiche funzioni di reindirizzamento delle chiamate da Internet verso servizi presenti sulla propria rete interna nonché l’ottenimento automatico degli eventuali certificati crittografici utili alla navigazione sicura verso tali servizi.

Solitamente, chi adotta un servizio di reverse proxy tramite add-on di HassOS/Supervised lo fa perché gli è utile per la connessione remota sicura verso la propria domotica personale basata su Home Assistant. Questa guida è dedicata sia alla configurazione generica di Caddy sia a quella specifica per l’uso con Home Assistant.

N.b. Sebbene non si tratti di scienza missilistica, l’implementazione di questa guida prevede un minimo di cultura sul networking nonché sul funzionamento del reverse proxy. Inutile e deleterio tentare di configurare su Caddy senza conoscere l’abc su questi temi.

ATTENZIONE: Per funzionare, questa guida dev’essere letta con particolare attenzione e calma. Pena, il probabile fallimento della configurazione del servizio.

Si parte

Assunti

Questa guida è dedicata a chi abbia già in uso l’HUB Home Assistant OS/Supervised. Il computer ospitante l’HUB può essere qualsiasi, dal tradizionale Raspberry Pi a un computer vero e proprio, o altro.

Le guide disponibili su inDomus per installare HassOS sono:

Si assume infine che l’host ospitante Caddy possegga un indirizzo IP fisso assegnato automaticamente dal router domestico.

Dominio

N.b. Se si possiede un dominio proprio o comunque una gestione DDNS diversa da DuckDNS, si può saltare direttamente alla sezione “Port forwarding“.

Affinché sia raggiungibile dall’esterno in modo semplificato, il punto di accesso alla rete domestica (ovvero interfaccia WAN del modem) deve esser rappresentato da un nome univoco (chiamato FQDN) il quale veda l’IP ad esso associato aggiornarsi automaticamente ad ogni variazione, dato che quello assegnato al vostro modem/router cambia ciclicamente. Per fare questo interviene il servizio Dynamic DNS (o DDNS), ovvero un servizio che tenga traccia dell’ultima variazione e risponda, ai sistemi che chiedano la risoluzione (traduzione) del nome DNS, l’ultimo IP conosciuto, ovvero quello in uso.

DuckDNS è il servizio che abbiamo scelto per questa funzione di fornitura di FQDN nonché di associazione dinamica dell’IP.

N.b. Caddy può serenamente gestire anche domini propri acquistati e gestiti sulla rete dai più diversi fornitori diversi da DuckDNS. Come vedremo a seguire, la “challenge” (ovvero la procedura di ottenimento automatica dei certificati) varia da fornitore a fornitore: impossibilitati a documentare qualsiasi casistica possibile, in questa guida analizzeremo le più comuni modalità di challenge tra i servizi più comunemente usati. Ciononostante, con i debiti accorgimenti la guida di massima è valida anche per gli altri casi.

Collegarsi quindi al servizio tramite l’indirizzo https://www.duckdns.org e, una volta registrati creare un proprio nome dominio che, univocamente, rappresenterà il vostro modem collegato ad Internet. Il suffisso è sempre lo stesso (“.duckdns.org“) mentre ciò che cambia e va scelto è il suffisso (per esempio “casamia“).

Per questa guida, daremo per assunto di aver creato il seguente FQDN:

casamia.duckdns.org

dove “duckdns.org” è la parte fissa mentre casamia è il nome di dominio da noi creato a mo’ di esempio.

All’interno della vostra sezione privata di DuckDNS troverete anche un campo importante chiamato “token“, il quale appare analogo a questo:

e3ff465f-c6d6-acb1-4416-44b2af152111

Appuntarselo da una parte, tornerà utile a breve.

Aggiornamento di DuckDNS

Ora è necessario implementare su Home Assistant un elemento che, a fronte dell’eventuale cambiamento dell’IP Internet sull’interfaccia WAN del proprio modem/router, comunichi tale variazione a DuckDNS, in modo da aggiornare la conseguente risoluzione dell’FQDN.

Per far questo è sufficiente seguire questa breve guida:

Aggiornare il proprio record su DuckDNS tramite automazione Home Assistant

N.b. Questo paragrafo non va attuato se sulla propria rete c’è già qualche dispositivo che provveda a tale funzione di associazione dell’IP con il proprio FQDN, come per esempio un modem/router FRITZ!Box o altri modelli/marche in grado di effettuare da sé l’operazione. Se e quando un modem è in grado di provvedere a tale funzione, è sempre buona regola lasciare che sia lui ad aggiornare tale associazione, e non ad altri host della propria rete.

Port forwarding

Per far sì che Caddy possa autonomamente provvedere all’ottenimento di eventuali certificati SSL per il proprio FQDN nonché accettare le connessioni esterna da girare – in quanto reverse proxy – è necessario configurare delle regole di port forwarding sul modem/router. Il cosiddetto “aprire le porte”.

Prima di proseguire oltre – se non si ha già dimestichezza col port forwarding – si consiglia la lettura di questo articolo.

IMPORTANTE.

Le regole di port forwarding variano in base alle porte che si vogliano esporre verso Internet rispetto a quelle aperte (e da raggiungere) internamente. Questo non è oggetto della presente guida, in quanto qualsiasi guida presente su inDomus che referenzi la presente e che utilizzi Caddy come reverse proxy spiegherà questo aspetto nello specifico del servizio.

Ciò che viene spiegato in questa occasione – ovvero alla prima installazione e configurazione di Caddy – è relativo alle porte (eventualmente) da aprire in caso si voglia far provvedere a Caddy all’ottenimento di eventuali certificati SSL per la securizzazione delle comunicazioni dentro-fuori.

I certificati crittografici, per essere considerati validi, devono essere rilasciati da una Certification Authority riconosciuta: nel caso della presente guida utilizzeremo il servizio gratuito Let’s Encrypt. Questo processo viene automatizzato sfruttando uno specifico protocollo (chiamato ACME Protocol) il quale prevede tre modalità diverse, dette anche challenge, per appurare la propria “identità” al gestore del servizio e ottenere quindi i certificati richiesti. Tali modalità sono:

  • HTTP Challenge
  • TLS-ALPN Challenge
  • DNS Challenge

Su Caddy le prime due challenge vengono utilizzate di default, la terza invece va eventualmente abilitata in configurazione (il che disabilita le prime due).

  • TLS-ALPN Challenge: Questa è la prima challenge che viene tentata di default da Caddy. Tecnicamente, viene effettuata una DNS lookup verso il proprio FQDN per il quale viene richiesto il certificato e viene eseguita una specifica request sulla porta TCP 443. Se alla CA viene restituito il risultato atteso, avviene il rilascio del certificato. Per questa challenge è necessaria l’apertura della porta TCP 443 verso l’host che ospita Caddy.
  • HTTP Challenge: Si tratta della seconda challenge che viene tentata di default da Caddy. Anche qui viene effettuata una DNS lookup verso il proprio FQDN per il quale viene richiesto il certificato e viene effettuata una specifica request sulla porta TCP 80. Se alla CA viene restituito il risultato atteso, avviene il rilascio del certificato. Com’è facile intuire, questa challenge necessità dell’apertura della porta TCP 80 verso l’host che ospita Caddy.
  • DNS challenge: Questa challenge non viene tentata in automatico ma, come detto prima, va eventualmente configurata (disabilitando di conseguenza le precedenti due). Diversamente dalle altre non necessita di apertura porte ma richiede una specifica configurazione: caddy deve poter accedere al provider DNS del proprio dominio per impostare i cosidetti TXT record in modo tale che, quando viene effettuata l’authoritative DNS lookup verso il provider DNS per la ricerca del TXT record, venga effettivamente restituito il valore atteso.

Dunque, quali porte vanno “aperte” tramite port forwarding e girate verso l’host che ospita Caddy? La TCP 80, la 443 o nessuna?

La scelta ovviamente è soggettiva e dipende da diversi fattori. Dipende in primis dal DNS provider, in base se esso consenta o meno la scrittura dei TXT record. Dipende anche dal proprio modem: non tutti permettono l’apertura delle porte 80 e 443. Dipende dalla volontà o meno di voler esporre il proprio server sulle porte 80 e 443. Per fare qualche esempio:

  • se abbiamo un comune modem che consente il port forwarding della porta TCP 443 o della TCP 80 e utilizziamo DucKDNS, ci basta HTTP-Challenge;
  • se abbiamo un vecchio modem Fastweb che non permette il port forwarding della porta TCP 80 e non abbiamo un provider DNS che permetta l’impostazione dei TXT record (magari perché non previsto dal servizio gratuito), possiamo pensare di sfruttare la TLS-ALPN inoltrando il traffico sulla 443 verso Caddy;
  • se invece abbiamo acquistato un dominio possiamo ad esempio farlo gestire a Cloudflare e sfruttare la DNS Challenge;
  • se abbiamo registrato un dominio su noip.com e facciamo l’upgrade a pagamento, possiamo impostare i TXT record e scegliere di usufruire della DNS Challenge evitando di esporre altre porte.

e altro.

In questa guida assumeremo di utilizzare la casistica più classica, ovvero il primo esempio qui sopra spiegato, ovvero quello che utilizza port forwarding della porta TCP 443 o TCP 80 nonché – come vedremo – la corretta challenge prevista per DuckDNS (la TLS-ALPN).

La configurazione per il port forwarding sul modem da noi consigliata è:

  • IP destinazione: IP statico dell’host ospitante Caddy (assegnato precedentemente)
  • Porta esterna: TCP 443
  • Porta interna: TCP 443

oppure

  • IP destinazione: IP statico dell’host ospitante Caddy (assegnato precedentemente)
  • Porta esterna: TCP 80
  • Porta interna: TCP 80

Vetrina - Offerte del giorno

Punto della situazione

Arrivati a questo punto della guida abbiamo:

  • un FQDN rappresentante il nostro punto di ingresso alla rete locale;
  • un sistema di aggiornamento automatico dell’FQDN;
  • un port forwarding su porta TCP 80 o 443 (o nessuno, se si usa la DNS Challenge).

Ora non manca che installare Caddy e far sì che nella sua configurazione ci sia l’ottenimento automatico dei certificati da parte di Let’s Encrypt per il nostro FQDN.

Installare Caddy

A questo punto è possibile provvedere all’installazione di Caddy, il quale viene eseguito come processo tramite l’aggiunta di un add-on Home Assistant OS. Si tratta, però, di un add-on custom pertanto non nativamente disponibile presso l’add-on store di Home Assistant OS.

Per installare l’add-on, cliccare, presso il menu, la voce:

  • “Impostazioni” > “Componenti aggiuntivi” e poi sul pulsante “Raccolta di componenti aggiuntivi“.

Si tratta di accedere ad una vera e propria “vetrina” di componenti aggiuntivi (gratuiti) che, proprio come mattoncini da costruzioni, andranno ad arricchire le funzionalità del nostro HUB. Per installarlo è primariamente necessario aggiungere un repository alla lista di quelli già presenti, nello specifico questo indirizzo:

https://github.com/einschmidt/hassio-addons

Per farlo, recarsi alla voce di menu “Repository” > “Aggiungi“.

Successivamente, cercare tra gli add-on disponibili “Caddy”: si troverà “Caddy 2“:

HassoOS - Caddy add-on

Cliccarci sopra per accedere alla scheda di dettaglio, poi cliccare su “INSTALLA“:

Caddy HASSIO add-on - installazione

Al termine dell’installazione, non avviare il l’add-on: è necessario, prima, configurarlo.

Configurare Caddy

N.b. L’add-on, di suo, offrirebbe di default una configurazione minimale, modificabile da interfaccia, che consente di evitare l’uso di un file di configurazione specifico. Di contro, tale configurazione limita l’uso di Caddy col solo Home Assistant, quando invece questa guida è concepita per consentire sì la connessione remota sicura di Home Assistant ma anche di eventuali altri servizi. Inoltre, l’uso del file di configurazione consente di effettuare dei test di corretto funzionamento prima di richiedere formalmente i certificati definitivi, cosa che diversamente non è possibile fare.

Per questi più che validi motivi documentiamo la configurazione che prevede l’uso del file di configurazione, sebbene (leggermente!) più complicata ma più efficace.

A questo punto è necessario recarsi, presso la scheda dell’add-on Caddy, alla voce “Configurazione“, cliccando poi sulla voce di menu “Modifica in YAML” presso i tre puntini in alto a destra.

Al posto della configurazione di default:

args: []
env_vars: []
log_level: info
non_caddyfile_config:
  destination: localhost
  domain: mydomain.com
  email: your@email.com
  port: 8123

impostare la seguente configurazione:

args:
  - "--watch"
env_vars: []
log_level: info
non_caddyfile_config:
  destination: localhost
  domain: mydomain.com
  email: your@email.com
  port: 8123
config_path: /config/caddy/Caddyfile

E terminare cliccando su “SALVA“.

Ora, prima di avviare l’add-on è necessario creare un file la quale conterrà la sua configurazione chiamato “Caddyfile“.
Per farlo, usare File Editor (o SSH, se si preferisce): creare la cartella “caddy” sotto “/config“, poi il file “Caddyfile” dentro “caddy“.

All’interno di “Caddyfile” copiare il seguente codice:

#  When your config is ok comment block below to disable use of AMCE staging server
{
    acme_ca https://acme-staging-v02.api.letsencrypt.org/directory 
}

https://casamia.duckdns.org { 
  respond "Saluti dal Crew inDomus.it"
  file_server
}

Dove ovviamente “casamia.duckdns.org” andrà personalizzato col proprio FQDN.
Una volta completata la modifica, usciamo dall’editor salvando il file (CTRL+x, y, invio).

N.b. Si noti come in alto nel file di configurazione sia stato esplicitamente (e volutamente) indicato il server ACME di test di Let’s Encrypt (https://acme-staging-v02.api.letsencrypt.org/directory). Questa scelta è voluta: consente di effettuare una prima prova, altrimenti utilizzando direttamente quello di esercizio si rischierebbe, in caso di problemi, di rimanere impossibilitati a fare nuove richieste per diversi giorni. Superata questa la prima fase, correggeremo il file di configurazione in modo appropriato a tempo debito.

A questo punto avviamo l’add-on di Caddy, dopodiché rechiamoci presso la tab “Registri” dell’add-on.

Nei log dovremmo trovare qualcosa come:

{"level":"info","ts":1610093092.9648476,"logger":"tls.issuance.acme.acme_client","msg":"validations succeeded; finalizing order","order":"https://acme-staging-v02.api.letsencrypt.org/acme/order/yyyyyy/zzzzzz"} 
{"level":"info","ts":1610093093.8919973,"logger":"tls.issuance.acme.acme_client","msg":"successfully downloaded available certificate chains","count":2,"first_url":"https://acme-staging-v02.api.letsencrypt.org/acme/cert/xxxxxxxxxxxxxxxxxxxxxxxxxxx"} 
{"level":"info","ts":1610093093.8923566,"logger":"tls.obtain","msg":"certificate obtained successfully","identifier":"casamia.duckdns.org"}

il che confermerà il funzionamento del tutto.
In caso di problemi, ripetere i passi precedenti, portando particolare attenzione alla configurazione di port forwarding sul modem/router.

Come spiegato sopra, questi non sono i certificati definitivi: dovremo quindi fermare il container Docker di Caddy, modificare il file di configurazione e riavviarlo.

Torniamo sul file e cancelliamo le prime quattro righe; il contenuto del file di configurazione diventerà quindi:

https://casamia.duckdns.org { 
  respond "Saluti dal Crew inDomus.it"
  file_server
}

Dove ovviamente “casamia.duckdns.org” andrà personalizzato col proprio FQDN.
Una volta completata la modifica, usciamo dall’editor salvando il file (CTRL+x, y, invio).

Riavviamo dunque l’add-on. Dopo il riavvio, verifichiamo i log: anche in questo caso dovremmo trovare:

{"level":"info","ts":1610092585.0720239,"logger":"tls.issuance.acme.acme_client","msg":"validations succeeded; finalizing order","order":"https://acme-v02.api.letsencrypt.org/acme/order/yyyyyy/zzzzzz"}
{"level":"info","ts":1610092586.0094872,"logger":"tls.issuance.acme.acme_client","msg":"successfully downloaded available certificate chains","count":2,"first_url":"https://acme-v02.api.letsencrypt.org/acme/cert/xxxxxxxxxxxxxxxxxxxxxxxxxxx"} 
{"level":"info","ts":1610092586.0111442,"logger":"tls.obtain","msg":"certificate obtained successfully","identifier":"casamia.duckdns.org"}

il che confermerà il funzionamento definitivo del tutto.
A questo punto come verifica finale possiamo puntare al dominio configurato nel Caddyfile

https://casamia.duckdns.org

Congratulazioni: Caddy è ora operativo.

Abbiamo finito?

In realtà, nì.

Caddy, di per sé ora è operativo ma, in buona sostanza, non sta facendo nulla se non ottenere automaticamente gli aggiornamenti dei certificati per il nostro FQDN. Va da sé che per utilizzarlo per ciò che è concepito, ovvero la funzione di reverse proxy, sarà necessario indicare in configurazione (nel “Caddyfile”) quali regole implementare e riavviare coerentemente il container, oltre a implementare le relative regole di port forwarding sul modem/router.

Un esempio: Home Assistant

Ipotizziamo di voler gestire il traffico esterno per la propria istanza di Home Assistant presente sulla rete interna in modo da farlo raggiungere dall’esterno su porta 9000 (e in modo sicuro con certificati SSL) per controllare la propria domotica in remoto.

Le cose da fare sono:

  • modificare coerentemente il “Caddyfile”;
  • configurare il port forwarding;
  • riavviare l’add-on Caddy.
MODIFICA AL CADDYFILE

Modificheremo il Caddyfile come segue:

(https_header) {
  header {
    Strict-Transport-Security "max-age=31536000; includeSubdomains"
    X-XSS-Protection "1; mode=block"
    X-Content-Type-Options "nosniff"
    X-Frame-Options "SAMEORIGIN"
    Referrer-Policy "same-origin"
  }
}

https://casamia.duckdns.org { 
  respond "Saluti dal Crew inDomus"
  file_server
}
https://casamia.duckdns.org:9000 { 
  import https_header
  reverse_proxy http://IP_DELLA_ISTANZA_HOME_ASSISTANT:8123
}

Come si nota, la regola indica che tutte le richieste https verso casamia.duckdns.org:9000 vengano reindirizzate verso l’indirizzo interno http://IP_DELLA_ISTANZA_HOME_ASSISTANT:8123.

CONFIGURARE IL PORT FORWARDING

Sul modem/router, definire una regola di port forwarding così modellata:

  • IP destinazione: IP statico dell’host che che ospita Caddy
  • Porta esterna: TCP 9000
  • Porta interna: TCP 9000

Questo ovviamente è solo un esempio illustrativo: per tutte le possibili configurazioni (non documentate da inDomus) si consiglia di far riferimento direttamente alla documentazione Caddy.

RICONFIGURARE HOME ASSISTANT

Dato che abbiamo portato l’esempio di Home Assistant, dopo la configurazione di Caddy ricordarsi anche di effettuare un’ultima modifica, ma stavolta lato Home Assistant.

⚠️ Se di Home Assistant ne sai poco ma sei interessato a capirne di più, ti suggeriamo di partire da qui.

Questa pagina è redatta, manutenuta e aggiornata dallo staff di inDomus, un gruppo di persone molto diverse tra loro che trovi, per domande e supporto, sul forum e sulla chat del sito. Alcuni link sono taggati in qualità di affiliati Amazon e riceviamo un compenso dagli acquisti idonei, utile al sostenimento del sito, ma le nostre recensioni sono tutte indipendenti e non sponsorizzate. Se ti sei perso, a tua disposizione c'è la mappa.