Skip to main content

OPN003 - OPNsense TLS Certificate Error

Agent error code #OPN003 indicates that the agent could not verify the TLS certificate presented by OPNsense. The TLS handshake failed before any API request could be sent.

This error is distinct from connection refused (#OPN004) or timeout (#OPN002) errors. Error #OPN003 means the network path to OPNsense is working but the certificate is not trusted by the agent.

Common causes include:

  • OPNsense is presenting its default self-signed certificate
  • The certificate is signed by an internal CA that the agent host does not trust
  • The certificate has expired or its validity window has not started
  • The hostname configured in the Knocknoc backend does not match the certificate's Subject or SAN

Steps to Resolve

Install a Trusted Certificate on OPNsense

  1. In the OPNsense web UI, navigate to System > Trust > Certificates
  2. Import or generate a certificate signed by a CA that the agent host trusts (Let's Encrypt is supported by OPNsense via the ACME plugin)
  3. Apply the certificate to the web UI under System > Settings > Administration
  4. Confirm the certificate is valid and the Subject/SAN matches the hostname in the Knocknoc backend

Confirm the Hostname Matches the Certificate

  1. In the Knocknoc backend configuration, confirm the Hostname value uses the name on the certificate (not an IP address, unless the certificate also has an IP SAN)
  2. If you need to use a different hostname, reissue the certificate to include it as a SAN

Use the Insecure Option (Lab Only)

If the OPNsense host genuinely cannot present a trusted certificate (for example, a lab environment), enable Insecure in the Knocknoc backend configuration. This skips TLS verification.

  1. In the Knocknoc admin interface, edit the backend configuration for the affected OPNsense Knoc
  2. Tick the Insecure checkbox and save

Skipping verification means an attacker on the network between the agent and the firewall could intercept the API key/secret. Only use this when the agent and firewall share a trusted segment.

Still Having Issues?

We can help you out, contact us at support@knocknoc.io.

Back to top