truenas-scale-acme

README

truenas-scale-acme

truenas-scale-acme optains and manages certificates for TrueNAS Scale using the ACME DNS-01 challenge and the TrueNAS Scale API.

It uses Caddy's caddyserver/certmagic library internally to optain and renew SSL certificates and ensures that TrueNAS uses a valid certificate to serve requests.

Supported DNS-Providers

Currently the following providers are supported:

• acme-dns
• cloudflare

If you require a different provider, feel free to create an issue. In theory, all github.com/libdns providers can be supported.

Install

Homebrew

brew tap thde/truenas-scale-acme
brew install thde/truenas-scale-acme/truenas-scale-acme

curl

mkdir truenas-scale-acme
curl -L $(curl -s https://api.github.com/repos/thde/truenas-scale-acme/releases/latest |
    jq -r '.assets[].browser_download_url | select(contains ("linux_amd64"))') |
    tar xvz -C ./truenas-scale-acme

Getting Started

1. Create an API key in TrueNAS
2. Register an account on ACME-DNS server:

   curl -X POST https://auth.acme-dns.io/register
   

3. Create a DNS CNAME record that points from _acme-challenge.your-domain.example.com to the fulldomain from the registration response.
4. Use the credentials obtained in step 1 and 2 to configure truenas-scale-acme (default ~/.config/truenas-scale-acme/config.json):

   {
     "domain": "nas.domain.com",
     "scale": {
       "api_key": "s3cure",
       "url": "https://localhost/api/v2.0/",
       "skip_verify": true
     },
     "acme": {
       "email": "myemail@example.com",
       "tos_agreed": true,
       "acme-dns": {
         "username": "00000000-0000-0000-0000-000000000000",
         "password": "s3cure",
         "subdomain": "FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF",
         "server_url": "https://auth.acme-dns.io"
       }
     }
   }
   

5. Run truenas-acme-scale and verify that the certificate is issued and updated successfully.
6. Setup a cronjob that runs truenas-acme-scale daily as the correct user.

CA's

truenas-scale-acme currently has the following CA's configured by default:

1. Let's Encrypt
2. ZeroSSL

This ensures a valid certificate even if one CA is unavailable.

Other Solutions

• TrueNAS SCALE/ACME Certificates - TrueNAS Scale integrated ACME functionality using DNS authentication. Includes support for external shell commands.
• danb35/deploy-freenas - Python script to deploy TLS certificates to a TrueNAS Core using its API.
• acmesh-official/acme.sh/deploy/truenas.sh - acme.sh deploy script for TrueNAS Core using its API.