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" /var/log/ndagent.log

Solutions:

1. Update CA certificates:

   pkg update
   pkg upgrade ca_root_nss

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

   date
   ntpdate -q pool.ntp.org

3. 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

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

• Contact support

  • Visit NetDefense Support
  • Include the diagnostic information you gathered
  • Describe the steps to reproduce the issue

• Check known issues

  • Visit the GitHub Issues page
  • Search for similar reports from other users