Come installare un certificato SSL ACME su TrueNAS

Questa guida mostra come installare un certificato SSL ACME su TrueNAS utilizzando un host esterno e l’EAB (External Account Binding). È compatibile sia con TrueNAS CORE che con TrueNAS SCALE.

TrueNAS ha un supporto nativo per ACME, ma solo per Let’s Encrypt attraverso l’integrazione DNS-01 integrata. Se vuoi utilizzare un provider ACME commerciale (Sectigo, DigiCert, ecc.) con ACME + EAB, devi generare e rinnovare il tuo certificato esternamente utilizzando un client ACME come acme.sh, quindi distribuirlo in TrueNAS.

---

Prima di iniziare

Ecco cosa ti serve:

• Un nome di dominio che punta all’IP pubblico del tuo TrueNAS (ad esempio, nas.example.com)
• TrueNAS CORE 13.x o TrueNAS SCALE 23.x+
• Una macchina Linux/BSD esterna, un VPS o un server domestico (per eseguire acme.sh)
• URL della directory ACME, ID della chiave EAB e HMAC della CA commerciale.
• Accesso SSH a TrueNAS se hai intenzione di automatizzare la sincronizzazione

Nota: TrueNAS NON supporta provider ACME arbitrari nella sua interfaccia utente. Tutta l’automazione commerciale di ACME deve avvenire al di fuori di TrueNAS.

---

Passo 1: Installare acme.sh sull’host esterno

Questa macchina gestirà la registrazione, l’emissione e il rinnovo degli account ACME.

Corri:

curl https://get.acme.sh | sh
source ~/.bashrc
acme.sh --version

Se la versione viene stampata correttamente, sei a posto.

---

Passo 2: Registra il tuo account ACME con il tuo CA commerciale (ACME + EAB)

Il cruscotto del tuo CA ti fornirà:

• ID chiave EAB
• Chiave EAB HMAC
• URL della directory ACME

Registra il tuo account ACME:

acme.sh --register-account \
  --server https://acme.yourca.com/v2/acme \
  --eab-kid YOUR_EAB_KID \
  --eab-hmac-key YOUR_EAB_HMAC_KEY \
  --accountemail [email protected]

Sostituisci i valori con i tuoi. Puoi eseguirlo solo una volta.

---

Passo 3: Rilasciare il certificato (è richiesta la convalida DNS-01)

TrueNAS è quasi sempre dietro NAT, quindi la convalida DNS è la più sicura.

Ecco un esempio di DNS manaul:

acme.sh --issue \
  -d nas.example.com \
  --dns dns_manual \
  --server https://acme.yourca.com/v2/acme

acme.sh ti dirà di creare un record TXT:

_acme-challenge.nas.example.com   TXT   <token>

Crea il record TXT nel tuo gestore DNS e attendi la propagazione.

Controlla la propagazione:

dig TXT _acme-challenge.nas.example.com +short

Una volta visualizzato il token, esegui nuovamente lo stesso comando e acme.sh terminerà il rilascio del certificato. I file verranno salvati in ~/.acme.sh/nas.example.com/.

All’interno troverai:

• fullchain.cer: certificato del server + intermedio
• nas.example.com.key: chiave privata
• ca.cer: Catena CA (se fornita separatamente)

---

Passo 4: Importare il certificato in TrueNAS

1. Vai a: TrueNAS UI > Sistema > Certificati
2. Clicca su Aggiungi e seleziona Importa certificato
3. Carica i file del tuo certificato e clicca su Salva

Assegna il certificato ai tuoi servizi:

• Interfaccia utente web
• Servizi SMB / NFS (se applicabile)
• API middleware
• Proxy inversi o applicazioni che utilizzano HTTPS (TrueNAS SCALE)

---

Passo 5: Automatizzare il rinnovo e l’implementazione

TrueNAS non estrae automaticamente i certificati. Devi inserire i certificati rinnovati in TrueNAS.

1. Crea uno script di distribuzione

Sul tuo host ACME esterno, crea /usr/local/bin/truenas-deploy.sh:

Nota: questo script funziona solo se TrueNAS consente l’accesso a SSH con un utente autorizzato a eseguire midclt. Carica la nuova chiave + certificato su /tmp/ e sostituisce il certificato attivo attraverso l’API di TrueNAS. Assicurati che i percorsi e il dominio corrispondano alla configurazione di acme.sh.

#!/bin/bash

DOMAIN="nas.example.com"
NAS_USER="root"
NAS_HOST="truenas.local"

CERT_PATH="$HOME/.acme.sh/$DOMAIN"
KEY="$CERT_PATH/$DOMAIN.key"
CERT="$CERT_PATH/fullchain.cer"

scp "$KEY" "$NAS_USER@$NAS_HOST:/tmp/key.key"
scp "$CERT" "$NAS_USER@$NAS_HOST:/tmp/cert.cer"

ssh "$NAS_USER@$NAS_HOST" <<EOF
midclt call certificate.update '{"certificate": "custom", "csr": null, "privatekey": "$(cat /tmp/key.key)", "certificate": "$(cat /tmp/cert.cer)"}'
EOF

Rendilo eseguibile:

chmod +x /usr/local/bin/truenas-deploy.sh

2. Aggiungi un gancio per il rinnovo

Aggiungi un hook di deploy in acme.sh:

acme.sh --deploy-hook truenas-deploy \
  -d nas.example.com

Oppure aggiungi questo all’interno di ~/.acme.sh/deploy/truenas-deploy.sh.

3. Lascia che acme.sh gestisca tutto

Ecco cosa fa acme.sh automaticamente:

• Controlla quotidianamente i rinnovi
• Rinnova il certificato
• Attiva il tuo script di distribuzione
• Invia i certificati aggiornati a TrueNAS
• Applica le modifiche in modo silenzioso

Una volta configurato, non dovrai più toccare TrueNAS per il rinnovo dei certificati.

---

Domande comuni

Se stai configurando l’automazione ACME su TrueNAS per la prima volta, queste risposte rapide riguardano i problemi che gli utenti incontrano più spesso.

Posso utilizzare un certificato sia per la GUI di TrueNAS che per altri servizi (portali SMB, NFS, iSCSI)?

Sì. Una volta importato il certificato in System > Certificates, puoi selezionare lo stesso certificato per l’interfaccia web e per qualsiasi servizio che esponga HTTPS (interfaccia web, API, forse reverse proxy/HAProxy se lo usi). Non hai bisogno di certificati separati per ogni servizio, a meno che tu non voglia nomi di host diversi.

Il mio NAS è dietro CGNAT o doppio NAT. Posso ancora utilizzare ACME?

Sì, ma devi utilizzare la convalida DNS-01. HTTP-01 non funziona perché il server ACME non può raggiungere il tuo NAS sulla porta 80. Con il DNS-01, il CA controlla solo il record TXT di _acme-challenge.yourdomain.com, quindi non gli interessa dove si trova effettivamente il NAS.

Cosa succede se acme.sh rinnova il certificato ma io dimentico di reimportarlo in TrueNAS?

TrueNAS continuerà a utilizzare il vecchio certificato importato l’ultima volta. I file rinnovati rimarranno sul tuo host esterno fino a quando non li caricherai di nuovo (o lo script/API se ne occuperà).

Il tuo sito continuerà a funzionare, ma alla fine i browser inizieranno a segnalare la presenza di un certificato scaduto. Per questo motivo vale la pena di eseguire una nuova importazione tramite script o di inserire un promemoria in prossimità della data di scadenza.

Posso utilizzare un certificato wildcard (come *.example.com) con TrueNAS?

Sì. Finché la chiave privata e il certificato corrispondono, a TrueNAS non importa se si tratta di un certificato wildcard o single-host. Devi comunque rilasciare il certificato wildcard tramite DNS-01 in acme.sh, quindi importare fullchain.cer + *.example.com.key in TrueNAS. Fai attenzione a dove riutilizzi la chiave. Un certificato wildcard dà il pieno controllo su tutti i sottodomini che copre.

---

Parole finali

Questo flusso di lavoro ti offre un modo stabile e affidabile per installare un certificato ACME su TrueNAS senza combattere il sistema. Il tuo host esterno si occupa dell’emissione, del rinnovo e della gestione del certificato, mentre TrueNAS riceve semplicemente importazioni pulite ogni volta che i file vengono aggiornati.

Una volta che il processo è stato messo in atto, tutto viene eseguito silenziosamente in background e tu intervieni solo se vuoi regolare gli script o ruotare le credenziali.