fail2ban-webui/README.md

fail2ban-webui

Eine schlanke, selbst gehostete Weboberfläche, um fail2ban-Sperren auf mehreren Hosts anzuzeigen, zu setzen und aufzuheben – Bare Metal, VMs, LXC-Container oder Docker-Hosts.

• Eine Seite für alle Hosts: aktuelle Sperren pro Jail, Herkunft (GeoIP) mit Weltkarte, Suche und Filter
• IP dauerhaft auf beliebigen Hosts sperren, pro Jail oder überall entsperren
• Protokoll jeder Aktion (wer, wann, von wo)
• Optional: Log-Verlauf pro IP aus Loki, Links nach Grafana
• Anmeldung mit lokalem Benutzer, OpenID Connect (z. B. Authentik) oder über den Reverse Proxy
• Oberfläche auf Englisch und Deutsch, weitere Sprachen über eine JSON-Datei
• Läuft als gehärteter Container (schreibgeschützt, ohne Capabilities, nicht als root), amd64 und arm64

 Browser ──HTTPS──▶ Reverse Proxy ──▶ fail2ban-webui (Docker)
                                           │  SSH, ein eingeschränkter Schlüssel
                     ┌─────────────────────┼─────────────────────┐
                     ▼                     ▼                     ▼
               Host A (Bare Metal)   LXC-Container          Docker-Host
               f2b-webctl            f2b-webctl             f2b-webctl
               fail2ban              fail2ban               fail2ban

Die Weboberfläche bekommt nie eine Shell auf deinen Hosts. Auf jedem Host läuft ein kleiner Agent, f2b-webctl, als SSH-Forced-Command. Er kennt nur list, ban <ip>, unban <jail> <ip>, unban-all <ip> und version, sperrt niemals private Netze, die eigenen Adressen des Hosts oder Einträge seiner Schutzliste und protokolliert jede Aktion im Syslog. Zugriff auf den fail2ban-Socket wäre gleichbedeutend mit root – die Sicherheitsgrenze ist der Agent, nicht die Weboberfläche.

Voraussetzungen

Getestet auf Ubuntu 24.04/26.04 und Debian 12/13 – Bare Metal, VM oder LXC. Alle Befehle als root.

Grundpakete (alle Hosts)

apt update
apt install -y curl git
apt install -y mc        # optional: Midnight Commander als Dateimanager

Docker-Host (Weboberfläche)

Gebraucht wird eine vollständige Docker-Umgebung – Docker Engine und das Compose-Plugin (Befehl docker compose mit Leerzeichen), amd64 oder arm64.

Auf Ubuntu 24.04/26.04 z. B. mit dem Docker-Installer:

git clone https://git.retronerd.at/schiwagoa/public-docker-installer-26.04-v1.git
cd public-docker-installer-26.04-v1
chmod +x *.sh
./docker-installer-2604-v1.sh

Diese Anleitung verwendet docker compose (Plugin). Der Installer richtet zusätzlich das eigenständige docker-compose ein; das Plugin kommt normalerweise mit docker-ce mit. Prüfen – beide Befehle müssen eine Version ausgeben:

docker version --format '{{.Server.Version}}'
docker compose version

Meldet docker compose version den Fehler 'compose' is not a docker command, das Plugin nachinstallieren: apt install -y docker-compose-plugin.

In einem LXC-Container braucht Docker auf dem Proxmox-Host die Features nesting=1,keyctl=1 (unprivilegierter Container: pct set <id> --features nesting=1,keyctl=1, danach den Container neu starten).

fail2ban-Hosts (Agent)

apt install -y fail2ban python3 sudo openssh-server
systemctl enable --now fail2ban
fail2ban-client ping     # Server replied: pong

• fail2ban ≥ 0.11 (Start-/Endzeiten der Sperren brauchen --with-time)
• sudo nur für den Standardbenutzer f2bweb; mit einem root-Schlüssel nicht nötig
• bash, ssh-keygen (Teil von OpenSSH) für den Installer

Schnellstart

Voraussetzungen siehe oben (Grundpakete, Docker, Agent auf den fail2ban-Hosts).

mkdir -p /opt/fail2ban-webui/{config,data} && cd /opt/fail2ban-webui
curl -fsSLo docker-compose.yaml https://git.retronerd.at/schiwagoa/fail2ban-webui/raw/branch/main/examples/docker-compose.yaml
curl -fsSLo .env               https://git.retronerd.at/schiwagoa/fail2ban-webui/raw/branch/main/examples/.env.example
curl -fsSLo config/hosts.yaml  https://git.retronerd.at/schiwagoa/fail2ban-webui/raw/branch/main/examples/hosts.yaml.example
chown -R 10050:10050 data

Noch kein fertiges Image: Solange git.retronerd.at/schiwagoa/fail2ban-webui in der Registry noch nicht veröffentlicht ist, das Image einmalig lokal unter demselben Namen bauen – Docker Compose verwendet dann das lokale Image und versucht keinen Download:

git clone https://git.retronerd.at/schiwagoa/fail2ban-webui.git /opt/fail2ban-webui-src
docker build -f /opt/fail2ban-webui-src/docker/Dockerfile --build-arg VERSION=dev >   -t git.retronerd.at/schiwagoa/fail2ban-webui:latest /opt/fail2ban-webui-src

docker compose run --rm -it fail2ban-webui hash-password   # Zeile in die .env übernehmen
nano .env                                                  # PUBLIC_URL, Hash, DEFAULT_LANG=de …
docker compose run --rm fail2ban-webui keygen              # öffentlicher Schlüssel für die Agenten
# auf jedem fail2ban-Host den Agenten installieren (docs/agent.md), danach:
nano config/hosts.yaml                                     # Beispiel-Hosts durch deine ersetzen!
docker compose run --rm -it fail2ban-webui keyscan
docker compose run --rm fail2ban-webui check
docker compose up -d

Die Oberfläche lauscht auf 127.0.0.1:8080 – davor gehört ein Reverse Proxy mit TLS.

Dokumentation

Installation	Weboberfläche Schritt für Schritt, von mkdir bis zur ersten Anmeldung
Agent	f2b-webctl auf Bare Metal, LXC und Docker-Hosts installieren
Konfiguration	alle Einstellungen in .env und hosts.yaml
Anmeldung	lokaler Login, OpenID Connect (Authentik), Anmeldung über den Reverse Proxy
Reverse Proxy	Nginx Proxy Manager, Caddy, Traefik, nginx
Betrieb	Logs, Updates, Backups, Fehlersuche
Entwicklung	lokales Testbed, Tests, neue Sprache hinzufügen
Sicherheit	Sicherheitsmodell und Melden von Schwachstellen

Lizenz

MIT. IP-Geolokalisierung durch DB-IP Lite (CC BY 4.0), wird nur bei GEOIP_AUTO_DOWNLOAD=1 heruntergeladen. Weltkarte von Natural Earth (Public Domain), in der App enthalten.

---

🏰 Website · 🐘 Mastodon · 🔒 Datenschutz · 💬 Support

© Thomas Werner Schwaighofer · retronerd.AT · MIT Lizenz