Troubleshooting¶
Common issues and their solutions.
Dashboard Not Loading¶
Symptoms¶
- Browser shows "connection refused" or timeout
https://nettap.localdoes not resolve
Diagnosis¶
# Check if the service is running
systemctl status nettap
# Check if containers are running
docker compose -f /opt/nettap/docker/docker-compose.yml ps
# Check the nginx proxy specifically
docker logs nettap-nginx --tail 20
# Check if port 443 is listening
ss -tlnp | grep 443
Solutions¶
| Cause | Solution |
|---|---|
| Service not started | sudo systemctl start nettap |
| Nginx container not running | docker compose -f docker/docker-compose.yml up -d nettap-nginx |
| Port conflict on 443 | Check for other services using port 443: ss -tlnp \| grep 443 |
| mDNS not working | Try the IP address directly: https://192.168.1.100 |
| Avahi not running | sudo systemctl restart avahi-daemon |
OpenSearch Issues¶
"OpenSearch not responding"¶
OpenSearch takes 2--5 minutes to start, especially on first boot when it initializes security indices.
# Check OpenSearch health
curl -sk https://localhost:9200/_cluster/health | python3 -m json.tool
# Check OpenSearch logs
docker logs nettap-opensearch --tail 50
# Check JVM memory
docker stats nettap-opensearch --no-stream
"Cluster health: yellow"¶
Yellow cluster health is normal and expected for a single-node deployment. It means all primary shards are assigned, but replicas cannot be allocated (because there is only one node). This does not affect functionality.
OpenSearch Out of Memory (OOM)¶
If OpenSearch is killed by the OOM killer:
Solution: Reduce the JVM heap size or add more RAM:
Then restart: sudo systemctl restart nettap
vm.max_map_count Error¶
OpenSearch requires vm.max_map_count >= 262144. If you see:
Solution:
sudo sysctl -w vm.max_map_count=262144
echo "vm.max_map_count = 262144" | sudo tee /etc/sysctl.d/99-nettap.conf
Bridge Issues¶
Traffic Not Passing Through¶
# Validate the bridge
sudo scripts/bridge/setup-bridge.sh --validate-only
# Check bridge status
ip link show br0
bridge link show
# Check that interfaces are attached
ip link show eth0 | grep master
ip link show eth1 | grep master
Bridge Validation Failures¶
| Issue | Cause | Solution |
|---|---|---|
| Bridge not found | Bridge was not created | Re-run: sudo scripts/bridge/setup-bridge.sh --wan eth0 --lan eth1 |
| Interface not attached | NIC removed from bridge | Re-run bridge setup |
| STP enabled | STP should be off for inline tap | ip link set br0 type bridge stp_state 0 |
| Forward delay non-zero | Should be 0 for inline tap | ip link set br0 type bridge forward_delay 0 |
| Promiscuous mode off | Required for packet capture | ip link set eth0 promisc on; ip link set eth1 promisc on |
Bridge Lost After Reboot¶
If the bridge does not persist across reboots, the netplan configuration may be missing:
# Check for netplan config
cat /etc/netplan/10-nettap-bridge.yaml
# If missing, re-run with persistence
sudo scripts/bridge/setup-bridge.sh --wan eth0 --lan eth1 --persist
Tearing Down the Bridge¶
If you need to remove the bridge and restore normal networking:
This removes the bridge, restores interfaces, and cleans up persistence files.
Container Issues¶
Containers Failing to Start¶
# Check which containers are unhealthy or restarting
docker compose -f /opt/nettap/docker/docker-compose.yml ps
# Check logs for a specific container
docker logs nettap-opensearch --tail 50
docker logs nettap-zeek-live --tail 50
docker logs nettap-suricata-live --tail 50
Zeek or Suricata Not Capturing¶
# Check if br0 exists and is up
ip link show br0
# Check if capture containers can see the interface
docker exec nettap-zeek-live ip link show
# Check Zeek logs
docker logs nettap-zeek-live --tail 30
# Check Suricata stats
docker logs nettap-suricata-live --tail 30
Tip
Zeek and Suricata run with network_mode: host so they can access the bridge interface directly. If the bridge is not set up, they will fail to start capture.
Restarting Individual Containers¶
# Restart a specific container
docker compose -f /opt/nettap/docker/docker-compose.yml restart zeek-live
# Restart the whole stack
sudo systemctl restart nettap
No Data in Dashboard¶
Symptoms¶
- Dashboard shows "--" for all values
- "No traffic data available" messages
Diagnosis¶
-
Check that containers are running:
-
Check that OpenSearch has indices:
-
Check that the daemon API is reachable:
-
Check Zeek log output:
Common Causes¶
| Cause | Solution |
|---|---|
| Bridge not set up | Run bridge setup script |
| No traffic on bridge | Verify cables are connected to WAN and LAN ports |
| OpenSearch still starting | Wait 5 minutes for initial startup |
| Filebeat not shipping logs | Check docker logs nettap-filebeat |
| Logstash pipeline error | Check docker logs nettap-logstash |
| Daemon not running | Check docker logs nettap-storage-daemon |
Daemon API Issues¶
"Unable to reach the monitoring daemon"¶
This warning banner appears on the dashboard when the web UI cannot reach the storage daemon API.
# Check daemon container
docker logs nettap-storage-daemon --tail 30
# Test API directly
curl http://localhost:8880/api/health
API Returns Errors¶
Performance Issues¶
High CPU Usage¶
# Check which containers use the most CPU
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"
Common CPU hogs:
- Suricata under heavy traffic --- normal, scales with traffic volume
- OpenSearch during indexing --- normal, especially after startup
- Logstash during log enrichment --- reduce
pipeline.workersif needed
High Memory Usage¶
# Check memory per container
docker stats --no-stream --format "table {{.Name}}\t{{.MemUsage}}\t{{.MemPerc}}"
If memory is tight, reduce OpenSearch and Logstash heap sizes. See Performance Tuning.
Disk Space Running Low¶
# Check disk usage
df -h /
# Check Docker disk usage
docker system df
# Clean up unused Docker resources
docker system prune --volumes
Warning
docker system prune --volumes removes all unused volumes, including any data not associated with a running container. Make sure all your containers are running before pruning.
Getting Help¶
If these troubleshooting steps do not resolve your issue:
-
Collect diagnostic information:
-
Open a GitHub Issue with the diagnostic output.
-
Join the Discord community for real-time help.