Skip to content

Troubleshooting Guide

First checks

sudo systemctl status vnetarmor-core
sudo systemctl status vnetarmor-managerd
vnetarmorctl --server manager01.example.local:9443 status
curl -kI https://www.example.com/health

Core does not start

Check:

  • Invalid server.conf syntax.
  • TLS certificate/key path missing.
  • Port already in use.
  • License activation or heartbeat requirement.
  • File permissions on config and certs.

Traffic gets 403

Check event fields:

  • module
  • rule_id
  • reason
  • client_ip
  • host
  • path

Common causes are L4 allowlist mismatch, GEO block, WAF block, route default action, or trusted proxy misconfiguration.

Traffic gets 429

Check matching rate-limit rule and key. Confirm whether the client IP is being resolved correctly through trusted proxies.

Traffic gets 502 or 503

From the Core host/container, test backend reachability:

curl -kI https://app01.example.local:8443/health

Check backend TLS verification, SNI, health path, DNS, and firewall.

Managerd cannot connect to Core

Check:

  • Core running state.
  • IPC socket path.
  • Socket permissions.
  • Managerd --core-ipc argument.
  • SELinux/AppArmor/container volume mounts.

WebGUI is slow or causes load

Reduce polling intervals, disable unnecessary live tail views, and ensure Managerd has CPU/memory limits and backoff behavior. Use log/event pagination for large datasets.

mTLS failure

Use openssl verify and grpcurl to isolate whether the problem is trust, hostname SAN, client certificate EKU, or firewall connectivity.

GEO filtering problems

Symptom Likely cause Resolution
Country appears as UNKNOWN GEO database missing, wrong path, unsupported format, permissions issue, or lookup miss. Verify geo_db_path, file ownership, permissions, and Core startup logs.
All requests appear from the load balancer country VNetArmor is evaluating the proxy IP instead of the real client IP. Configure trusted proxy CIDRs and approved client IP headers.
Country header is ignored Request did not arrive from a trusted proxy CIDR. Add only approved proxy/load balancer CIDRs; never trust public client-supplied GEO headers.
A valid user is blocked by country policy Strict country block, outdated database, or route-specific wildcard rule. Switch to monitor mode, review rule_id, update GEO database, and refine the policy.
Core reload fails after GEO changes Invalid path, unreadable file, or syntax error in GEO rules. Check Core logs, validate files, and reload again.

For GEO database licensing, update cadence, file locations, and validation commands, see GEO Location Filtering and Database Licensing.