opnsense / opnsense/plugins

security/acme-client: new TrueNAS deploy hook (WebSocket, no midclt)

Open
#5,660 6 comments 0 reactions 1 assignee View on GitHub

@fraenki is already working on this.

Since Sep 7, 2026.

upstream
Dominant language
PHP
Stars
1.2k
Forks
863
Avg merge
2d 6h
Merged PRs (30d)
10

Description

Important notices
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:

  1. Would simply adding RUN_DEPENDS+= websocat:www/websocat to security/acme-client/Makefile be enough for websocat to get built and published as part of a future plugin release, the same way jq presumably became available through a similar dependency declaration ?
  2. Or is there an extra step / approval needed to introduce a package that isn't currently used by anything in the OPNsense ecosystem ?
  3. Is www/websocat still present and buildable in opnsense/ports as-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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.