Automate non-ACME TLS cert renewals? (Tailscale cert)

maranite · June 22, 2025, 5:28am

A year in and I’m still thrilled with TrueNAS Scale!

… but need help sorting out one thing, please.

I use Tailscale to security access my TrueNAS Scale from anywhere, but the TLS (HTTPS) certificates which Tailscale generates keep expiring, and a script I wrote which renews the certs doesn’t work correctly.

My script to renew TLS certs is:

sudo docker exec -it ix-tailscale-tailscale-1 sh -c 'tailscale cert --cert-file /etc/certificates/tailscale.crt --key-file /etc/certificates/tailscale.key xxxxxx.ts.net'
sudo chmod 666 /etc/certificates/tailscale.*

… which effectively uses docker to ask the tailscale app to renew the TLS certificates and write them out to TrueNAS’s /etc/certificates folder.

Here’s the rub: The system doesn’t pick up that these files have been updated. It’s kinda like TrueNAS is secretly keeping private copies of the old certs elsewhere.

I’ve tried using the deprecated cli system certificates command, but not getting joy there either.

What is the correct way to automate certificate renewals when not using an ACME?

dan · June 22, 2025, 9:36am

Not secretly at all; everything is stored in the config database.

Using the API. A couple of tools to do this include:

github.com/danb35/deploy-freenas

README_truenas.md

master

# deploy-freenas

deploy_truenas.py is a Python script to deploy TLS certificates to a TrueNAS SCALE/Community Edition server using the TrueNAS Websocket API.  This should ensure that the certificate data is properly stored in the configuration database, and that all appropriate services use this certificate.  Its original intent was to be called from an ACME client like [acme.sh](https://github.com/acmesh-official/acme.sh) after the certificate is issued, so that the entire process of issuance (or renewal) and deployment can be automated.  However, it can be used with certificates from any source, whether a different ACME-based certificate authority or otherwise.

# Alternatives
This script isn't the only way to automate deployment of a TLS certificate to your TrueNAS SCALE/CE system.  Known alternatives include:
* [TrueNAS' own built-in mechanism](https://wiki.familybrown.org/en/fester/maintain-truenas/letsencrypt-scale).  It's far more complicated than necessary to set up, but if you use one of the supported DNS providers (Cloudflare, Digital Ocean, OVH, or Route53), and you don't need to deploy the same cert anywhere else, it's still probably the simplest way to go.
* Although it doesn't currently (early May 2025) seem to be documented anywhere, `acme.sh` has a deploy hook that works with the websocket API.  The closest I've found to documentation is [this section](https://github.com/acmesh-official/acme.sh/wiki/deployhooks#25-deploy-the-cert-on-truenas-core-server) in its wiki.  Substitute `--deploy-hook truenas_ws` in the given command to use this hook.  Note that as of this writing, this script can only be run on the TrueNAS host to which you're deploying the cert; it doesn't have any option to connect to a different host.
* [tnascert-deploy](https://github.com/jrushford/tnascert-deploy) implements many of the features of this script in Go, resulting in a statically-linked binary you can run pretty much anywhere with no other dependencies.  File size is much larger (roughly 8 MB for the binary vs. 10 KB for this script), but simplicity of installation may outweigh this, and the comparison is a little misleading, as it doesn't account for this script's dependencies.  Binaries are presently available for Linux/x64, FreeBSD/x64, macOS/ARM, and Windows, or you can build it yourself under any OS using Go.

Support for any of these, of course, is with their respective sources.

# Known issues
Connections to the Websocket API will fail if you have a HTTP -> HTTPS redirect enabled, either in TrueNAS itself or in some other system (e.g., Traefik) in front of TrueNAS.  This results from an [issue](https://github.com/truenas/api_client/issues/13) in the upstream API client.  If your NAS has a trusted and valid certificate, or you've set `verify_ssl = false` in `deploy_config`, you may be able to avoid this issue by setting `protocol = wss` in `deploy_config`.

# Status
* TrueNAS CE 25.04 - Works locally (running on the TrueNAS host) and remotely (so long as all dependencies are installed), but see notes below.
* TrueNAS SCALE 24.10 - Works locally and remotely.
* TrueNAS SCALE 24.04 - Works remotely only--the TrueNAS API client isn't installed in this version of TrueNAS.  Will not update certificates for apps on this or earlier versions of TrueNAS SCALE.
* TrueNAS SCALE 23.10 - Same as 24.04.

This file has been truncated. show original

and

Both of these are intended for ACME certs, but they’ll work for any valid cert.

maranite · June 22, 2025, 11:53am

Dan, you’re a legend! Thank you!

jjrushford · June 22, 2025, 1:31pm

I use certbot on my web server to renew my lets encrypt certificate. certbot provides a deploy hook feature. So I’ve installed a custom shell script in the certbot deployment hooks directory on my web server. Whenever my certificate renews, certbot calls the shell script which uses “tnascert-deploy” to automate the installation and UI restart of my two TrueNAS scale instances. tnascert-deploy supports TrueNAS scale versions 25 (fangtooth) and later. For earlier versions of TrueNAS, you’ll need to use the deploy_freenas.py script mentioned by @dan

A binary releases for Windows, MacOS, FreeBSD, and linux are available for download at:

tnascert-deploy version 1.2

The main Github repository with source and documentation is available at:

tnascert-deploy Git Repository