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.

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