fail2ban-webui/docs/installation.md

Installation – Weboberfläche

Diese Anleitung richtet die Weboberfläche Schritt für Schritt auf einem Docker-Host ein. Die Agenten auf den fail2ban-Hosts sind in agent.md beschrieben; du brauchst beides.

• Quelle: https://git.retronerd.at/schiwagoa/fail2ban-webui
• Image: git.retronerd.at/schiwagoa/fail2ban-webui (amd64, arm64)
• Tags: 1.0.0 (genau diese Version), 1 (neueste 1.x), latest

1. Voraussetzungen

• Grundpakete curl und git (apt install -y curl git; mc optional) – in frischen LXC-Templates fehlt curl
• Docker Engine mit Compose-Plugin (docker compose version), z. B. über den Docker-Installer – Details in den Voraussetzungen im README
• Ausgehendes SSH (TCP 22 oder dein Port) vom Docker-Host zu jedem fail2ban-Host
• Ein DNS-Name und ein Reverse Proxy mit TLS für die Oberfläche (siehe reverse-proxy.md)

Prüfen, ob das Subnetz aus dem Beispiel (172.23.51.0/24) frei ist:

docker network inspect $(docker network ls -q) --format '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}' | grep 172.23.51 \
  || echo "172.23.51.0/24 is free"

Ist es belegt, ein anderes /24 wählen und in Schritt 3 anpassen.

2. Verzeichnisse

mkdir -p /opt/fail2ban-webui/config /opt/fail2ban-webui/data
cd /opt/fail2ban-webui
# der Container läuft als UID 10050 und muss in data/ schreiben
chown -R 10050:10050 data
chmod 700 data

Pfad	Inhalt
docker-compose.yaml	der Dienst
.env	Einstellungen und Geheimnisse (Passwort-Hash, OIDC-Secret)
config/hosts.yaml	die fail2ban-Hosts (schreibgeschützt eingebunden)
data/	SSH-Schlüssel, known_hosts, Sitzungsschlüssel, Protokoll, GeoIP-Datenbank

3. docker-compose.yaml

nano docker-compose.yaml

# =====================================================================
# fail2ban-webui – example docker-compose.yaml
#
#   mkdir -p fail2ban-webui/{config,data} && cd fail2ban-webui
#   (copy this file, .env.example as .env and hosts.yaml.example as config/hosts.yaml)
#   chown -R 10050:10050 data
#
# The UI listens on 127.0.0.1:8080 only – put a reverse proxy with TLS in front of it.
# The network uses its own /24 subnet; change it if it collides with an existing one
# (docker network inspect $(docker network ls -q) | grep Subnet).
# =====================================================================
name: fail2ban-webui

services:
  fail2ban-webui:
    image: git.retronerd.at/schiwagoa/fail2ban-webui:latest
    # build: { context: .., dockerfile: docker/Dockerfile }   # build from the repository instead
    container_name: fail2ban-webui
    restart: unless-stopped
    env_file: .env
    environment:
      TZ: ${TZ:-Europe/Vienna}
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    volumes:
      - ./config:/config:ro
      - ./data:/data
    ports:
      - "127.0.0.1:8080:8080"
    extra_hosts:
      # lets the container reach an agent on the Docker host itself (address: host.docker.internal)
      - "host.docker.internal:host-gateway"
    deploy:
      resources:
        limits:
          memory: 256M
    networks:
      fail2ban-webui.dockernetwork.local:
        ipv4_address: 172.23.51.10

networks:
  fail2ban-webui.dockernetwork.local:
    name: fail2ban-webui.dockernetwork.local
    driver: bridge
    ipam:
      config:
        - subnet: 172.23.51.0/24
          gateway: 172.23.51.1
          ip_range: 172.23.51.128/25

Läuft der Reverse Proxy auf einer anderen Maschine, den Port stattdessen an die LAN-Adresse binden, z. B. "192.168.1.10:8080:8080" – niemals ohne Firewall davor an 0.0.0.0.

Solange das Image in der Registry noch nicht veröffentlicht ist, schlägt der Download fehl (manifest unknown bzw. pull access denied). Dann das Image einmalig lokal unter demselben Namen bauen:

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

4. .env

Mit dieser minimalen Datei beginnen; alle Optionen stehen in configuration.md und in examples/.env.example.

nano .env
chmod 600 .env

PUBLIC_URL=https://fail2ban.example.org
DEFAULT_LANG=en
TRUSTED_PROXY_HOPS=1

AUTH_MODE=local
AUTH_USER=admin
AUTH_PASSWORD_HASH='set in the next step'

SSH_USER=f2bweb
MANUAL_JAIL=manual-block
GEOIP_AUTO_DOWNLOAD=1

DEFAULT_LANG=de stellt die Oberfläche standardmäßig auf Deutsch; jeder Benutzer kann die Sprache zusätzlich im Dropdown wählen.

Passwort-Hash

docker compose run --rm -it fail2ban-webui hash-password

Die ausgegebene Zeile (AUTH_PASSWORD_HASH='scrypt:…') in die .env kopieren und den Platzhalter ersetzen. Die einfachen Anführungszeichen beibehalten – der Hash enthält $-Zeichen, die Docker Compose sonst als Variablen auswerten würde. Für Single Sign-on stattdessen siehe authentication.md.

5. SSH-Schlüssel

docker compose run --rm fail2ban-webui keygen

Der Befehl erzeugt data/ssh/id_ed25519 und gibt den öffentlichen Schlüssel aus (ssh-ed25519 AAAA… fail2ban-webui). Kopieren – er wird für den Agent-Installer gebraucht.

6. Agenten

Den Agenten auf jedem fail2ban-Host installieren, wie in agent.md beschrieben. Kurzfassung:

# auf jedem fail2ban-Host, als root
git clone https://git.retronerd.at/schiwagoa/fail2ban-webui.git /tmp/fail2ban-webui
echo 'ssh-ed25519 AAAA… fail2ban-webui' > /tmp/webui.pub
bash /tmp/fail2ban-webui/agent/install.sh --key-file /tmp/webui.pub --from <öffentliche IP des Webui-Hosts>

7. config/hosts.yaml

nano config/hosts.yaml

hosts:
  - name: web01
    address: web01.example.org

  - name: lxc-proxy
    address: 192.168.1.20
    port: 2222

  # fail2ban on the Docker host itself
  - name: dockerhost
    address: host.docker.internal

user ist standardmäßig SSH_USER (f2bweb). Für Hosts, auf denen der Agent mit --user root installiert wurde, user: root setzen.

8. Host-Schlüssel und Verbindungstest

docker compose run --rm -it fail2ban-webui keyscan

keyscan zeigt den Fingerprint jedes Hosts und fragt vor dem Schreiben von data/ssh/known_hosts nach. Die Fingerprints mit den Hosts vergleichen:

# auf dem fail2ban-Host
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Danach jeden Agenten testen:

docker compose run --rm fail2ban-webui check

OK    web01                agent 1.0.0, 3 jails, 12 bans
OK    lxc-proxy            agent 1.0.0, 2 jails, 0 bans
OK    dockerhost           agent 1.0.0, 4 jails, 7 bans

Jeder Host muss OK melden – sonst siehe operations.md.

9. Starten

docker compose up -d
docker compose ps                      # STATUS: Up … (healthy)
docker compose logs -f fail2ban-webui  # mit Strg+C verlassen

Das Log zeigt eine Zusammenfassung wie fail2ban-webui 1.0.0 – hosts: web01, lxc-proxy, dockerhost – auth: local – loki: off – geoip: on.

Lokaler Test ohne Proxy:

curl -s http://127.0.0.1:8080/healthz    # ok

10. Reverse Proxy

http://127.0.0.1:8080 (oder die LAN-Adresse aus Schritt 3) unter deinem DNS-Namen mit TLS veröffentlichen – Beispiele für Nginx Proxy Manager, Caddy, Traefik und nginx stehen in reverse-proxy.md. Dann PUBLIC_URL öffnen und anmelden.

Nächste Schritte

• Login mit fail2ban absichern
• Updates und Backups
• Optional: Loki-Verlauf und Grafana-Links