New deploy hook: TrueNAS via WebSocket without midclt/Python (for remote deployment from non-TrueNAS hosts)

[Tok-Ra85]

Context

The existing truenas_ws deploy hook communicates with TrueNAS's WebSocket JSON-RPC API using midclt, which relies on the truenas_api_client Python package.

This works well when acme.sh runs directly on the TrueNAS box itself (where midclt is native), but it cannot work on hosts that don't have midclt Python available.

For example, when running acme.sh on OPNsense to push a certificate to a remote TrueNAS server.
OPNsense is FreeBSD-based and doesn't ship midclt or truenas_api_client, and installing a Python runtime + a third-party PyPI package just for this one integration is a heavy, non-idiomatic dependency for a firewall appliance.

This is also related to #6804 (the older truenas.sh REST-based hook being broken by the REST API deprecation/removal in TrueNAS 26), both existing hooks have practical gaps depending on where acme.sh is run.

What I built

A new deploy hook, truenas_ws_websocat, that talks to the same WebSocket JSON-RPC API (wss://<host>/api/current) but uses websocat instead of midclt/Python. websocat is a small, dependency-free binary (and already packaged for FreeBSD as www/websocat), which makes it a much lighter requirement for remote/non-TrueNAS hosts.

It keeps a single persistent WebSocket connection open for the whole deployment (auth, system.info, certificate import, Web UI assignment, restart, cleanup of the old certificate), and correctly handles certificate.create/certificate.delete as asynchronous jobs (polling core.get_jobs).
It also supports optional, opt-in updates for the FTP certificate and iX Apps using a TLS certificate, both disabled by default to keep the common case fast and side-effect-free.

It's written in pure POSIX sh (no bash-only constructs), since acme.sh deploy hooks are sourced by whatever shell is calling acme.sh this matters in particular for OPNsense (my usecase), where the calling shell is FreeBSD's /bin/sh, not bash.

I've tested it successfully end-to-end against TrueNAS SCALE 25.10.6, including certificate import, Web UI reassignment/restart, and old certificate cleanup.

I write it myself helped with Claude Code to fix somes bugs

Proposal

I'd like to contribute this as a new deploy hook (deploy/truenas_ws_websocat.sh), alongside the existing truenas_ws.sh, rather than replacing it.
So users who already have midclt available (e.g. running acme.sh on the TrueNAS host itself) aren't affected.

Before opening a PR, I wanted to check:

• whether this is a welcome addition, or whether you'd rather see the existing truenas_ws.sh hook itself modified to support both backends,
• naming preferences for the hook / function,
• any conventions I should follow that I might have missed.

Happy to share the script directly here before drafting the PR if relevant for people !

[github-actions]

Please upgrade to the latest code and try again first. Maybe it's already fixed. acme.sh --upgrade If it's still not working, please provide the log with --debug 2, otherwise, nobody can help you. Before posting the log, review it and REDACT any secrets: private keys (-----BEGIN ... PRIVATE KEY----- blocks), API tokens and passwords.

[Tok-Ra85]

Linked to :
#6337
#6804

[invario]

Personally, as a TrueNAS Scale/CE user myself, I'd gladly welcome this addition however you can get it merged. I'm currently using https://github.com/danb35/deploy-freenas to deploy but it also requires midclt and python, and this requires me to build a custom Docker image.

[neilpang]

A separate hook is fine -- keep truenas_ws.sh untouched. Use the shorter
name truenas_websocat.

Requirements for the PR:

• Pure POSIX sh, shebang #!/usr/bin/env sh. Hooks are sourced by the
  calling shell, so no bashisms anywhere.
• Check that the websocat binary exists early and _err a clear message
  if not.
• Read config via _getdeployconf / save via _savedeployconf. Call
  _getdeployconf FIRST, apply a default only if the value is still
  empty, otherwise saved config is ignored on cron renewal.
• Prefix every helper function and global variable with the hook name.
  All hooks share one shell.
• Use _info/_err/_debug, never bare echo. Pass the API key through
  _secure_debug, never plain _debug.
• Deploy the fullchain, not the leaf cert.
• Add a usage section to the wiki deployhooks page and link it from
  the PR.

Open the PR against the dev branch.

[Tok-Ra85]

PR posted : #7216
Wiki modified with this new hook (position 48 in the Wiki deploy )