Skip to main content

Frequently Asked Questions

Common questions about Bloqd installation, usage, and features.

General​

What is Bloqd?​

Bloqd is a centralized management platform for fail2ban across multiple servers. It provides:

  • Real-time ban monitoring
  • Centralized whitelist management
  • Remote server control
  • Analytics and reporting
  • Integrations (Discord, AbuseIPDB, SIEM)

What does Bloqd stand for?​

"Bloqd" comes from "blocked" - referencing the IP blocking functionality of fail2ban.

Is Bloqd free?​

Bloqd offers a free tier with:

  • 1 managed server
  • Basic ban monitoring
  • Whitelist sync

Paid tiers unlock more servers and advanced features.

What are the system requirements?​

Server (Dashboard):

  • 1 CPU core
  • 512 MB RAM
  • 1 GB disk space
  • Docker & Docker Compose

Agent (Managed servers):

  • Python 3.8+
  • fail2ban installed
  • Outbound HTTPS access

Which operating systems are supported?​

Dashboard: Any OS with Docker (Linux recommended)

Agent:

  • Debian 10+
  • Ubuntu 18.04+
  • RHEL/CentOS 7+
  • Fedora 35+
  • Other Linux with Python 3.8+ and fail2ban

Installation​

Can I run Bloqd without Docker?​

Yes, but Docker is recommended. For manual installation:

  1. Install Node.js 18+
  2. Clone repository
  3. Run npm install
  4. Configure environment
  5. Run npm start

See the manual installation guide for details.

How do I update Bloqd?​

cd /opt/bloqd
docker compose pull
docker compose up -d

Can I migrate from another fail2ban manager?​

Yes, Bloqd can import:

  • IP whitelists (from text file)
  • fail2ban configurations

Export your data and use the import features in the dashboard.

Does Bloqd work with firewalls other than iptables?​

Bloqd works with whatever fail2ban uses. If fail2ban supports your firewall (iptables, nftables, firewalld, ufw), Bloqd will work.

Usage​

How often does the agent check in?​

Default heartbeat interval is 60 seconds. Configurable in agent.yaml:

heartbeat:
  interval: 60  # seconds

How long are bans stored?​

By default, 90 days. Configure in .env:

BAN_RETENTION_DAYS=90

Can I run Bloqd behind a reverse proxy?​

Yes, Bloqd works with Nginx, Caddy, Traefik, and other proxies. See the reverse proxy guide.

Does Bloqd support IPv6?​

Yes, both IPv4 and IPv6 addresses are fully supported.

Can multiple users access the dashboard?​

Yes, Bloqd supports multiple users with role-based access:

  • Admin: Full access
  • Operator: Manage bans and servers
  • Viewer: Read-only access

Security​

Is my data encrypted?​

  • In transit: Yes, HTTPS/TLS
  • At rest: Database file is not encrypted by default
  • Passwords: Hashed with bcrypt
  • API keys: Hashed (only shown once on creation)

How secure is the agent connection?​

  • API key authentication
  • HTTPS encryption
  • Server validates agent identity
  • Commands are signed and verified

Can I use Bloqd in production?​

Yes, Bloqd is designed for production use. Recommendations:

  • Use HTTPS with valid certificates
  • Enable MFA for admin accounts
  • Regularly backup the database
  • Keep software updated

What data does Bloqd collect?​

Bloqd collects from your servers:

  • Banned IP addresses
  • Jail names and ban times
  • Server metrics (CPU, memory, disk)
  • fail2ban status

Bloqd does not send this data to external services unless you configure integrations (AbuseIPDB, SIEM).

Features​

What is the whitelist sync?​

The whitelist sync ensures all your managed servers have the same allowed IPs:

  1. Add IP to Bloqd whitelist
  2. Bloqd pushes to all agents
  3. Agents update fail2ban's ignoreip

How does AbuseIPDB integration work?​

When enabled, Bloqd automatically:

  1. Checks banned IPs against AbuseIPDB
  2. Reports malicious IPs to AbuseIPDB
  3. Shows abuse scores in the dashboard

Requires a free AbuseIPDB API key.

What is port knocking?​

Port knocking (Pro feature) hides services behind a knock sequence:

  1. Send packets to specific ports in order
  2. Service port opens temporarily for your IP
  3. Port closes after timeout

Useful for SSH, admin panels, etc.

Can I create custom jail templates?​

Yes (Personal tier+). Create templates with:

  • Filter patterns
  • Action configurations
  • Ban times, retries, etc.

Deploy to servers with one click.

Troubleshooting​

Why is my server showing offline?​

Common causes:

  1. Agent not running
  2. Network connectivity issue
  3. API key mismatch
  4. Firewall blocking outbound HTTPS

Check agent status: sudo systemctl status bloqd-agent

Why aren't bans appearing?​

Check:

  1. Agent is running
  2. fail2ban action is configured
  3. Reporter module is enabled
  4. Jail is active in fail2ban

Why is the dashboard slow?​

Possible solutions:

  1. Reduce ban retention period
  2. Vacuum the database
  3. Increase server resources
  4. Check for large queries

How do I reset my password?​

docker compose exec bloqd npm run reset-password admin

Integrations​

Does Bloqd work with Prometheus/Grafana?​

Yes, Bloqd exposes Prometheus-compatible metrics at /api/v1/metrics.

Can I send notifications to Slack?​

Discord webhooks work with Slack's webhook compatibility. Native Slack support is planned.

Does Bloqd support SSO?​

Yes, GitHub and Google OAuth are supported. Configure in Settings → OAuth.

Licensing​

How are servers counted?​

Each unique server with an installed agent counts as one server toward your limit.

What happens if I exceed my limit?​

You cannot add new servers until you:

  • Remove existing servers
  • Upgrade to a higher tier

Existing servers continue working.

Can I transfer my license?​

Yes, deactivate on the old installation and activate on the new one. Contact support if needed.

Is there a trial?​

The free tier is available indefinitely with 1 server. For trying Pro features, contact support for a trial.

API​

Where is the API documentation?​

API documentation is in the dashboard at /api/docs (Swagger UI) or in this documentation under API Reference.

What's the rate limit?​

TierRequests/minute
Free60
Personal120
Pro300
EnterpriseCustom

Can I use the API to automate everything?​

Yes, all dashboard functionality is available via API. Common automations:

  • Ban/unban IPs
  • Add to whitelist
  • Deploy templates
  • Generate reports

Support​

How do I get help?​

  1. Check this documentation
  2. Search GitHub Issues
  3. Open a new issue for bugs
  4. Contact support@bloqd.io for license issues

How do I report a bug?​

Open an issue on GitHub with:

  • Bloqd version
  • Steps to reproduce
  • Expected vs actual behavior
  • Logs if applicable

How do I request a feature?​

Open a feature request on GitHub. Community voting helps prioritize development.