Troubleshooting

Agent Cannot Reach Gateway

# Test UDP connectivity
nc -u -v gateway.avon.example.com 4600

# Check DNS resolution
dig gateway.avon.example.com

# Run agent with debug logging
sudo avon-agent run --log-level debug

Firewall Configuration

Linux:

sudo ufw allow out 4600/udp

macOS:

sudo /usr/libexec/ApplicationFirewall/socketfilterfw 
  --add /usr/local/bin/avon-agent

Windows (PowerShell as Admin):

New-NetFirewallRule -DisplayName "AVON Agent" `
  -Direction Outbound -Protocol UDP -LocalPort 4600 -Action Allow

TUN Device Issues

Linux:

lsmod | grep tun
sudo modprobe tun
echo "tun" | sudo tee /etc/modules-load.d/tun.conf

macOS: Open System Settings > Privacy & Security and approve the AVON system extension.

Windows: Reinstall the TAP driver from C:\Program Files\AVON\tap-installer.exe.

Certificate Issues

# Check certificate validity
avon-agent cert info

# Re-enroll with a new token
sudo avon-agent enroll --force 
  --gateway gateway.avon.example.com:4600 
  --token "NEW_TOKEN"

Diagnostic Commands

# Full diagnostic report
avon-agent diagnostics

# Network connectivity test
avon-agent diagnostics --network

# Validate configuration
avon-agent config validate

# Export debug bundle for support
avon-agent diagnostics --export /tmp/avon-debug.zip

Kubernetes Troubleshooting

Pods stuck in Pending:

kubectl describe pod <pod-name> -n avon

Database connectivity:

kubectl run -it --rm debug --image=postgres:16 -n avon -- 
  psql -h avon-postgresql -U avon -d avon -c "SELECT 1"

Gateway not getting external IP:

kubectl describe svc avon-gateway -n avon

For on-premise deployments, verify MetalLB is configured and an IP address pool is available.

Log Locations