Sync Module

The sync module downloads the global whitelist from the Bloqd server and updates the local fail2ban configuration.

How It Works

1. Agent downloads whitelist from server via API
2. Compares hash with previous version
3. If changed, writes to local whitelist file
4. Optionally reloads fail2ban to apply changes

┌─────────────────┐     GET /api/v1/whitelist/plain     ┌─────────────────┐
│                 │◄───────────────────────────────────│                 │
│  Bloqd Server   │                                    │   Sync Module   │
│                 │────────────────────────────────────►│                 │
└─────────────────┘         Whitelist content          └─────────────────┘
                                                               │
                                                               ▼
                                               ┌───────────────────────────┐
                                               │ /etc/fail2ban/            │
                                               │   bloqd-whitelist.txt     │
                                               └───────────────────────────┘

Configuration

modules:
  sync:
    enabled: true
    interval: 300  # 5 minutes
    whitelist_path: "/etc/fail2ban/bloqd-whitelist.txt"
    reload_on_change: true

Setting	Description	Default
enabled	Enable the sync module	true
interval	Sync interval in seconds	300 (5 min)
whitelist_path	Path to whitelist file	/etc/fail2ban/bloqd-whitelist.txt
reload_on_change	Reload fail2ban when whitelist changes	true

Whitelist File Format

The whitelist file is plain text with one IP/CIDR per line:

# Bloqd whitelist - managed by agent
# Last sync: 2024-01-15T10:30:00Z
192.168.1.100
10.0.0.0/8
2001:db8::/32

fail2ban Integration

The whitelist is referenced in the fail2ban base configuration:

# /etc/fail2ban/jail.d/00-bloqd-base.conf
[DEFAULT]
ignoreip = 127.0.0.1/8 ::1 /etc/fail2ban/bloqd-whitelist.txt

fail2ban automatically reads IPs from the file path when processing bans.

Events

The sync module emits and subscribes to events:

Event	Direction	Description
sync_start	Emits	Sync process started
sync_complete	Emits	Sync finished (success/fail/unchanged)
sync_requested	Subscribes	Manual sync trigger

Triggering Manual Sync

Via Dashboard

1. Go to server detail page
2. Click Sync Whitelist action
3. Agent receives command and syncs immediately

Via API

# Queue sync command
curl -X POST "https://bloqd.example.com/api/v1/commands" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_id": 1, "command_type": "whitelist_sync"}'

Via Agent Event

The commands module can trigger sync:

self.emit("sync_requested", {})

Optimization

The module uses content hashing to avoid unnecessary writes:

1. Downloads whitelist content
2. Calculates SHA-256 hash
3. Compares with last known hash
4. Only writes and reloads if hash differs

This prevents unnecessary fail2ban reloads when whitelist hasn't changed.

Troubleshooting

Whitelist Not Updating

1. Check agent logs:

   journalctl -u bloqd-agent | grep -i sync

2. Verify API connectivity:

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

3. Check file permissions:

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

IP Still Getting Banned

1. Verify IP is in dashboard whitelist
2. Check whitelist file contains the IP:

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

3. Reload fail2ban:

   fail2ban-client reload

Sync Errors

Common causes:

• Network connectivity issues
• Invalid API key
• SSL certificate problems (try verify_ssl: false)
• Server unreachable