schiwagoaandClaude Opus 5.5
d03aa6f0d2
The temporary "image not yet in the registry – build locally" hints are removed from README, installation guide and troubleshooting. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
249 lines
7.4 KiB
Markdown
249 lines
7.4 KiB
Markdown
# 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](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](https://git.retronerd.at/schiwagoa/public-docker-installer-26.04-v1) –
|
||
Details in den [Voraussetzungen im README](../README.md#voraussetzungen)
|
||
- 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](reverse-proxy.md))
|
||
|
||
Prüfen, ob das Subnetz aus dem Beispiel (`172.23.51.0/24`) frei ist:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
nano docker-compose.yaml
|
||
```
|
||
|
||
```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](configuration.md) und in [`examples/.env.example`](../examples/.env.example).
|
||
|
||
```bash
|
||
nano .env
|
||
chmod 600 .env
|
||
```
|
||
|
||
```ini
|
||
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
|
||
|
||
```bash
|
||
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](authentication.md).
|
||
|
||
## 5. SSH-Schlüssel
|
||
|
||
```bash
|
||
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](agent.md) beschrieben. Kurzfassung:
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
nano config/hosts.yaml
|
||
```
|
||
|
||
```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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
# auf dem fail2ban-Host
|
||
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
|
||
```
|
||
|
||
Danach jeden Agenten testen:
|
||
|
||
```bash
|
||
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](operations.md#fehlersuche).
|
||
|
||
## 9. Starten
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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](reverse-proxy.md). Dann `PUBLIC_URL` öffnen und anmelden.
|
||
|
||
## Nächste Schritte
|
||
|
||
- [Login mit fail2ban absichern](operations.md#login-mit-fail2ban-absichern)
|
||
- [Updates und Backups](operations.md)
|
||
- Optional: [Loki-Verlauf und Grafana-Links](configuration.md#loki-und-grafana)
|