Skip to main content

Agent Troubleshooting

Common issues and their solutions for the Bloqd agent.

Diagnostic Commands​

Quick Status Check​

# Check agent service
systemctl status bloqd-agent

# Check fail2ban service
systemctl status fail2ban

# View recent agent logs
journalctl -u bloqd-agent -n 50

# Run agent status command
bloqd-agent --status

# Run health check
bloqd-agent --health-check

# Validate configuration
bloqd-agent --check

Connection Issues​

Agent Not Connecting​

Symptoms: Agent shows as offline in dashboard

Solutions:

  1. Verify server URL in config:

    grep url /etc/bloqd/agent.yaml

  2. Test connectivity:

    curl -v https://bloqd.example.com/api/v1/health

  3. Check firewall:

    # Allow outbound HTTPS
    firewall-cmd --add-port=443/tcp --permanent
    firewall-cmd --reload

  4. Check SSL certificate:

    # For self-signed certs
    server:
      verify_ssl: false

API Authentication Failing​

Symptoms: 401/403 errors in logs

Solutions:

  1. Verify API key:

    grep api_key /etc/bloqd/agent.yaml

  2. Check key is not expired/revoked in dashboard

  3. Regenerate API key in Bloqd Settings → API Keys

Ban Reporting Issues​

Bans Not Appearing in Dashboard​

Solutions:

  1. Check report socket exists:

    ls -la /var/run/bloqd-agent/report.sock

  2. Test helper script:

    /usr/local/bin/bloqd-report 192.0.2.1 sshd "test log"

  3. Verify fail2ban action is installed:

    cat /etc/fail2ban/action.d/bloqd-report.conf

  4. Check jail uses the action:

    grep "action.*bloqd" /etc/fail2ban/jail.d/*.conf

  5. Test with manual ban:

    fail2ban-client set sshd banip 192.0.2.1
    # Check dashboard
    fail2ban-client set sshd unbanip 192.0.2.1

Socket Not Found​

Symptoms: Socket not found in syslog

Solutions:

  1. Ensure agent is running:

    systemctl restart bloqd-agent

  2. Check socket directory permissions:

    ls -la /var/run/bloqd-agent/

  3. Verify reporter module is enabled:

    modules:
      reporter:
        enabled: true

Whitelist Sync Issues​

Whitelist Not Updating​

Solutions:

  1. Force manual sync:

    # From dashboard: Server → Sync Whitelist
    # Or via API

  2. Check sync logs:

    journalctl -u bloqd-agent | grep -i sync

  3. Verify whitelist file:

    cat /etc/fail2ban/bloqd-whitelist.txt

  4. Check API returns data:

    curl -H "Authorization: Bearer API_KEY" \
      https://bloqd.example.com/api/v1/whitelist/plain

IP Still Getting Banned​

Solutions:

  1. Verify IP is in dashboard whitelist

  2. Check local whitelist:

    grep "192.168.1.100" /etc/fail2ban/bloqd-whitelist.txt

  3. Reload fail2ban:

    fail2ban-client reload

  4. Check jail config includes whitelist:

    grep ignoreip /etc/fail2ban/jail.d/00-bloqd-base.conf

Service Issues​

Agent Keeps Crashing​

Solutions:

  1. Check logs for errors:

    journalctl -u bloqd-agent -p err

  2. Run in debug mode:

    bloqd-agent --log-level DEBUG

  3. Check Python version:

    python3 --version  # Requires 3.10+

  4. Reinstall agent package:

    /opt/bloqd-agent/venv/bin/pip install --upgrade --force-reinstall \
      /path/to/bloqd-agent.tar.gz

High Memory/CPU Usage​

Solutions:

  1. Increase intervals:

    modules:
      metrics:
        interval: 600  # 10 minutes
      health:
        interval: 300  # 5 minutes

  2. Disable unused modules:

    modules:
      siem:
        enabled: false

  3. Check for log file growth:

    du -h /var/log/bloqd/

fail2ban Issues​

fail2ban Not Starting​

Solutions:

  1. Check configuration:

    fail2ban-client -t

  2. Check for syntax errors:

    fail2ban-client -vvv start

  3. Review Bloqd jail configs:

    ls -la /etc/fail2ban/jail.d/

  4. Remove problematic jail:

    rm /etc/fail2ban/jail.d/50-problem-jail.conf
    fail2ban-client reload

Jail Not Starting​

Solutions:

  1. Check log file exists:

    ls -la /var/log/nginx/access.log

  2. Verify filter exists:

    ls /etc/fail2ban/filter.d/nginx-*.conf

  3. Test filter:

    fail2ban-regex /var/log/nginx/access.log \
      /etc/fail2ban/filter.d/nginx-botsearch.conf

Installation Issues​

Install Script Fails​

Solutions:

  1. Check install log:

    cat /var/log/bloqd-install.log

  2. Verify root access:

    sudo -v

  3. Check OS compatibility:

    cat /etc/os-release

  4. Install dependencies manually:

    # Debian/Ubuntu
    apt-get install -y python3 python3-pip python3-venv fail2ban curl jq

    # RHEL/CentOS
    dnf install -y epel-release
    dnf install -y python3 python3-pip fail2ban curl jq

Token Expired​

Solutions:

  1. Generate new install command in dashboard
  2. Tokens expire after 24 hours

Log Locations​

LogLocation
Agent log/var/log/bloqd/agent.log
Install log/var/log/bloqd-install.log
Systemd journaljournalctl -u bloqd-agent
fail2ban log/var/log/fail2ban.log
Syslog messages/var/log/syslog or /var/log/messages

Getting Help​

If issues persist:

  1. Collect diagnostic info:

    bloqd-agent --status > /tmp/bloqd-status.txt 2>&1
    journalctl -u bloqd-agent -n 100 >> /tmp/bloqd-status.txt

  2. Check Bloqd documentation

  3. Report issue with:

    • OS version
    • Agent version (bloqd-agent --version)
    • Error messages
    • Diagnostic output