Skip to content
NetDefense Docs

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.

  1. Navigate to Services > NetDefense > Log File

  2. The log viewer displays real-time 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
    • 📅 Set date/time ranges

Via Command Line

Terminal window
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.

Terminal window
service ndagent status

Expected output when running:

NetDefense Agent is running (pid: 12345)

If stopped:

NetDefense Agent is not running

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:

    Terminal window
    /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:

Terminal window
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:

Terminal window
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:

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

Common registration issues:

ErrorCauseSolution
Invalid tokenToken format incorrectRe-copy token from NetDefense dashboard
Token not foundToken doesn’t exist or expiredGenerate a new token in dashboard
Device limit reachedAccount device quota exceededRemove unused devices or upgrade plan
Already registeredDevice ID used by another deviceClick Reset ID in settings to generate new ID

Connection Drops

Symptoms: The agent connects but frequently disconnects.

Diagnostic steps:

  1. Check for network instability:

    Terminal window
    ping -c 100 hub.netdefense.io

  2. Review logs for disconnect patterns:

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

  3. Check system resources:

    Terminal window
    top -b -n 1 | head -20

Solutions:

  • 🌐 Ensure stable internet connectivity
  • 🔥 Check for firewall rules that might timeout idle connections
  • 🔄 Verify no proxy is interfering with WebSocket connections

SSL Certificate Errors

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

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

Solutions:

  1. Update CA certificates:

    Terminal window
    pkg update
    pkg upgrade ca_root_nss

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

    Terminal window
    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:

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

  2. Clear package cache:

    Terminal window
    pkg clean -a
    pkg update -f

  3. Retry the installation:

    Terminal window
    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:

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

  2. Test repository connectivity:

    Terminal window
    fetch https://repo.netdefense.io/opnsense/meta.conf

  3. Recreate repository configuration if corrupted:

    Terminal window
    cat > /usr/local/etc/pkg/repos/netdefense.conf <<'EOF'
    netdefense: {
      url: "https://repo.netdefense.io/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

Terminal window
ps aux | grep ndagent


top -p $(pgrep ndagent) -n 1

Test Configuration

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

Log Level Reference

LevelWhen to UseInformation Captured
DEBUGTroubleshooting onlyAll details including raw data
INFONormal operationStart/stop, connections, tasks
WARNINGReduced loggingPotential issues only
ERRORMinimal loggingErrors only

Getting Help

If you’re unable to resolve an issue:

  • 📋 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 gathered
    • Describe the steps to reproduce the issue

  • 🐛 Check known issues

    • Visit the GitHub Issues page
    • Search for similar problems reported by other users