14 – Troubleshooting

Revisionshistorie

Inhaltsverzeichnis

1. Diagnose-Werkzeuge
2. Haeufige Probleme und Loesungen
3. Log-Dateien und ihre Bedeutung
4. Cribl Diagnostic Bundle erstellen
5. Support-Kontakte und Community-Ressourcen
6. FAQ (Haeufig gestellte Fragen)

1. Diagnose-Werkzeuge

1.1 Cribl CLI

Cribl Stream und Edge bieten ein Kommandozeilen-Interface fuer Diagnose und Management:

# Cribl Stream CLI - Allgemeine Befehle
/opt/cribl/bin/cribl status          # Service-Status anzeigen
/opt/cribl/bin/cribl version         # Installierte Version pruefen
/opt/cribl/bin/cribl mode            # Betriebsmodus (master/worker/single)
/opt/cribl/bin/cribl start           # Service starten
/opt/cribl/bin/cribl stop            # Service stoppen
/opt/cribl/bin/cribl restart         # Service neustarten
/opt/cribl/bin/cribl reload          # Konfiguration neu laden (ohne Restart)

# Cribl Edge CLI
/opt/cribl-edge/bin/cribl status
/opt/cribl-edge/bin/cribl version
/opt/cribl-edge/bin/cribl restart

1.2 Cribl REST API

# Authentifizierung - Token holen
TOKEN=$(curl -s -X POST http://localhost:9000/api/v1/auth/login \
    -H "Content-Type: application/json" \
    -d '{"username":"admin","password":"'"${CRIBL_ADMIN_PASSWORD}"'"}' | jq -r '.token')

# Health Check
curl -s http://localhost:9000/api/v1/health | jq .

# System-Informationen
curl -s -H "Authorization: Bearer ${TOKEN}" \
    http://localhost:9000/api/v1/system/info | jq .

# Inputs (Sources) auflisten
curl -s -H "Authorization: Bearer ${TOKEN}" \
    http://localhost:9000/api/v1/m/default/system/inputs | jq '.items[] | {id, type, disabled}'

# Outputs (Destinations) auflisten
curl -s -H "Authorization: Bearer ${TOKEN}" \
    http://localhost:9000/api/v1/m/default/system/outputs | jq '.items[] | {id, type}'

# Pipelines auflisten
curl -s -H "Authorization: Bearer ${TOKEN}" \
    http://localhost:9000/api/v1/m/default/pipelines | jq '.items[] | .id'

# Routes auflisten
curl -s -H "Authorization: Bearer ${TOKEN}" \
    http://localhost:9000/api/v1/m/default/routes | jq '.items[] | {id, name, pipeline, output}'

# Fleet / Edge-Gruppen auflisten
curl -s -H "Authorization: Bearer ${TOKEN}" \
    http://localhost:9000/api/v1/master/groups | jq '.items[] | .id'

# Worker-Status
curl -s -H "Authorization: Bearer ${TOKEN}" \
    http://localhost:9000/api/v1/master/workers | jq .

1.3 System-Diagnose-Kommandos

# Service-Status (systemd)
sudo systemctl status cribl
sudo systemctl status cribl-edge

# Prozesse pruefen
ps aux | grep cribl
pgrep -af cribl

# Port-Belegung pruefen
sudo ss -tlnp | grep -E '9000|9997|8088|10080'

# Netzwerk-Konnektivitaet
ping -c 3 10.10.0.66                            # Splunk-Host
nc -zv 10.10.0.66 8088                           # Splunk HEC Port
nc -zv 10.10.0.66 9997                           # Splunk S2S Port
curl -sk https://10.10.0.66:8088/services/collector/health  # HEC Health

# Festplattenspeicher
df -h /opt
du -sh /opt/cribl/state/queues/ 2>/dev/null      # Queue-Groesse
du -sh /opt/cribl/log/ 2>/dev/null               # Log-Groesse

# Speicher und CPU
free -h
top -bn1 | grep cribl

# Tailscale-Verbindung
tailscale status
tailscale ip -4

1.4 Cribl Diagnostics (diag)

# Diagnose-Informationen sammeln
/opt/cribl/bin/cribl diag

# Ausgabe: Erstellt ein tar.gz im aktuellen Verzeichnis mit:
# - Cribl-Logs
# - Konfiguration (bereinigt)
# - System-Informationen
# - Metriken-Snapshot

2. Haeufige Probleme und Loesungen

2.1 Problemuebersicht

# Port pruefen
sudo ss -tlnp | grep 9000

# Berechtigungen pruefen
ls -la /opt/cribl/
sudo chown -R cribl:cribl /opt/cribl

# Logs pruefen
sudo journalctl -u cribl --since "5 min ago" --no-pager
tail -50 /opt/cribl/log/cribl.log

# Konfiguration validieren
/opt/cribl/bin/cribl status

# Speicher pruefen
free -h

# Netzwerk pruefen
nc -zv <stream-host> 9000
curl -sk https://<stream-host>:9000/api/v1/health

# Edge-Konfiguration pruefen
cat /opt/cribl-edge/local/cribl/cribl.yml | grep -A5 "leader"

# Edge-Logs pruefen
tail -50 /opt/cribl-edge/log/cribl.log

# Firewall pruefen
sudo iptables -L -n | grep 9000

# Edge neu registrieren
sudo systemctl restart cribl-edge

# Splunk-Konnektivitaet pruefen
curl -sk https://10.10.0.66:8088/services/collector/health

# HEC-Token testen
curl -sk -X POST \
  https://10.10.0.66:8088/services/collector/event \
  -H "Authorization: Splunk ${SPLUNK_HEC_TOKEN}" \
  -d '{"event":"test","sourcetype":"manual"}'

# Routes in Cribl pruefen (API)
curl -s -H "Authorization: Bearer ${TOKEN}" \
  http://localhost:9000/api/v1/m/default/routes | jq .

# Destinations pruefen
curl -s -H "Authorization: Bearer ${TOKEN}" \
  http://localhost:9000/api/v1/m/default/system/outputs | jq .

# Live-Datenfluss in Cribl UI:
# Monitoring -> Sources -> Events anzeigen
# Monitoring -> Destinations -> Events anzeigen

# Ressourcenverbrauch pruefen
top -bn1 | head -20
ps aux --sort=-%mem | grep cribl

# Worker-Anzahl anpassen
# Cribl UI -> Settings -> System -> Worker Processes
# Empfehlung fuer NUC: 1-2 Worker

# Pipeline-Performance analysieren
# Cribl UI -> Monitoring -> Pipelines
# -> Verarbeitungszeit pro Pipeline pruefen

# Problematische Regex identifizieren
# Cribl UI -> Pipelines -> betroffene Pipeline
# -> Funktionen einzeln deaktivieren und testen

# Bei Memory Leak: Service neustarten
sudo systemctl restart cribl

# Queue-Status pruefen
du -sh /opt/cribl/state/queues/*
df -h /opt

# Destination-Konnektivitaet pruefen
nc -zv 10.10.0.66 8088
nc -zv 10.10.0.66 9997

# In Cribl UI:
# Destinations -> betroffene Destination
# -> Status und Fehlermeldungen pruefen

# Queue-Limit temporaer erhoehen
# Destinations -> Destination -> Queue Settings
# -> Max Queue Size erhoehen

# Alte Queue-Daten manuell bereinigen (Vorsicht!)
# Nur wenn Daten nicht mehr benoetigt werden:
# sudo rm -rf /opt/cribl/state/queues/<dest-id>/*

# Zertifikat pruefen
openssl s_client -connect 10.10.0.66:8088 \
  -servername 10.10.0.66 2>/dev/null | \
  openssl x509 -noout -dates -subject

# Zertifikats-Ablaufdatum pruefen
echo | openssl s_client -connect 10.10.0.66:8088 \
  2>/dev/null | openssl x509 -noout -enddate

# Trust Chain pruefen
openssl s_client -connect 10.10.0.66:8088 \
  -showcerts 2>/dev/null | grep "verify"

# Bei selbstsigniertem Zertifikat:
# In Cribl Destination -> TLS Settings
# -> "Reject Unauthorized" deaktivieren (nur PoC!)
# Oder: CA-Zertifikat in Cribl hinterlegen

# Cribl TLS-Konfiguration
ls -la /opt/cribl/local/cribl/auth/

# Neuen Token anfordern
curl -s -X POST \
  http://localhost:9000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"..."}' | jq .

# Token-Gueltigkeit pruefen
curl -s -H "Authorization: Bearer ${TOKEN}" \
  http://localhost:9000/api/v1/system/info | jq .

# Bei HTTP 429 (Rate Limiting): Warten
# Bei HTTP 401: Neuen Token holen
# Bei HTTP 404: API-Pfad pruefen
# Bei HTTP 500: Cribl-Logs pruefen

# API-Dokumentation
# http://localhost:9000/api/v1/docs

Haeufiger Fehler: ssl3_get_record:wrong version number

Fehlermeldung im Cribl-Log:

{"channel":"output:splunk_hec","level":"warn","message":"protocol error",
 "hint":"Check your configured Minimum and Maximum TLS versions",
 "error":"write EPROTO...ssl3_get_record:wrong version number"}

Loesung:

1. Pruefen, ob Splunk HEC TLS aktiviert hat:

   curl -s "http://<splunk>:8088/services/collector/health"   # HTTP
   curl -sk "https://<splunk>:8088/services/collector/health"  # HTTPS

2. Cribl HEC-Destination-URL entsprechend anpassen:

   # Via API
   TOKEN=$(curl -s -X POST "http://localhost:9000/api/v1/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"username":"admin","password":"admin"}' | jq -r '.token')
   curl -s -X PATCH "http://localhost:9000/api/v1/system/outputs/splunk_hec" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"id":"splunk_hec","type":"splunk_hec","url":"http://<splunk>:8088/services/collector"}'

3. Config committen und Cribl neu starten

2.2 Weitere haeufige Probleme

Script-Fehler: \\r: command not found

Symptom: Shell-Skripte brechen mit kryptischen Fehlern ab:

/bin/bash^M: bad interpreter: No such file or directory
# oder
$'\r': command not found

Ursache: Windows-Zeilenenden (CRLF) in den Skript-Dateien.

Loesung:

# Alle Skripte und .env auf Unix-Zeilenenden konvertieren
sed -i 's/\r$//' scripts/*.sh scripts/lib/*.sh splunk/*.sh .env .env.example

Edge meldet "Unauthorized" beim Verbinden mit Leader

Symptom: Cribl Edge startet, kann sich aber nicht mit dem Stream Leader auf Port 4200 verbinden. Im Edge-Log erscheint wiederholt "Unauthorized" oder "Other party ended the socket connection".

Bekanntes Problem: Die Managed-Edge-Authentifizierung ueber das authToken in cribl.yml und cribl.secret funktioniert in bestimmten Konstellationen nicht zuverlaessig.

Workaround:

• Cribl Stream im Single-Mode betreiben (statt Leader-Mode)
• Syslog-Input und Systemd-Journal direkt in Stream konfigurieren
• Einschraenkung: File-Monitor-Quellen sind nur ueber Edge verfuegbar

API-Authentifizierung schlaegt fehl (HTTP 401)

Symptom: API-Aufrufe mit -u admin:password geben HTTP 401 zurueck.

Moegliche Ursachen:

1. Basic Auth funktioniert nicht: Die Cribl API erwartet Bearer-Token-Authentifizierung, nicht HTTP Basic Auth. Token zuerst holen:

   TOKEN=$(curl -s -X POST "http://localhost:9000/api/v1/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"username":"admin","password":"admin"}' | jq -r '.token')
   curl -s -H "Authorization: Bearer $TOKEN" "http://localhost:9000/api/v1/system/inputs"

2. Standard-Passwort: Nach Neuinstallation ist das Passwort admin. Ein Bootstrap ueber users.json funktioniert in 4.16.x nicht zuverlaessig.
3. Token abgelaufen: Bearer-Tokens haben eine begrenzte Gueltigkeit (1 Stunde). Bei Ablauf neuen Token anfordern.

3. Log-Dateien und ihre Bedeutung

3.1 Cribl Stream Log-Dateien

3.2 Cribl Edge Log-Dateien

3.3 Systemd-Logs

# Cribl Stream systemd-Logs
sudo journalctl -u cribl --since "1 hour ago" --no-pager
sudo journalctl -u cribl --since "today" -p err --no-pager  # Nur Fehler

# Cribl Edge systemd-Logs
sudo journalctl -u cribl-edge --since "1 hour ago" --no-pager

# Echtzeit-Logs verfolgen
sudo journalctl -u cribl -f
sudo journalctl -u cribl-edge -f

3.4 Wichtige Log-Meldungen und ihre Bedeutung

4. Cribl Diagnostic Bundle erstellen

4.1 Automatisches Diagnostic Bundle

# Cribl Stream Diagnose erstellen
sudo /opt/cribl/bin/cribl diag

# Das Bundle wird als .tar.gz im aktuellen Verzeichnis erstellt
# Inhalt:
# - /log/          - Cribl-Logs (cribl.log, audit.log, etc.)
# - /conf/         - Konfiguration (bereinigt, ohne Secrets)
# - /metrics/      - Aktuelle Metriken-Snapshots
# - /system/       - OS-Informationen, Ressourcenverbrauch
# - diag-info.json - Zusammenfassung der Diagnose

4.2 Manuelles Diagnostic Bundle

Falls cribl diag nicht funktioniert, kann ein manuelles Bundle erstellt werden:

#!/usr/bin/env bash
# Manuelles Diagnostic Bundle erstellen

DIAG_DIR="/tmp/cribl-diag-$(date +%Y%m%d_%H%M%S)"
mkdir -p "${DIAG_DIR}"

echo "Sammle Diagnose-Informationen..."

# 1. System-Informationen
echo "--- System Info ---" > "${DIAG_DIR}/system-info.txt"
uname -a >> "${DIAG_DIR}/system-info.txt"
cat /etc/os-release >> "${DIAG_DIR}/system-info.txt"
free -h >> "${DIAG_DIR}/system-info.txt"
df -h >> "${DIAG_DIR}/system-info.txt"
uptime >> "${DIAG_DIR}/system-info.txt"

# 2. Cribl-Version und Status
/opt/cribl/bin/cribl version > "${DIAG_DIR}/cribl-version.txt" 2>&1
/opt/cribl/bin/cribl status > "${DIAG_DIR}/cribl-status.txt" 2>&1
systemctl status cribl > "${DIAG_DIR}/systemd-status.txt" 2>&1

# 3. Logs (letzte 1000 Zeilen)
tail -1000 /opt/cribl/log/cribl.log > "${DIAG_DIR}/cribl.log" 2>/dev/null
tail -500 /opt/cribl/log/audit.log > "${DIAG_DIR}/audit.log" 2>/dev/null
journalctl -u cribl --since "1 hour ago" --no-pager > "${DIAG_DIR}/journalctl.log" 2>/dev/null

# 4. Netzwerk
ss -tlnp > "${DIAG_DIR}/ports.txt" 2>&1
ip addr > "${DIAG_DIR}/network.txt" 2>&1

# 5. Prozesse
ps aux | grep cribl > "${DIAG_DIR}/processes.txt" 2>&1

# 6. Konfiguration (ohne Secrets)
cp -r /opt/cribl/local/cribl/ "${DIAG_DIR}/config/" 2>/dev/null
# Secrets entfernen
find "${DIAG_DIR}/config/" -name "*.yml" -exec \
    sed -i 's/password:.*/password: [REDACTED]/' {} \; 2>/dev/null
find "${DIAG_DIR}/config/" -name "*.yml" -exec \
    sed -i 's/token:.*/token: [REDACTED]/' {} \; 2>/dev/null

# 7. Queue-Status
du -sh /opt/cribl/state/queues/* > "${DIAG_DIR}/queue-status.txt" 2>/dev/null

# 8. Health Check
curl -s http://localhost:9000/api/v1/health > "${DIAG_DIR}/health.json" 2>/dev/null

# Bundle erstellen
tar czf "${DIAG_DIR}.tar.gz" -C /tmp "$(basename "${DIAG_DIR}")"
rm -rf "${DIAG_DIR}"

echo "Diagnostic Bundle erstellt: ${DIAG_DIR}.tar.gz"
echo "Groesse: $(ls -lh "${DIAG_DIR}.tar.gz" | awk '{print $5}')"

5. Support-Kontakte und Community-Ressourcen

5.1 Interne Ansprechpartner

5.2 Cribl Support

5.3 Splunk-Ressourcen

6. FAQ (Haeufig gestellte Fragen)

Allgemein

F: Was ist der Unterschied zwischen Cribl Stream und Cribl Edge?

A: Cribl Stream ist die zentrale Verarbeitungskomponente. Sie empfaengt Daten, verarbeitet sie in Pipelines und leitet sie an Destinations weiter. Cribl Edge ist ein leichtgewichtiger Agent, der auf den Quell-Systemen installiert wird und Daten sammelt (z.B. aus Systemd Journal, Log-Dateien). Im IceDataEmphasise-PoC laeuft Stream als zentraler Server und Edge als Agent auf dem gleichen NUC-Host.

F: Welche Cribl-Version wird im PoC eingesetzt?

A: Cribl Stream Version 4.16.1. Die genaue Version kann mit /opt/cribl/bin/cribl version geprueft werden.

F: Wie viele Log-Quellen sind konfiguriert?

A: 12 Log-Quellen sind konfiguriert, darunter Systemd Journal, SSH Auth, Apache Access/Error, Samba, Docker und weitere. Die Verifikationssuite (07-verify-deployment.sh) prueft, ob alle 12 Quellen aktiv sind.

Betrieb

F: Wie starte ich Cribl Stream neu, ohne Daten zu verlieren?

A: Die Persistent Queue speichert Events waehrend eines Restarts. Ein sudo systemctl restart cribl fuehrt zu einem kurzen Unterbruch (typischerweise 5-10 Sekunden), aber Events gehen nicht verloren, da sie in der Queue gepuffert werden.

F: Wie pruefe ich, ob die gesamte Pipeline funktioniert?

A: Fuehren Sie die Verifikationssuite aus: sudo ./scripts/07-verify-deployment.sh. Sie fuehrt ca. 20 Tests durch und zeigt eine Zusammenfassung mit PASS/FAIL fuer jeden Test.

F: Wo finde ich die Cribl-Konfigurationsdateien?

A: Die Konfiguration liegt unter /opt/cribl/local/. Wichtige Unterverzeichnisse:

• /opt/cribl/local/cribl/ – Systemkonfiguration (cribl.yml, auth)
• /opt/cribl/local/cribl/pipelines/ – Pipeline-Definitionen
• /opt/cribl/local/cribl/routes.yml – Route-Tabelle
• /opt/cribl/local/cribl/outputs/ – Destination-Konfigurationen
• /opt/cribl/local/cribl/inputs/ – Source-Konfigurationen

F: Wie kann ich Aenderungen an der Konfiguration rueckgaengig machen?

A: Cribl verwaltet Konfigurationen intern ueber Git. Ueber die Cribl UI (Settings → Versioning) koennen vorherige Versionen angezeigt und wiederhergestellt werden. Alternativ kann ein Backup wiederhergestellt werden (siehe Notfallhandbuch).

Troubleshooting

F: Die Verifikationssuite meldet "FAIL" bei einem Test. Was tun?

A: Die Detail-Spalte in der Testausgabe zeigt die Fehlerbeschreibung. Pruefen Sie zunaechst den spezifischen Fehler und verwenden Sie die Diagnose-Kommandos aus Abschnitt 1 dieses Dokuments. Bei Service-Fehlern starten Sie mit sudo journalctl -u cribl --since "5 min ago".

F: Wie kann ich testen, ob ein einzelnes Event korrekt verarbeitet wird?

A: Nutzen Sie die Preview-Funktion in der Cribl UI: Pipeline oeffnen → "Preview" klicken → Testdaten eingeben oder aus einer Quelle laden → Verarbeitungsergebnis pruefen. Dies ist besonders hilfreich bei Pipeline-Problemen.

F: Cribl zeigt "Backpressure" an. Was bedeutet das?

A: Backpressure bedeutet, dass eine Destination Events nicht schnell genug annimmt. Cribl drosselt daraufhin die Aufnahme von Events, um einen Queue-Ueberlauf zu verhindern. Pruefen Sie die Destination-Konnektivitaet und -Kapazitaet. Im Fall von Splunk: HEC-/S2S-Verbindung und Splunk-Indizierungsleistung pruefen.

F: Warum sehe ich doppelte Events in Splunk?

A: Haeufige Ursachen: (1) Mehrere Routes in Cribl matchen auf das gleiche Event und senden es an die gleiche Destination. Loesung: Route-Reihenfolge und Filter pruefen, final: true auf der korrekten Route setzen. (2) Edge und Stream sammeln die gleiche Quelle. Loesung: Sicherstellen, dass jede Quelle nur an einer Stelle konfiguriert ist.

F: Wie aktualisiere ich Cribl Stream auf eine neue Version?

A: Vor einem Update unbedingt ein Backup erstellen (siehe Notfallhandbuch). Das Update erfordert einen Change Request (siehe Compliance-Dokument). Ablauf: Service stoppen, neues Paket installieren, Service starten, Verifikation ausfuehren.