Skip to main content

Add Your First Server

After setting up the Bloqd dashboard, you'll want to connect servers for fail2ban management. This guide walks you through adding your first server.

Prerequisites​

On the target server, ensure you have:

  • Root or sudo access
  • Python 3.10 or higher
  • fail2ban installed (or the installer will install it)
  • Outbound HTTPS access to your Bloqd server

Step 1: Generate Install Token​

In the Bloqd dashboard:

  1. Navigate to Servers in the sidebar
  2. Click Add Server
  3. Fill in the server details:
    • Server Name: A friendly name (e.g., "web-prod-01")
    • Jails: Select which jails to enable

For a typical web server:

  • sshd - Protect SSH from brute force (always recommended)
  • nginx-http-auth - If using HTTP Basic Auth
  • nginx-botsearch - Block scanners hitting 404s

For a mail server:

  • sshd
  • postfix
  • postfix-sasl
  • dovecot
  1. Click Generate Install Command

You'll see a command like:

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

Install tokens expire after 24 hours. Generate a new one if needed.

Step 2: Run the Installer​

SSH into your target server and run the generated command:

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

The installer will:

  1. Detect your OS - Supports Debian, Ubuntu, RHEL, Rocky, AlmaLinux, CentOS, Fedora
  2. Install dependencies - Python 3, fail2ban, curl, jq
  3. Download the agent - Python-based Bloqd agent
  4. Configure fail2ban - Set up selected jails with Bloqd integration
  5. Create systemd service - bloqd-agent.service
  6. Start the agent - Begin syncing with Bloqd

Installation Output​

[INFO] Bloqd Agent Installer
[INFO] Detected OS: ubuntu 22.04
[INFO] Installing dependencies...
[INFO] Downloading Bloqd agent...
[INFO] Configuring fail2ban...
[INFO] Creating systemd service...
[INFO] Starting bloqd-agent service...
[SUCCESS] Installation complete!

Server registered successfully.
Agent status: running

Step 3: Verify Connection​

After installation, verify the server is connected:

In the Dashboard​

  1. Go to Servers
  2. Your server should appear with a green status indicator
  3. Click on the server to see details

On the Target Server​

Check the agent status:

systemctl status bloqd-agent

Expected output:

● bloqd-agent.service - Bloqd Agent
     Loaded: loaded (/etc/systemd/system/bloqd-agent.service; enabled)
     Active: active (running) since ...

View agent logs:

journalctl -u bloqd-agent -f

Check fail2ban status:

fail2ban-client status

Step 4: Test the Integration​

Generate a Test Ban​

To verify everything works, trigger a test ban (be careful not to lock yourself out!):

# From a different IP, make failed SSH attempts
ssh invalid-user@your-server

After a few failed attempts, check:

  1. fail2ban: fail2ban-client status sshd
  2. Bloqd Dashboard: The ban should appear in the live feed

Verify Whitelist Sync​

Add an IP to the whitelist in Bloqd:

  1. Go to Whitelist → Add Entry
  2. Enter an IP address
  3. Click Add

On the target server:

cat /etc/fail2ban/bloqd-whitelist.txt

The IP should appear within 60 seconds (default sync interval).

Agent Configuration​

The agent configuration is stored at /etc/bloqd/agent.yaml:

/etc/bloqd/agent.yaml
server:
  url: "https://bloqd.example.com"
  api_key: "f2b_xxxxx"

agent:
  hostname: "web-prod-01"
  log_level: "INFO"

modules:
  sync:
    enabled: true
    interval: 300  # seconds

  reporter:
    enabled: true

  metrics:
    enabled: true

  health:
    enabled: true

  commands:
    enabled: true
    poll_interval: 30

See Agent Configuration for all options.

Troubleshooting​

Server Shows "Offline"​

  1. Check agent status:

    systemctl status bloqd-agent

  2. Check agent logs:

    journalctl -u bloqd-agent --since "5 minutes ago"

  3. Test connectivity:

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

Agent Won't Start​

Check for configuration errors:

cat /etc/bloqd/agent.yaml

Verify Python version:

python3 --version  # Must be 3.10+

Bans Not Appearing​

  1. Check fail2ban is running:

    systemctl status fail2ban

  2. Check jail is enabled:

    fail2ban-client status sshd

  3. Check the reporter module logs:

    journalctl -u bloqd-agent | grep reporter

Whitelist Not Syncing​

  1. Check sync module is enabled in agent.yaml

  2. Verify the whitelist file exists:

    ls -la /etc/fail2ban/bloqd-whitelist.txt

  3. Check file permissions

For more help, see Agent Troubleshooting.

Next Steps​