From 62d4c8b78d35332544d8c80184a9d700be70f5ac Mon Sep 17 00:00:00 2001 From: Michael Reber Date: Wed, 22 Jul 2026 18:55:30 +0200 Subject: [PATCH] Replace architecture.drawio.png with svg variant, that is also readable in darkmode --- README.md | 2 +- docs/architecture.md | 2 +- docs/diagrams/architecture.drawio.svg | 4 ++++ 3 files changed, 6 insertions(+), 2 deletions(-) create mode 100644 docs/diagrams/architecture.drawio.svg diff --git a/README.md b/README.md index 62f286f..4314c53 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ The UI runs as a single Go binary, in a container or as a systemd service. Two i * **Control path** (blue) - Fail2ban UI manages each Fail2Ban instance through one of three connectors (see below): reading jail status, banning and unbanning, editing configuration, restarting the service. * **Event path** (green) - a custom Fail2Ban action on each host posts every ban and unban event back to the UI over HTTP, authenticated by a shared callback secret. The UI stores the event, broadcasts it to connected browsers, and triggers alerts and advanced actions. -[![Architecture-Diagram](docs/diagrams/architecture.drawio.png)](docs/diagrams/architecture.drawio.png) +[![Architecture-Diagram](docs/diagrams/architecture.drawio.svg)](docs/diagrams/architecture.drawio.svg) See [docs/architecture.md](docs/architecture.md) for the data-flow description. diff --git a/docs/architecture.md b/docs/architecture.md index 5d67e63..f76407e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -11,7 +11,7 @@ The application consists of the following parts: - Optional integrations: alert providers, GeoIP/Whois enrichment, and edge firewall actions Fail2Ban UI system architecture -[![Architecture-Diagram](diagrams/architecture.drawio.png)](diagrams/architecture.drawio.png) +[![Architecture-Diagram](diagrams/architecture.drawio.svg)](diagrams/architecture.drawio.svg) ## Design principles diff --git a/docs/diagrams/architecture.drawio.svg b/docs/diagrams/architecture.drawio.svg new file mode 100644 index 0000000..b44b2b7 --- /dev/null +++ b/docs/diagrams/architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
Web Browser
Dashboard, jail/filter management, settings
Live ban/unban events propagated over WebSocket
Identity provider (optional)
Keycloak, Authentik or Pocket-ID
OIDC authorization flow
Alert providers
Email (SMTP)
Webhook (HTTP POST)
Elasticsearch (event indexing)
Country filtering, GeoIP/Whois enrichment
Edge firewalls
MikroTik (SSH)
pfSense or OPNsense (REST API)
Permanent blocks for recurring offenders,
pushed by the UI when thresholds are reached
Fail2Ban UI host - container or systemd service
Fail2Ban UI (single Go binary, Gin)
Web frontend
embedded template with static assets, vanilla JS, Tailwind (no CDN)
REST API
/api/* --> session auth (OIDC)
strict IP/CIDR input validation
WebSocket hub
same-origin only, /api/ws
ban/unban and console events
Connector manager
one connector per managed fail2ban-server, selected via X-F2B-Server
Local (via socket), SSH (via remote fail2ban-client), Agent (via HTTPS)
Alert dispatcher
Email, Webhook, Elasticsearch
per-event toggles, country filter
SQLite storage
ban_events, servers, settings
permanent_blocks
Firewall integrations
recurring-offender thresholds
MikroTik, pfSense or OPNsense
GeoIP / Whois
MaxMind or ip-api.com
enriches events and alerts
Event callback receiver
POST "/api/ban", POST "/api/unban"
validates X-Callback-Secret --> enrich --> store --> broadcast --> alert
--> advanced actions (edge firewall block on repeat offenders)
Fail2Ban -- local connector (same host as the UI)
fail2ban daemon
jails, filters, actions
fail2ban.sock
/etc/fail2ban (must be mounted)
ui-custom-action.conf
fires on every ban/unban
curl --> callback URL
(loopback)
direct unix socket
file access
POST events
(loopback HTTP)
Remote host -- SSH connector
sshd
dedicated system service
(account, key auth needed)
fail2ban daemon
sudo fail2ban-client
/etc/fail2ban via SSH
ui-custom-action.conf
posts ban/unban events to the UI callback URL
requires sudo permissions for: "fail2ban-client *"
and as well for: "systemctl restart fail2ban" -- Also the SSH-user used to connect, 
Remote host -- agent connector
fail2ban-ui-agent
HTTP control API, no inbound SSH required (Agent talks to fail2ban.sock)
fail2ban daemon
jails, filters, actions
fail2ban.sock
ui-custom-action.conf
posts ban/unban events (callback URL)
prebuilt image: swissmakers/fail2ban-ui-agent
HTTPS
SSH
HTTPS
HTTPS POST
X-Callback-Secret
Legend
The UI manages Fail2Ban through a connector
Fail2Ban posts ban/unban callbacks to the UI
Operator traffic and outbound integrations
Optional component
WSS
must be able to write to "/etc/fail2ban/*" to be able to make changes to configuration
\ No newline at end of file