Como instalar um certificado SSL da ACME no TrueNAS

Este guia mostra como instalar um certificado ACME SSL no TrueNAS usando um host externo e EAB (External Account Binding). Ele é compatível com o TrueNAS CORE e o TrueNAS SCALE.

O TrueNAS tem suporte nativo ao ACME, mas somente para o Let’s Encrypt por meio de sua integração DNS-01 integrada. Se você quiser usar um provedor ACME comercial (Sectigo, DigiCert, etc.) com ACME + EAB, deverá gerar e renovar seu certificado externamente usando um cliente ACME, como acme.sh, e depois implantá-lo no TrueNAS.

---

Antes de você começar

Aqui está o que você precisará:

• Um nome de domínio que aponte para o IP público do TrueNAS (por exemplo, nas.example.com)
• TrueNAS CORE 13.x ou TrueNAS SCALE 23.x+
• Uma máquina Linux/BSD externa, VPS ou servidor doméstico (para executar o acme.sh)
• URL do diretório ACME, ID da chave EAB e HMAC EAB da sua CA comercial
• Acesso SSH ao TrueNAS se você planeja automatizar a sincronização

Observação: O TrueNAS NÃO oferece suporte a provedores ACME arbitrários em sua interface do usuário. Toda automação comercial do ACME deve ocorrer fora do TrueNAS.

---

Etapa 1: instalar o acme.sh em seu host externo

Essa máquina processará o registro, a emissão e a renovação de contas ACME.

Você pode correr:

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

Se a versão for impressa corretamente, você está pronto.

---

Etapa 2: Registre sua conta ACME com sua CA comercial (ACME + EAB)

Seu painel de controle da CA fornecerá:

• ID da chave EAB
• Chave HMAC do EAB
• URL do diretório ACME

Registre sua conta 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]

Substitua os valores por seus próprios valores. Você só deve executar isso uma vez.

---

Etapa 3: Emitir o certificado (é necessária a validação do DNS-01)

O TrueNAS quase sempre está protegido por NAT, portanto, a validação de DNS é a mais segura.

Aqui está um exemplo de DNS manual:

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

O acme.sh dirá a você para criar um registro TXT:

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

Crie o registro TXT em seu gerenciador de DNS e aguarde a propagação.

Verifique a propagação:

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

Quando o token aparecer, execute novamente o mesmo comando e o acme.sh concluirá a emissão do certificado. Seus arquivos serão salvos em ~/.acme.sh/nas.example.com/.

No interior, você encontrará:

• fullchain.cer: certificado do servidor + intermediário
• nas.example.com.key: chave privada
• ca.cer: Cadeia CA (se fornecida separadamente)

---

Etapa 4: Importar o certificado para o TrueNAS

1. Ir para: TrueNAS UI > Sistema > Certificados
2. Clique em Adicionar e selecione Importar certificado
3. Carregue seus arquivos de certificado e clique em Salvar

Atribua o certificado a seus serviços:

• IU da Web
• Serviços SMB/NFS (se aplicável)
• APIs de middleware
• Proxies reversos ou aplicativos que usam HTTPS (TrueNAS SCALE)

---

Etapa 5: automatizar a renovação e a implantação

O TrueNAS não extrai certificados automaticamente. Você deve enviar certificados renovados para o TrueNAS.

1. Crie um script de implementação

No host ACME externo, crie o arquivo /usr/local/bin/truenas-deploy.sh:

Observação: este script funciona somente se o TrueNAS permitir o acesso SSH com um usuário autorizado a executar midclt. Ele faz upload da nova chave + certificado para /tmp/ e substitui o certificado ativo por meio da API do TrueNAS. Certifique-se de que seus caminhos e domínio correspondam à configuração do 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

Torne-o executável:

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

2. Adicionar um gancho de renovação

Adicione um gancho de implantação em acme.sh:

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

Ou adicione isso em ~/.acme.sh/deploy/truenas-deploy.sh.

3. Deixe o acme.sh cuidar de tudo

Aqui está o que o acme.sh faz automaticamente:

• Verifica as renovações diariamente
• Renova o certificado
• Aciona seu script de implantação
• Envia certificados atualizados para o TrueNAS
• Aplica as alterações silenciosamente

Uma vez configurado, você não precisa tocar no TrueNAS novamente para renovações de certificados.

---

Perguntas comuns

Se você estiver configurando a automação ACME no TrueNAS pela primeira vez, estas respostas rápidas abordam os problemas que os usuários encontram com mais frequência.

Posso usar um certificado para a GUI do TrueNAS e para outros serviços (SMB, NFS, portais iSCSI)?

Sim. Depois de importar o certificado em System > Certificates, você pode selecionar o mesmo certificado para a interface do usuário da Web e para qualquer serviço que exponha HTTPS (interface do usuário da Web, API, talvez proxy reverso/HAProxy, se você o usar). Você não precisa de certificados separados por serviço, a menos que queira nomes de host diferentes.

Meu NAS está atrás de CGNAT ou NAT duplo. Ainda posso usar o ACME?

Sim, mas você deve usar a validação DNS-01. O HTTP-01 não funcionará porque o servidor ACME não pode acessar seu NAS pela porta 80. Com o DNS-01, a CA verifica apenas o registro TXT em _acme-challenge.yourdomain.com, portanto, não importa onde o NAS realmente se encontra.

O que acontecerá se o acme.sh renovar o certificado, mas eu me esquecer de reimportá-lo para o TrueNAS?

O TrueNAS continuará usando o certificado antigo que você importou da última vez. Os arquivos renovados permanecem no host externo até que você os carregue novamente (ou seu script/API cuide disso).

Seu site ainda funcionará, mas, eventualmente, os navegadores começarão a avisar sobre um certificado expirado. É por isso que vale a pena programar a reimportação ou colocar um lembrete próximo à data de expiração.

Posso usar um certificado curinga (como *.example.com) com o TrueNAS?

Sim. Contanto que a chave privada e o certificado correspondam, o TrueNAS não se importa se é um curinga ou um certificado de host único. Você ainda precisa emitir o curinga via DNS-01 em acme.sh e, em seguida, importar fullchain.cer + *.example.com.key para o TrueNAS. Apenas tome cuidado onde você reutiliza essa chave. Um certificado curinga oferece controle total sobre todos os subdomínios que ele abrange.

---

Palavras finais

Esse fluxo de trabalho oferece a você uma maneira estável e confiável de instalar um certificado ACME no TrueNAS sem precisar lutar contra o sistema. Seu host externo lida com a emissão, a renovação e o gerenciamento do certificado, enquanto o TrueNAS simplesmente recebe importações limpas sempre que os arquivos são atualizados.

Depois que o processo é implementado, tudo é executado silenciosamente em segundo plano, e você só entra em cena se quiser ajustar scripts ou alternar credenciais.