Knoten: Fehlersuche

Knoten: Fehlersuche

Diese Seite ergänzt Knoten einrichten. Dort steht, was das Skript tut; hier steht, was man tut, wenn es nicht so läuft.

Welche Skripte auf die Knoten gehören

Skript	Wo es läuft	Wozu
setup-haproxy.sh	auf jedem HAProxy-Knoten, als root	richtet HAProxy, die Data Plane API und — mit --crowdsec — CrowdSec ein. Wiederholbar
setup-haproxy.sh --crowdsec-proxy <name>	auf dem Proxy, der die LAPI des Standorts hat	legt den Zugang für einen weiteren Proxy an und gibt den Befehl dafür aus
setup-haproxy.sh --crowdsec-join …	auf dem weiteren Proxy	ihn an die LAPI des Standorts anbinden (der Befehl kommt von --crowdsec-proxy)
zpo-captcha	nicht von Hand	kommt als Paket aus der Paketquelle von ZPO; das Skript installiert es

Die Skripte in packaging/ des Repositorys (test-base-config.sh, test-crowdsec.sh, test-join.sh) sind Prüfungen für die Entwicklung. Sie laufen mit Docker und gehören nicht auf einen Produktivknoten.

Vor dem Lauf

• Ubuntu oder Debian, frisch oder ohne fremde HAProxy-Konfiguration. Eine vorhandene haproxy.cfg sichert das Skript nach /etc/haproxy/haproxy.cfg.bak-<datum>-<uhrzeit>, ersetzt sie aber.
• Eine konkrete Verwaltungsadresse angeben, wenn der Server mehrere Adressen hat (--api-bind). Ohne Angabe nimmt das Skript die erste eigene IP — bei Docker-Bridges oder einem zweiten Netz kann das die falsche sein.
• Ist ufw aktiv, mit --allow-from nur das Netz von ZPO freigeben, sonst sind Data Plane API, LAPI und Metriken für jeden erreichbar, der ins Netz kommt.

Meldungen des Skripts

Die Meldungen stehen so in setup-haproxy.sh; wer sie sucht, findet sie dort im Wortlaut.

Meldung	Ursache	Abhilfe
Bitte als root ausführen	Skript ohne Rechte gestartet	curl … | sudo bash oder sudo ./setup-haproxy.sh
Unbekannte Option	Tippfehler oder eine Option aus einer neueren Version	--help zeigt alle Optionen des Skripts auf dem Knoten
--crowdsec braucht eine konkrete --api-bind-Adresse, nicht 0.0.0.0	LAPI und Data Plane API sollen auf einer Adresse lauschen, nicht überall	--api-bind <eigene-ip> angeben
--allow-from braucht Adressen oder Netze (CIDR, mit Komma getrennt)	Der Wert ist keine Adresse, z. B. ein Name	--allow-from 192.0.2.10/32,192.0.2.0/24
--crowdsec-join braucht die Adresse der LAPI (https://<adresse>:8080)	Die Adresse hat einen Pfad oder fehlt das Schema	nur https://<adresse>:8080, ohne Pfad
die Anbindung über https braucht --crowdsec-fingerprint	Der Befehl stammt von vor der TLS-Umstellung oder ist unvollständig	den vollständigen Befehl von --crowdsec-proxy auf dem LAPI-Proxy neu holen
das Zertifikat der LAPI passt nicht zum Fingerabdruck — nichts übernommen	Der Fingerabdruck im Befehl stimmt nicht mit dem Zertifikat überein: die Adresse der LAPI hat ein neues Zertifikat bekommen, oder es antwortet ein anderer Rechner	Auf dem LAPI-Proxy --crowdsec-proxy <name> erneut ausführen. Bleibt die Meldung, prüfen, wer unter der Adresse antwortet, bevor man den Proxy anbindet
die LAPI antwortet unter … nicht per TLS	Die LAPI ist nicht erreichbar, oder sie läuft noch ohne TLS	auf dem LAPI-Proxy das Skript erneut ausführen; danach systemctl status crowdsec
Die Zugangsdaten enthalten keinen Fingerabdruck der LAPI	Die Zugangsdaten stammen von vor der TLS-Umstellung	auf dem LAPI-Proxy das Skript ohne Optionen erneut ausführen, dann --crowdsec-proxy
neues Zertifikat für … erzeugt (kein Fehler)	Die Verwaltungsadresse hat sich geändert, deshalb gibt es ein neues Zertifikat	den neuen Fingerabdruck in ZPO am Knoten (und an der LAPI) eintragen
--crowdsec-proxy braucht einen Namen aus Buchstaben, Ziffern, . _ -	Leerzeichen oder Sonderzeichen im Namen	den Namen des Proxys in ZPO verwenden
Auf diesem Proxy läuft keine LAPI	--crowdsec-proxy auf einem Proxy ohne LAPI	auf dem Proxy des Standorts ausführen, der mit --crowdsec eingerichtet wurde
Die LAPI kennt noch keine Anmeldung weiterer Proxys	Die LAPI hat noch keinen Zugang für Proxys	setup-haproxy.sh einmal ohne weitere Optionen auf dem LAPI-Proxy ausführen, dann --crowdsec-proxy wiederholen
… hatte schon einen Zugang — er wird ersetzt (Warnung)	Ein Proxy mit diesem Namen wurde schon angelegt	Nur sinnvoll, wenn der Zugang verloren ging. Ist der Proxy schon angebunden, holt sein Bouncer nichts mehr ab, bis der neue Befehl dort gelaufen ist
zum ersten Anbinden braucht es --crowdsec-token	Der Befehl für den neuen Proxy ist unvollständig kopiert	den vollständigen Befehl von --crowdsec-proxy verwenden
der CrowdSec-Hub ist nicht erreichbar (hub.crowdsec.net)	Der Knoten kommt nicht ins Internet, oder eine Firewall blockt	Ausgang auf hub.crowdsec.net und packagecloud.io freigeben, dann das Skript erneut starten; es holt die Collections nach
die erzeugte Konfiguration ist ungültig — nichts geändert	haproxy -c lehnt die neue Konfiguration ab	die Meldung darüber lesen; meist eine eigene Änderung an haproxy.cfg oder ein fremdes Zertifikat. Die alte Datei bleibt stehen
die Schnittstelle antwortet nicht	Data Plane API läuft nicht oder lauscht woanders	systemctl status dataplaneapi und journalctl -u dataplaneapi -n 50
zpo_hosts.map taucht in der Runtime nicht auf (Warnung)	HAProxy hat die Datei nicht übernommen	systemctl reload haproxy und den Lauf wiederholen
die LAPI des Standorts antwortet nicht	Die LAPI ist auf dem Ziel-Proxy nicht erreichbar	auf dem LAPI-Proxy systemctl status crowdsec; dann Firewall und Adresse prüfen
der Lesezugang zpo-monitor wird abgewiesen / der Maschinen-Zugang zpo-sync wird abgewiesen	Die Zugänge in der LAPI fehlen oder stimmen nicht mit der Zugangsdatei überein	Skript erneut laufen lassen; bleibt es, die Zugänge in /root/haproxy-credentials mit der LAPI vergleichen
zpo-captcha ließ sich nicht installieren (Warnung)	Die Paketquelle ist nicht erreichbar oder das Paket fehlt	--repo <adresse> mit der Adresse der Paketquelle angeben; danach das Skript erneut ausführen. Bis dahin bekommen auffällige Adressen keine Prüfseite
--allow-from wirkt nur mit aktivem ufw — die Ports sind offen (Warnung)	ufw ist nicht aktiv, die Freigabe fehlt	Firewall einrichten oder den Knoten im Netz abschirmen
ufw nicht aktiv — 5555/tcp muss anderweitig erreichbar sein	Keine Firewall auf dem Knoten	Der Port muss durch die Netzfirewall erreichbar sein, nur für ZPO

Nach dem Lauf prüfen

Auf dem Knoten, mit den Zugangsdaten aus /root/haproxy-credentials:

systemctl is-active haproxy dataplaneapi
curl -fsS --cacert /etc/zpo-tls/cert.pem -u zpo:<passwort> https://<verwaltungs-ip>:5555/v3/info

Mit --crowdsec außerdem:

systemctl is-active crowdsec crowdsec-spoa-bouncer zpo-captcha
cscli lapi status
cscli bouncers list
curl -fsS --cacert /etc/zpo-tls/cert.pem https://<verwaltungs-ip>:8080/health

Die Ausgabe von cscli bouncers list sollte den SPOA-Bouncer mit einem frischen „Last API pull” zeigen. ZPO prüft dieselben Punkte im Verbindungstest des Knotens und meldet, was fehlt.

Stolpersteine im Betrieb

ZPO meldet den Knoten nach der Umstellung auf TLS als gestört

Bis ZPO die neue Adresse und den Fingerabdruck kennt, scheitert jede Verbindung: der Knoten spricht nur noch https, ZPO spricht noch http, oder ZPO prüft das Zertifikat gegen einen alten Fingerabdruck. Abhilfe:

1. Den Fingerabdruck des Knotens ablesen:

   sudo openssl x509 -noout -fingerprint -sha256 -in /etc/zpo-tls/cert.pem

   Die Ausgabe ohne Doppelpunkte in ZPO eintragen (ZPO nimmt beides an).

2. In ZPO den Knoten auf https://<verwaltungs-ip>:5555 stellen und den Fingerabdruck eintragen. Hat der Standort CrowdSec, die LAPI ebenso (https://<verwaltungs-ip>:8080).

3. Den Verbindungstest laufen lassen. Ist der Knoten wieder erreichbar, ist alles in Ordnung.

Schlägt der Test mit einer Meldung über den Fingerabdruck fehl, stimmt der Wert in ZPO nicht mehr mit dem Zertifikat überein. Das passiert nach einer Änderung der Verwaltungsadresse (dann gibt es ein neues Zertifikat) oder wenn ein anderer Rechner unter dieser Adresse antwortet. Den Ablesewert oben vergleichen, bevor man ihn überschreibt.

Der Firewall-Bouncer holt nach der Umstellung auf TLS keine Sperren mehr

Ein Firewall-Bouncer wie cs-routeros-bouncer gehört nicht zum Skript und zeigt nach der Umstellung noch auf http://…:8080. Sein Journal meldet dann Client sent an HTTP request to an HTTPS server, nach der Änderung auf https:// zunächst x509: certificate signed by unknown authority. Abhilfe: api_url auf https:// stellen und dem Zertifikat über SSL_CERT_FILE vertrauen (siehe Knoten einrichten → Firewall-Bouncer). Danach trägt der Bouncer die verpassten Sperren beim ersten Abgleich nach.

Der HAProxy-Container fällt nach einer Änderung an zpo-captcha aus

Läuft zpo-captcha als program im HAProxy-Container und bekommt Optionen, die seine Binary nicht kennt (etwa -tls-cert mit einer Binary vor 0.10), beendet es sich mit Exit 2. HAProxy nimmt mit exit-on-failure alle Programme und Worker mit, und der Container startet in einer Schleife neu. Abhilfe: die Optionen sofort wieder entfernen und den Container neu starten, dann die Binary aus dem passenden Paket einsetzen und die Optionen erneut setzen.

ZPO meldet „Grundkonfiguration veraltet”

Nach einem Update von ZPO brauchen die Knoten neue Maps und Regeln. Das Setup-Skript mit denselben Optionen erneut ausführen. Es erzeugt kein neues Passwort, und Agent und Bouncer bleiben bestehen.

Nach dem Einschalten der Firewall ist der Knoten in ZPO nicht mehr erreichbar

Ist ufw aktiv, lässt es nur die Ports durch, die eine Regel nennt. Die Regeln für ZPO setzen, nur für dessen Adresse:

sudo ufw allow from <ip-von-zpo> to any port 5555 proto tcp
sudo ufw allow from <ip-von-zpo> to any port 8080,6060,5556 proto tcp

Dann mit --allow-from <ip-von-zpo> das Skript erneut laufen lassen; es entfernt die offenen Freigaben aus früheren Läufen.

Das Passwort soll wechseln

Das Skript übernimmt das Passwort aus /root/haproxy-credentials. Zum Wechsel die Zeile password= in dieser Datei löschen und das Skript erneut starten. Es schreibt das neue Passwort in die Data Plane API und in die Steuerung von zpo-captcha (/etc/zpo-captcha/env). Danach das neue Passwort in ZPO am Knoten eintragen. Bis dahin meldet ZPO den Knoten als gestört, weil die Anmeldung fehlschlägt.

Die Data Plane API antwortet mit 404

HAProxy ist älter als 2.8 oder die Data Plane API ist nicht 3.x. ZPO spricht ausschließlich v3 (Pfad /v3). Installiert das Skript die richtige Version, fehlt der Fehler; sonst dataplaneapi --version prüfen.

Der Bouncer startet nicht: „permission denied” auf die .local-Datei

Der Bouncer läuft unter einer eigenen Gruppe und muss die Datei /etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml.local lesen dürfen. Sie braucht Besitzer und Rechte der Hauptdatei daneben. Ab Version 0.9.1 setzt das Skript das selbst; auf älteren Knoten von Hand:

sudo chown --reference=/etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml \
    /etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml.local
sudo chmod --reference=/etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml \
    /etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml.local
sudo systemctl restart crowdsec-spoa-bouncer

Dienste mit WAF zeigen eine Sperre statt der Prüfseite

Der Bouncer kennt für den Host * keinen Captcha-Anbieter, deshalb macht er aus „captcha” sonst ein „ban”. Das Skript legt in der .local-Datei den Host * mit fallback_remediation: captcha und appsec always_send an. Fehlt der Eintrag, das Skript erneut laufen lassen. Die Meldung „empty captcha provider” beim Start ist erwartet.

Die Prüfseite lässt sich nicht lösen

In dieser Reihenfolge prüfen:

1. Ist zpo-captcha eingerichtet? curl -i http://127.0.0.1:9200/.zpo-captcha/challenge antwortet mit 503 „not configured”, solange ZPO keine Einstellungen übertragen hat. ZPO tut das beim Abgleich — gegebenenfalls den Knoten in ZPO prüfen lassen.
2. Stimmt die Uhr des Knotens? Eine Aufgabe gilt zehn Minuten. Mit falscher Zeit ist sie beim Absenden schon abgelaufen. timedatectl status prüfen.
3. Blockt der Browser Skripte von /.zpo-captcha/? Dann ist es ein Werkzeug oder eine Erweiterung, die alles blockt, was nach Bot aussieht. Mit einem normalen Browser ohne Erweiterungen prüfen.
4. Ist der Schlüssel in /etc/haproxy/maps/zpo_captcha.map der von ZPO? Steht dort noch der Platzhalter, den das Skript beim ersten Lauf schreibt, kann kein Cookie gültig sein. Die Übertragung von ZPO ersetzt ihn.

Ein Monitor oder Uptime-Check bekommt die Prüfseite

Monitore (Uptime-Kuma und Ähnliche) laufen über dieselbe Adresse wie Besucher. Löst ein Monitor die Erkennung aus, sperrt CrowdSec ihn wie jeden anderen, und er sieht die Prüfseite statt des Dienstes — der Monitor meldet dann einen Ausfall. Abhilfe: die Adresse des Monitors als vertrauenswürdige IP-Gruppe in ZPO eintragen („nie von CrowdSec sperren”).

CrowdSec liest keine Logs

Ubuntu schreibt die HAProxy-Logs mit rsyslog in /var/log/haproxy.log. Läuft rsyslog nicht, liest CrowdSec die Zeilen aus dem Journal. Die Datei /etc/crowdsec/acquis.d/zpo-haproxy-journal.yaml gehört dann dazu. Läuft rsyslog wieder, die Datei entfernen — sonst liest CrowdSec jede Zeile doppelt. Die Lage zeigt cscli metrics (Zeilen gelesen gegen geparst).

Der Proxy lädt apt nicht, nur wegen HTTPS

Steht ein Cache-Proxy wie apt-cacher-ng davor, tunnelt er HTTPS oft nicht (403 CONNECT denied). Das Skript legt dann /etc/apt/apt.conf.d/99zpo-https-direct an, damit HTTPS-Quellen direkt gehen. Ohne diese Datei den Cache für CrowdSec umgehen.

Die Metriken werden von ZPO nicht gelesen

Die Metriken (Port 6060) laufen als HTTP ohne Anmeldung. Sie sind nur für das Netz von ZPO freigegeben. Kommt ZPO nicht heran, Freigabe für ZPO prüfen (siehe oben). Ohne Metriken sieht ZPO nicht, ob CrowdSec die Logs liest.

Ein Proxy eines Standorts hat keinen Bouncer

Der Zugang des Proxys zur LAPI ist ungültig, oder der Proxy ist nicht mehr angebunden. Auf dem LAPI-Proxy --crowdsec-proxy <name> erneut ausführen und den neuen Befehl auf dem Proxy laufen lassen. Der alte Zugang wird ersetzt.

Eine Änderung von Hand ist verschwunden

ZPO schreibt die haproxy.cfg über die Data Plane API um. Änderungen von Hand an der Datei gehen dabei verloren, und jeder Lauf des Skripts setzt die Grundkonfiguration wieder her. Änderungen, die bleiben sollen, über ZPO machen oder das Skript erweitern.

Zurück zum Stand vor dem Lauf

Vor jeder Änderung an haproxy.cfg legt das Skript ein Backup an (haproxy.cfg.bak-<datum>-<uhrzeit>). Die Datei ist die Ausgangskonfiguration; das Zurückspielen heißt: Datei zurückkopieren, haproxy -c -f prüfen, dann systemctl reload haproxy. Mit CrowdSec gibt es außerdem eine Sicherung von profiles.yaml (profiles.yaml.vor-zpo). Eine Rückkehr vor CrowdSec ist nur mit einem Backup des ganzen Knotens sauber.