Skip to content
local-cert
Browse the documentation

Other systems

Two recipes cover everything that has no guide of its own: a generic ACME client when the system accepts one, and local-cert's API when it can only import a certificate.

Recognizing the right case

The system…Recipe
has an ACME client with a custom CA URL, EAB and HTTP-01configure it with the three values of the EAB credential, as in ACME server
gives shell accessacme.sh and a deploy hook — see certbot, acme.sh, lego
can only import a certificate, or only does DNS-01local-cert's API, below

Pointers by system

SystemApproach
OPNsenseos-acme-client plugin: create an account on a custom CA with the directory URL and the EAB fields, then a certificate using the HTTP-01 challenge. The plugin is built on acme.sh.
pfSenseACME package: if your version offers a custom ACME server with EAB, follow the same approach. Otherwise, run acme.sh from a shell and import the result in System → Certificates.
TrueNASIts ACME client only does DNS-01 with its own providers: use local-cert's API, then import the certificate.
Unraid, UniFi, printers, iDRAC/iLO, network equipmentCertificate import: local-cert's API.
Zoraxy, SWAG, proxies based on lego or certbotIf they expose the CA URL and EAB, generic case. Otherwise, import.
Envoy, proxies without an ACME clientacme.sh or lego alongside, files mounted into the proxy, reload in a hook.

API recipe: local-cert keeps the key and renews

Here the target system doesn't talk to local-cert. local-cert generates the key, obtains the certificate and renews it, and a script fetches the current version. You need an API key (Keys & access) with the cert:issue, cert:read and cert:export permissions on the domain.

1. Request the certificate, once

curl
curl -X POST https://certs.example.com/api/v1/certificates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'content-type: application/json' \
  -d '{"domains": ["nas.home.example.com"], "key_type": "ec-256", "auto_renew": true}'
# → { "id": "cert_…", "status": "pending", … }

2. Fetch certificate and key, on every run

scheduled script (cron, daily)
#!/bin/sh
set -eu
ID=cert_XXXXXXXXXXXXXXXX
OUT=/etc/ssl/local-cert

curl -fsS -H "Authorization: Bearer $TOKEN" \
  "https://certs.example.com/api/v1/certificates/$ID/bundle?format=pem&include=fullchain" \
  -o "$OUT/fullchain.pem.new"
curl -fsS -H "Authorization: Bearer $TOKEN" \
  "https://certs.example.com/api/v1/certificates/$ID/bundle?format=pem&include=key" \
  -o "$OUT/privkey.pem.new"

# only reload if the certificate changed
if ! cmp -s "$OUT/fullchain.pem.new" "$OUT/fullchain.pem"; then
  mv "$OUT/fullchain.pem.new" "$OUT/fullchain.pem"
  mv "$OUT/privkey.pem.new"  "$OUT/privkey.pem"
  # here: the target system's import or reload command
fi

Instead of polling every day, the request accepts a webhook_url that is called on every issuance and renewal. The routes are detailed in API.