Troubleshooting

This guide helps you diagnose and resolve common issues with the NetDefense plugin.

Viewing Logs

The first step in troubleshooting is always to check the logs. NetDefense provides an integrated log viewer in the OPNsense web interface.

Via Web Interface (Recommended)

1. Navigate to Services > NetDefense > Log File

2. The log viewer shows live agent activity, including:

   • Service start/stop events
   • Registration attempts and status
   • Server connection events
   • Task execution results
   • Errors and warnings

3. Use the filter options to narrow down specific events:

   • Filter by log level (DEBUG, INFO, WARNING, ERROR)
   • Search for specific keywords
   • Restrict by date/time range

Tip

Set the Log Level to DEBUG in Services > NetDefense > Settings for more detailed diagnostic information. Remember to set it back to INFO after troubleshooting.

Via Command Line

tail -f /var/log/ndagent.log

tail -100 /var/log/ndagent.log

grep -i error /var/log/ndagent.log

grep ndagent /var/log/messages

Common Issues

Service Won’t Start

Symptoms: The NetDefense agent fails to start after enabling it.

Check Status

service ndagent status

Expected output when running:

NetDefense Agent is running (pid: 12345)

If stopped:

NetDefense Agent is not running

Check Configuration

ls -la /usr/local/etc/ndagent.conf

cat /usr/local/etc/ndagent.conf

Confirm:

• enabled=true is present
• token= holds a valid UUID
• server_address= points to a valid URL

Solutions:

1. Missing or invalid token: Navigate to Services > NetDefense > Settings and verify the Registration Token is correctly entered

2. Configuration not applied: Click Apply on the settings page to regenerate the configuration

3. Manual start for diagnostics:

   /usr/local/bin/ndagent --config /usr/local/etc/ndagent.conf

   This runs the agent in the foreground and displays any errors directly.

Device Shows Offline

Symptoms: The device appears offline in your NetDefense dashboard even though the agent is running.

Possible causes and solutions:

Network Connectivity

Verify the device can reach the NetDefense server:

fetch -o /dev/null https://hub.netdefense.io

Firewall Rules

Ensure outbound HTTPS (port 443) is allowed to NetDefense servers.

DNS Resolution

Verify DNS is resolving:

host hub.netdefense.io

SSL Issues

Temporarily disable SSL verification in settings to test if certificates are the issue.

Registration Failed

Symptoms: Logs show registration failures or “PENDING” status that doesn’t resolve.

Check the logs for specific errors:

grep -i "registration\|pending\|token" /var/log/ndagent.log

Common registration issues:

Error	Cause	Solution
Invalid token	Token format incorrect	Re-copy token from NetDefense dashboard
Token not found	Token doesn’t exist or expired	Generate a new token in dashboard
Device limit reached	Account device quota exceeded	Remove unused devices or upgrade plan
Already registered	Device ID used by another device	Click Reset ID in settings to generate new ID

Connection Drops

Symptoms: The agent connects but frequently disconnects.

Diagnostic steps:

1. Check for network instability:

   ping -c 100 hub.netdefense.io

2. Review logs for disconnect patterns:

   grep -i "disconnect\|connection\|websocket" /var/log/ndagent.log

3. Check system resources:

   top -b -n 1 | head -20

Solutions:

• Confirm the device has stable internet connectivity
• Check for firewall rules that may time out idle connections
• Make sure no proxy is interfering with the WebSocket connection

SSL Certificate Errors

Symptoms: Logs show SSL/TLS errors or certificate verification failures.

grep -i "ssl\|certificate\|tls\|extra_ca_file" /var/log/ndagent.log

From agent 1.21.0, the agent checks NetDefense’s certificate against root certificates built into the agent, not the firewall’s certificate store, so updating the firewall’s CA bundle doesn’t change what it trusts.

Solutions:

1. Behind a TLS-inspection proxy: an error naming extra_ca_file means the certificate the agent was shown isn’t signed by a root it trusts. Its presented_issuer field names the issuer of the topmost certificate in the chain the agent was shown, which behind an inspection proxy is the proxy’s CA. Add that CA in Extra CA File.

2. Check system time: SSL verification requires accurate system time

   date
   ntpdate -q pool.ntp.org

3. On an agent older than 1.21.0, update CA certificates:

   pkg update
   pkg upgrade ca_root_nss

4. Temporary workaround: Disable SSL verification in settings (not recommended for production)

Package Signature Verification Failed

Symptoms: Package installation fails with signature verification errors.

pkg: signature verification failed

Solutions:

1. Update the fingerprint file:

   fetch -o /usr/local/etc/pkg/fingerprints/netdefense/trusted/netdefense \
     https://repo.netdefense.io/prod/opnsense/fingerprints/netdefense/trusted/netdefense

2. Clear package cache:

   pkg clean -a
   pkg update -f

3. Retry the installation:

   pkg install os-netdefense

Repository Not Found

Symptoms: Package manager cannot find the NetDefense repository.

pkg: repository netdefense has no meta file

Solutions:

1. Verify repository configuration:

   cat /usr/local/etc/pkg/repos/netdefense.conf

2. Test repository connectivity:

   fetch https://repo.netdefense.io/prod/opnsense/meta.conf

3. Recreate repository configuration if corrupted:

   cat > /usr/local/etc/pkg/repos/netdefense.conf <<'EOF'
   netdefense: {
     url: "https://repo.netdefense.io/prod/opnsense",
     signature_type: "fingerprints",
     fingerprints: "/usr/local/etc/pkg/fingerprints/netdefense",
     enabled: yes,
     priority: 10
   }
   EOF
   pkg update -f

A Firmware Track Step Is Held or Failed

Symptoms: A device in a firmware track isn’t updating, a step shows a hold reason such as held_check_failed, or the Flavour setting under System > Firmware > Settings keeps coming back after you reset it.

Solutions:

1. See what NetDefense recorded for the device:

   ndcli firmware status --name <device>
   ndcli firmware history <device>

2. Read the agent’s log under Services > NetDefense > Log File. Lines about the firmware pin start with Firmware flavour written, The firmware pin needs to be written again, or The pinned release folder is not on the device's mirror.

3. Look the reason up in Troubleshooting. A held step changed nothing, and the track’s next window tries again.

4. To take the device out of its track, move it to Unmanaged in NetDefense. Resetting the Flavour on the firewall doesn’t release it: the agent puts the pin back. See Firmware tracks on the firewall.

Diagnostic Commands

Quick Health Check

#!/bin/sh
echo "=== NetDefense Health Check ==="

echo "\n--- Package Status ---"
pkg info os-netdefense 2>/dev/null || echo "Package not installed"

echo "\n--- Service Status ---"
service ndagent status

echo "\n--- Configuration ---"
if [ -f /usr/local/etc/ndagent.conf ]; then
    echo "Config file exists"
    grep "enabled=" /usr/local/etc/ndagent.conf
else
    echo "Config file NOT found"
fi

echo "\n--- Network Connectivity ---"
fetch -q -o /dev/null https://hub.netdefense.io && echo "Server reachable" || echo "Server NOT reachable"

echo "\n--- Recent Errors ---"
grep -i error /var/log/ndagent.log 2>/dev/null | tail -5 || echo "No errors or log file not found"

View Service Process

ps aux | grep ndagent

top -p $(pgrep ndagent) -n 1

Test Configuration

/usr/local/bin/ndagent --config /usr/local/etc/ndagent.conf --validate

Log Level Reference

Level	When to Use	Information Captured
DEBUG	Troubleshooting only	All details including raw data
INFO	Normal operation	Start/stop, connections, tasks
WARNING	Reduced logging	Potential issues only
ERROR	Minimal logging	Errors only

Note

DEBUG level can generate significant log volume. Only enable temporarily for troubleshooting and remember to reset to INFO afterward.

Getting Help

If you can’t resolve an issue on your own:

• Gather diagnostic information

  • Run the health check script above
  • Export recent logs from the web interface
  • Note the OPNsense version and NetDefense plugin version

• Open a support ticket

  • In the web app, open your avatar menu, choose Support, then New ticket; or run ndcli support create (see Support)
  • Describe the steps to reproduce the issue and attach the diagnostic information you gathered
  • Only your organization and NetDefense Support can read the ticket

• Ask in the Community

  • Search the NetDefense Community discussions for similar reports
  • If none matches, start a discussion with the diagnostic information you gathered and the steps to reproduce the issue
  • Discussions are public: leave out tokens, keys, passwords and anything else you wouldn’t publish