acmesh-official / acmesh-official/acme.sh
New deploy hook: TrueNAS via WebSocket without midclt/Python (for remote deployment from non-TrueNAS hosts)
- Ngôn ngữ chính
- Shell
- Star
- 47.6k
- Fork
- 5.7k
- Merge trung bình
- 6 ngày 5 giờ
- Pull request đã merge (30 ngày)
- 15
Mô tả
### 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 !
Hướng dẫn đóng góp
Hướng nghiên cứu
Look at the existing deploy hook `deploy/truenas_ws.sh` to understand the pattern. The new hook should be a pure POSIX sh script placed in the deploy directory. Test by setting up a TrueNAS instance and using acme.sh's deploy function. Ensure it handles WebSocket connections, authentication, and async jobs correctly. Verify it works on FreeBSD's /bin/sh.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- shell
- Lĩnh vực
- cli, cloud, devops
- Loại issue
- Tính năng
- Độ khó
- 3/5
- Thời gian dự kiến
- 1-2 ngày
- Mức độ hoạt động
- Sôi nổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 65/100