Skip to main content

OPN005 - Cannot Resolve OPNsense Hostname

Agent error code #207005#OPN005 indicates that the agent host could not resolve the OPNsense hostname to an IP address. The request failed before any network connection was attempted.

This error is distinct from connection refused (#207004)#OPN004) and timeout (#207002)#OPN002), which both require name resolution to succeed first. Error #207005#OPN005 means the agent never got far enough to dial the firewall.

Common causes include:

  • The hostname in the Knocknoc backend is misspelled
  • The agent host's resolver does not know about an internal-only DNS name
  • The DNS server the agent uses is unreachable or returning failures
  • A recent DNS change has not yet propagated

Steps to Resolve

Verify the Hostname

  1. In the Knocknoc admin interface, check the Hostname value in the backend configuration
  2. Confirm it matches the name you use to log into OPNsense from a browser
  3. If you use an IP address to access the web UI, enter the IP address (with the https:// scheme) in the Knocknoc backend instead

Test DNS Resolution From the Agent Host

  1. From the agent host, run nslookup <hostname> or dig <hostname>
  2. If the lookup fails, the agent host's resolver configuration needs investigation
  3. If the lookup succeeds but returns the wrong IP, check for stale records or split-horizon DNS issues

Use a Hosts File Entry as a Workaround

If the hostname cannot be resolved through DNS but the IP is known, add an entry to the agent host's /etc/hosts (Linux/macOS) or C:\Windows\System32\drivers\etc\hosts (Windows) file to map the hostname to the correct IP.

Still Having Issues?

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

Back to top