Skip to main content

Whitelist Management

The whitelist prevents trusted IPs from being banned across your infrastructure.

How It Works​

  1. You add an IP/CIDR to the Bloqd whitelist
  2. Agents sync the whitelist periodically (default: 5 minutes)
  3. fail2ban ignores matching IPs

The whitelist is stored at /etc/fail2ban/bloqd-whitelist.txt on each server.

Adding Entries​

Single Entry​

  1. Click Add Entry
  2. Enter IP address or CIDR:
    • Single IP: 192.168.1.100
    • CIDR range: 10.0.0.0/8
    • IPv6: 2001:db8::1
  3. Add optional comment
  4. Click Add

Bulk Import (Pro)​

  1. Click Bulk Import
  2. Paste IPs (one per line): 
    192.168.1.100
    10.0.0.0/8
    172.16.0.0/12
  3. Click Import

From Ban Entry​

  1. Find a ban in the Bans page
  2. Click Whitelist action
  3. Confirm

Managing Entries​

View All Entries​

The whitelist page shows all entries with:

  • IP/CIDR
  • Comment
  • Added by (user)
  • Added date

Edit Entry​

  1. Click edit icon
  2. Modify comment
  3. Save

Delete Entry​

  1. Click delete icon
  2. Confirm deletion
  3. Entry removed from all servers on next sync

Sync Status​

Manual Sync​

Force immediate sync to all servers:

  1. Click Sync Now button
  2. Wait for confirmation
  3. Check sync results

Automatic Sync​

Agents sync automatically based on their poll interval (default: 5 minutes).

Sync Verification​

To verify an entry synced to a server:

# On the managed server
cat /etc/fail2ban/bloqd-whitelist.txt | grep "192.168.1.100"

Whitelist Format​

The whitelist file is plain text, one entry per line:

# Bloqd whitelist - do not edit manually
# Last sync: 2024-01-15T10:30:00Z
192.168.1.100
10.0.0.0/8
2001:db8::/32
warning

Do not manually edit the whitelist file on servers. Changes will be overwritten on the next sync.

Best Practices​

What to Whitelist​

  • Your office/VPN IP ranges
  • Monitoring services (Pingdom, UptimeRobot)
  • Trusted partner IPs
  • Load balancer/proxy IPs

What NOT to Whitelist​

  • Dynamic IPs (home connections)
  • Entire ISP ranges
  • Cloud provider ranges (too broad)

CIDR Notation​

Use CIDR for ranges instead of multiple single IPs:

Instead ofUse
192.168.1.1, 192.168.1.2, ...192.168.1.0/24
10.0.0.0 - 10.255.255.25510.0.0.0/8

Documentation​

Always add comments explaining why an IP is whitelisted:

192.168.1.100  # Office main IP
10.20.30.0/24  # AWS VPC for monitoring

API Access​

Get Whitelist​

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

Get Plain Text (for scripts)​

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

Add Entry​

curl -X POST "https://bloqd.example.com/api/v1/whitelist" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip": "192.168.1.100", "comment": "Office IP"}'

Delete Entry​

curl -X DELETE "https://bloqd.example.com/api/v1/whitelist/5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Troubleshooting​

IP Still Getting Banned​

  1. Verify the entry exists in Bloqd whitelist
  2. Check sync completed successfully
  3. On the server, verify the IP is in the whitelist file
  4. Reload fail2ban: fail2ban-client reload

Sync Not Working​

  1. Check agent status: systemctl status bloqd-agent
  2. Check agent logs: journalctl -u bloqd-agent
  3. Verify API connectivity from server
  4. Force manual sync from dashboard