acmesh-official / acmesh-official/acme.sh

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

Đang mở
#7,206 5 bình luận 1 reaction 0 người được giao Xem trên GitHub
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

Mở 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

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.