Agent Installation

The Bloqd agent can be installed automatically via the dashboard or manually.

Automatic Installation (Recommended)

The easiest way to install the agent is through the Bloqd dashboard.

Steps

1. Log in to your Bloqd dashboard
2. Go to Servers → Add Server
3. Enter a server name
4. Select jails to enable
5. Configure jail settings (optional)
6. Click Generate Install Command
7. Copy the command and run it on your target server:

curl -sSL https://bloqd.example.com/api/v1/installer/script/inst_xxx | sudo bash

Or using wget:

wget -qO- https://bloqd.example.com/api/v1/installer/script/inst_xxx | sudo bash

What the Installer Does

1. Checks root privileges
2. Detects OS (Debian/Ubuntu or RHEL/CentOS)
3. Installs dependencies (fail2ban, Python 3, jq, netcat)
4. Creates directories
5. Downloads and installs agent package
6. Creates configuration file
7. Installs systemd service
8. Installs fail2ban action
9. Configures selected jails
10. Starts services

Install Token

The install token in the URL:

• Is valid for 24 hours
• Contains embedded API key and configuration
• Can be used multiple times (for retry on failure)
• Is invalidated after successful registration

Manual Installation

For environments where automatic installation isn't possible.

Prerequisites

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

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

Install Steps

1. Create directories:

mkdir -p /opt/bloqd-agent
mkdir -p /etc/bloqd
mkdir -p /var/log/bloqd
mkdir -p /var/run/bloqd-agent

2. Create virtual environment:

python3 -m venv /opt/bloqd-agent/venv
source /opt/bloqd-agent/venv/bin/activate
pip install --upgrade pip

3. Download agent package:

curl -sSL -H "Authorization: Bearer YOUR_API_KEY" \
  https://bloqd.example.com/api/v1/agent/package \
  -o /tmp/bloqd-agent.tar.gz

pip install /tmp/bloqd-agent.tar.gz

4. Create symlink:

ln -sf /opt/bloqd-agent/venv/bin/bloqd-agent /usr/local/bin/bloqd-agent

5. Create configuration (/etc/bloqd/agent.yaml):

server:
  url: "https://bloqd.example.com"
  api_key: "YOUR_API_KEY"
  websocket: true
  verify_ssl: true

agent:
  hostname: "your-server-name"
  log_level: "INFO"
  log_file: "/var/log/bloqd/agent.log"
  pid_file: "/var/run/bloqd-agent/agent.pid"

modules:
  sync:
    enabled: true
    interval: 300
  reporter:
    enabled: true
  metrics:
    enabled: true
    interval: 300
  health:
    enabled: true
    interval: 60
  commands:
    enabled: true
    poll_interval: 30

6. Set permissions:

chmod 600 /etc/bloqd/agent.yaml

7. Create systemd service (/etc/systemd/system/bloqd-agent.service):

[Unit]
Description=Bloqd Security Agent
After=network-online.target fail2ban.service
Wants=network-online.target fail2ban.service

[Service]
Type=simple
User=root
Group=root
ExecStart=/usr/local/bin/bloqd-agent --config /etc/bloqd/agent.yaml
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
Environment=PYTHONUNBUFFERED=1
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

8. Install fail2ban action (/etc/fail2ban/action.d/bloqd-report.conf):

[Definition]
actionstart =
actionstop =
actioncheck =
actionban = /usr/local/bin/bloqd-report "<ip>" "<name>" "<matches>"
actionunban =
actionban_on_restore =

[Init]

9. Create report helper (/usr/local/bin/bloqd-report):

#!/bin/sh
SOCKET_PATH="/var/run/bloqd-agent/report.sock"
IP="$1"
JAIL="$2"
MATCHES="$3"

if [ -z "$IP" ] || [ -z "$JAIL" ]; then
    exit 1
fi

if [ ! -S "$SOCKET_PATH" ]; then
    exit 1
fi

printf '%s %s %s' "$IP" "$JAIL" "$MATCHES" | nc -U "$SOCKET_PATH" -w 2

chmod +x /usr/local/bin/bloqd-report

10. Start services:

systemctl daemon-reload
systemctl enable bloqd-agent
systemctl start bloqd-agent
systemctl restart fail2ban

Verifying Installation

Check Agent Status

# Service status
systemctl status bloqd-agent

# Agent logs
journalctl -u bloqd-agent -f

# Agent status command
bloqd-agent --status

Check fail2ban

# fail2ban status
fail2ban-client status

# Check jails
fail2ban-client status sshd

Test Ban Reporting

# Manually trigger a test ban (be careful!)
fail2ban-client set sshd banip 192.0.2.1

# Check Bloqd dashboard for the ban
# Then unban:
fail2ban-client set sshd unbanip 192.0.2.1

Uninstalling

Using Agent Command

sudo bloqd-agent --uninstall

Manual Uninstall

# Stop and disable service
systemctl stop bloqd-agent
systemctl disable bloqd-agent

# Remove files
rm -f /etc/systemd/system/bloqd-agent.service
rm -f /usr/local/bin/bloqd-agent
rm -f /usr/local/bin/bloqd-report
rm -f /etc/fail2ban/action.d/bloqd-report.conf
rm -rf /opt/bloqd-agent
rm -rf /etc/bloqd
rm -rf /var/log/bloqd
rm -rf /var/run/bloqd-agent

# Reload systemd
systemctl daemon-reload

note

Uninstalling the agent does not remove fail2ban or its jails. Your server continues to be protected by fail2ban, just without central management.