# 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
