schiwagoaandClaude Opus 5.5
97b0c14dac
- README: prerequisites before the quick start – base packages (curl, git, mc optional), Docker via public-docker-installer-26.04-v1 with compose plugin check, LXC features, packages for fail2ban hosts - Local image build as long as the image is not in the registry yet - Troubleshooting: missing curl/git, missing compose plugin, image pull Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
152 lines
6.8 KiB
Markdown
152 lines
6.8 KiB
Markdown
# 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`](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)
|
||
|
||
```bash
|
||
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](https://git.retronerd.at/schiwagoa/public-docker-installer-26.04-v1):
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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)
|
||
|
||
```bash
|
||
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).
|
||
|
||
```bash
|
||
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:
|
||
>
|
||
> ```bash
|
||
> 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
|
||
> ```
|
||
|
||
```bash
|
||
docker compose run --rm -it fail2ban-webui hash-password # Zeile in die .env übernehmen
|
||
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:
|
||
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](docs/installation.md) | Weboberfläche Schritt für Schritt, von `mkdir` bis zur ersten Anmeldung |
|
||
| [Agent](docs/agent.md) | `f2b-webctl` auf Bare Metal, LXC und Docker-Hosts installieren |
|
||
| [Konfiguration](docs/configuration.md) | alle Einstellungen in `.env` und `hosts.yaml` |
|
||
| [Anmeldung](docs/authentication.md) | lokaler Login, OpenID Connect (Authentik), Anmeldung über den Reverse Proxy |
|
||
| [Reverse Proxy](docs/reverse-proxy.md) | Nginx Proxy Manager, Caddy, Traefik, nginx |
|
||
| [Betrieb](docs/operations.md) | Logs, Updates, Backups, Fehlersuche |
|
||
| [Entwicklung](docs/development.md) | lokales Testbed, Tests, neue Sprache hinzufügen |
|
||
| [Sicherheit](SECURITY.md) | Sicherheitsmodell und Melden von Schwachstellen |
|
||
|
||
## Lizenz
|
||
|
||
[MIT](LICENSE). IP-Geolokalisierung durch [DB-IP Lite](https://db-ip.com) (CC BY 4.0), wird
|
||
nur bei `GEOIP_AUTO_DOWNLOAD=1` heruntergeladen. Weltkarte von [Natural Earth](https://www.naturalearthdata.com)
|
||
(Public Domain), in der App enthalten.
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
🏰 <a href="https://retronerd.at">Website</a> ·
|
||
🐘 <a href="https://social.retronerd.at/@schiwagoa">Mastodon</a> ·
|
||
🔒 <a href="https://retronerd.at/datenschutzerklaerung/">Datenschutz</a> ·
|
||
💬 <a href="https://helpdesk.retronerd.at/open.php">Support</a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://dl.retronerd.at/Bilder/cat-footer.png" alt="" width="100%">
|
||
</p>
|
||
|
||
<p align="center">© Thomas Werner Schwaighofer · retronerd.AT · <a href="LICENSE">MIT Lizenz</a></p>
|