security/acme-client: new TrueNAS deploy hook (WebSocket, no midclt)
@fraenki is already working on this.
Since Sep 7, 2026.
- Dominant language
- PHP
- Stars
- 1.2k
- Forks
- 863
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 10
Description
Important notices
- I have read the contributing guidelines at https://github.com/opnsense/plugins/blob/master/CONTRIBUTING.md
- I have searched the existing issues, open and closed, and I'm convinced that mine is new.
- The title contains the plugin to which this issue belongs.
Context
The existing "Upload certificate to TrueNAS Server" automation (AcmeTruenasWs.php) calls the acme.sh truenas_ws deploy hook, which talks to TrueNAS's WebSocket JSON-RPC API using midclt.
midclt requires the truenas_api_client Python package, which is TrueNAS-specific tooling, it isn't available on OPNsense (FreeBSD), so this automation cannot work when deploying from OPNsense to a remote TrueNAS host, only when acme.sh runs directly on the TrueNAS box itself.
The older REST-based truenas hook has a separate problem: TrueNAS's REST API was deprecated in 25.04 and removed entirely in TrueNAS 26, so that hook is now broken as well, regardless of platform.
What I'm working on
I've written a new acme.sh deploy hook, truenas_ws_websocat, that talks to the same WebSocket JSON-RPC API but uses websocat instead of midclt/Python.
websocat is a small, standalone binary (no runtime dependencies beyond what's already needed for TLS), and, importantly for this issue, it's already packaged upstream as www/websocat in the FreeBSD ports tree.
I've tested the hook successfully end-to-end against TrueNAS SCALE 25.10.6 (certificate import, Web UI certificate reassignment + restart, cleanup of the previous certificate), running it from OPNsense against a remote TrueNAS host, keeping a single persistent WebSocket connection open for the whole deployment and correctly polling core.get_jobs for the asynchronous certificate.create/certificate.delete calls.
I've opened a discussion with the acme.sh maintainers about contributing this as a new deploy hook upstream (referencing their existing open issue about the REST hook being broken). Assuming that goes forward, I'd like to also contribute a companion automation class here (e.g. AcmeTruenasWsWebsocat.php, modeled on the existing AcmeTruenasWs.php) so it's usable directly from the ACME Client automation screen, the same way the existing TrueNAS automations are.
The packaging question
This is where I need guidance, since I'm not familiar with how pkg.opnsense.org is built. Running pkg install websocat on a stock OPNsense install currently returns:
pkg: No packages available to install matching 'websocat' have been found in the repositories
From what I understand of the docs (Development Workflow page), your package repository only builds and publishes ports that are actually required as a dependency somewhere in the OPNsense package graph, it isn't a full mirror of the FreeBSD ports tree, even though the underlying port definitions (including www/websocat) exist there.
So, before going further with the PHP/XML side of things, I wanted to ask:
- Would simply adding
RUN_DEPENDS+= websocat:www/websocattosecurity/acme-client/Makefilebe enough forwebsocatto get built and published as part of a future plugin release, the same wayjqpresumably became available through a similar dependency declaration ? - Or is there an extra step / approval needed to introduce a package that isn't currently used by anything in the OPNsense ecosystem ?
- Is
www/websocatstill present and buildable inopnsense/portsas-is, or would it need attention there first ?
I'd rather confirm this is workable before investing time in the PHP/XML automation class, since the whole feature depends on the binary being available.
Happy to test/build locally against opnsense/tools if that's the best way to verify this myself and pointers are welcome, since this would be my first contribution to this repository.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.