Skip to main content

Agent Issues

Solutions to common problems with the Bloqd agent on managed servers.

Installation Issues​

Installer Fails​

Symptom: Installation script exits with error.

Solutions:

  1. Check prerequisites:

    # Python 3
    python3 --version

    # pip
    pip3 --version

    # systemd
    systemctl --version

  2. Run with verbose output:

    curl -sSL https://bloqd.example.com/api/v1/install | sudo bash -x

  3. Check network connectivity:

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

  4. Install dependencies manually:

    # Debian/Ubuntu
    sudo apt update
    sudo apt install python3 python3-pip python3-venv curl

    # RHEL/CentOS
    sudo yum install python3 python3-pip curl

Invalid Install Token​

Symptom: "Invalid or expired token" error.

Solutions:

  1. Generate new install command from dashboard (Servers → Add Server)

  2. Check token expiry - Tokens expire after 24 hours

  3. Verify URL is correct:

    # Token is embedded in the URL
    curl -sSL "https://bloqd.example.com/api/v1/install?token=YOUR_TOKEN"

Permission Denied​

Symptom: Permission errors during installation.

Solutions:

  1. Run with sudo:

    curl -sSL https://bloqd.example.com/api/v1/install | sudo bash

  2. Check directory permissions:

    sudo mkdir -p /etc/bloqd /var/lib/bloqd
    sudo chmod 755 /etc/bloqd /var/lib/bloqd

Connection Issues​

Agent Can't Connect to Server​

Symptom: Agent logs show connection errors.

Solutions:

  1. Test connectivity:

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

  2. Check DNS resolution:

    nslookup bloqd.example.com
    dig bloqd.example.com

  3. Check firewall:

    # Test outbound HTTPS
    nc -zv bloqd.example.com 443

  4. Check proxy settings:

    env | grep -i proxy

SSL Certificate Verification Failed​

Symptom: SSL/certificate errors in agent logs.

Solutions:

  1. Update CA certificates:

    # Debian/Ubuntu
    sudo apt update && sudo apt install ca-certificates
    sudo update-ca-certificates

    # RHEL/CentOS
    sudo yum update ca-certificates

  2. Test certificate:

    openssl s_client -connect bloqd.example.com:443 -servername bloqd.example.com

  3. Skip verification (not recommended):

    # /etc/bloqd/agent.yaml
    server:
      url: https://bloqd.example.com
      verify_ssl: false

API Key Invalid​

Symptom: 401 Unauthorized errors.

Solutions:

  1. Check agent configuration:

    sudo grep api_key /etc/bloqd/agent.yaml

  2. Regenerate API key:

    • Dashboard → Servers → Select server → Regenerate API Key

  3. Update agent config:

    sudo nano /etc/bloqd/agent.yaml
    # Update api_key value
    sudo systemctl restart bloqd-agent

Service Issues​

Agent Won't Start​

Symptom: Service fails to start.

Solutions:

  1. Check service status:

    sudo systemctl status bloqd-agent

  2. Check logs:

    sudo journalctl -u bloqd-agent -n 100

  3. Verify configuration:

    sudo python3 -c "import yaml; yaml.safe_load(open('/etc/bloqd/agent.yaml'))"

  4. Check Python installation:

    /opt/bloqd/venv/bin/python3 --version
    /opt/bloqd/venv/bin/pip list | grep bloqd

Agent Crashes Repeatedly​

Symptom: Agent keeps restarting.

Solutions:

  1. Check for error patterns:

    sudo journalctl -u bloqd-agent --since "1 hour ago" | grep -i error

  2. Check memory:

    free -m
    ps aux | grep bloqd

  3. Increase restart delay:

    sudo systemctl edit bloqd-agent
    # Add:
    [Service]
    RestartSec=30

Agent High CPU/Memory​

Symptom: Agent using excessive resources.

Solutions:

  1. Check resource usage:

    top -p $(pgrep -f bloqd-agent)

  2. Check log size:

    sudo journalctl --disk-usage
    sudo journalctl --vacuum-size=100M

  3. Reduce heartbeat frequency:

    # /etc/bloqd/agent.yaml
    heartbeat:
      interval: 120  # seconds

Module Issues​

Reporter Not Working​

Symptom: Bans not being reported.

Solutions:

  1. Check fail2ban action:

    sudo cat /etc/fail2ban/action.d/bloqd.conf

  2. Test action manually:

    # Ban an IP
    sudo fail2ban-client set sshd banip 192.168.1.100

    # Check agent logs
    sudo journalctl -u bloqd-agent -f

    # Unban
    sudo fail2ban-client set sshd unbanip 192.168.1.100

  3. Verify reporter module enabled:

    # /etc/bloqd/agent.yaml
    modules:
      reporter:
        enabled: true

Sync Module Fails​

Symptom: Whitelist not syncing.

Solutions:

  1. Check sync status:

    sudo cat /var/lib/bloqd/sync_status.json

  2. Force sync:

    sudo /opt/bloqd/venv/bin/python3 -m bloqd_agent sync --force

  3. Check fail2ban jail.local:

    sudo cat /etc/fail2ban/jail.local | grep ignoreip

  4. Verify write permissions:

    sudo touch /etc/fail2ban/jail.local
    ls -la /etc/fail2ban/jail.local

Metrics Not Reported​

Symptom: Server metrics missing in dashboard.

Solutions:

  1. Enable metrics module:

    # /etc/bloqd/agent.yaml
    modules:
      metrics:
        enabled: true
        interval: 60

  2. Check dependencies:

    /opt/bloqd/venv/bin/pip show psutil

  3. Test metrics collection:

    /opt/bloqd/venv/bin/python3 -c "import psutil; print(psutil.cpu_percent())"

Command Execution Fails​

Symptom: Remote commands from dashboard fail.

Solutions:

  1. Check command module:

    # /etc/bloqd/agent.yaml
    modules:
      commands:
        enabled: true

  2. Check agent permissions:

    # Agent needs sudo access for fail2ban
    sudo -l -U bloqd

  3. Configure sudoers:

    echo "bloqd ALL=(ALL) NOPASSWD: /usr/bin/fail2ban-client" | sudo tee /etc/sudoers.d/bloqd

Fail2ban Integration​

Fail2ban Not Detected​

Symptom: Agent doesn't detect fail2ban.

Solutions:

  1. Check fail2ban status:

    sudo systemctl status fail2ban
    sudo fail2ban-client status

  2. Check fail2ban socket:

    ls -la /var/run/fail2ban/

  3. Verify fail2ban-client path:

    which fail2ban-client

Jail Not Found​

Symptom: Specific jail not showing in dashboard.

Solutions:

  1. List active jails:

    sudo fail2ban-client status

  2. Check jail configuration:

    sudo fail2ban-client status sshd

  3. Enable jail:

    # /etc/fail2ban/jail.local
    [sshd]
    enabled = true

  4. Reload fail2ban:

    sudo fail2ban-client reload

Log Analysis​

View Agent Logs​

# Last 100 lines
sudo journalctl -u bloqd-agent -n 100

# Follow logs
sudo journalctl -u bloqd-agent -f

# Since last boot
sudo journalctl -u bloqd-agent -b

# Filter by priority
sudo journalctl -u bloqd-agent -p err

Enable Debug Logging​

# /etc/bloqd/agent.yaml
logging:
  level: debug
  file: /var/log/bloqd/agent.log
# Restart to apply
sudo systemctl restart bloqd-agent

Common Log Messages​

MessageMeaningAction
Connection refusedCan't reach serverCheck network/firewall
401 UnauthorizedInvalid API keyRegenerate key
SSL certificate verify failedCertificate issueUpdate CA certs
fail2ban not foundfail2ban not installedInstall fail2ban
Permission deniedInsufficient privilegesCheck sudoers

Reinstall Agent​

Complete reinstallation:

# Stop and remove
sudo systemctl stop bloqd-agent
sudo systemctl disable bloqd-agent
sudo rm -rf /opt/bloqd /etc/bloqd /var/lib/bloqd
sudo rm /etc/systemd/system/bloqd-agent.service
sudo systemctl daemon-reload

# Fresh install
curl -sSL "https://bloqd.example.com/api/v1/install?token=NEW_TOKEN" | sudo bash