acmesh-official / acmesh-official/acme.sh
New deploy hook: TrueNAS via WebSocket without midclt/Python (for remote deployment from non-TrueNAS hosts)
- Lingua principale
- Shell
- Stelle
- 47.6k
- Fork
- 5.7k
- Merge medio
- 7g 1h
- PR unite (30g)
- 16
Descrizione
### 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:///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 !
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.