Installationshandbuch

Revisionshistorie

Inhaltsverzeichnis

1. Voraussetzungen
2. Installationsuebersicht
3. Phase 0: Repository klonen
4. Phase 1: Tailscale/Headscale
5. Phase 2: Cribl Stream
6. Phase 3: Cribl Edge
7. Post-Installations-Pruefungen
8. Rollback-Verfahren

1. Voraussetzungen

1.1 Hardware-Anforderungen

1.2 Software-Anforderungen

1.3 Netzwerk-Voraussetzungen

• HTTPS-Zugang zu cdn.cribl.io (Port 443) fuer den Download der Cribl-Pakete
• HTTPS-Zugang zu pkgs.tailscale.com (Port 443) fuer Tailscale-Installation
• Zugang zum Headscale-Server (URL in .env definiert)
• Ausgehende Verbindung zum Splunk-Host auf Port 8088 (HEC) und 9997 (S2S)
• Freie lokale Ports: 9000, 9420, 9997, 4200, 514

1.4 Berechtigungen

1.5 Umgebungsvariablen (.env)

Vor der Installation muss die Datei .env im Projektroot erstellt und konfiguriert werden. Eine Vorlage befindet sich in .env.example.

# Beispiel .env Konfiguration
CRIBL_VERSION=4.16.1
CRIBL_EDGE_HOME=/opt/cribl-edge
CRIBL_SERVICE_USER=cribl
CRIBL_SERVICE_GROUP=cribl
CRIBL_EDGE_MGMT_PORT=4200
CRIBL_STREAM_API_PORT=9000
CRIBL_ADMIN_USER=admin
CRIBL_ADMIN_PASSWORD=<sicheres_passwort>

HEADSCALE_URL=https://<headscale-server>
HEADSCALE_AUTH_KEY=<pre-auth-key>

SPLUNK_HOST=<splunk-host>
SPLUNK_HEC_PORT=8088
SPLUNK_HEC_TOKEN=<hec-token>

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

2. Installationsuebersicht

2.1 Installationsphasen

2.2 Skriptverzeichnis-Struktur

scripts/
  00-preflight-check.sh          # Systemvoraussetzungen pruefen
  01-install-tailscale.sh        # Tailscale + Headscale
  02-install-cribl-stream.sh     # Cribl Stream Installation (geplant)
  03-install-cribl-edge-linux.sh # Cribl Edge (Linux)
  09-uninstall-cribl.sh          # Deinstallation (geplant)
  lib/
    common.sh                    # Gemeinsame Hilfsfunktionen
    api-helpers.sh               # Cribl REST API Wrapper

3. Phase 0: Repository klonen

# Repository klonen
git clone <repository-url> IceDataEmphasise
cd IceDataEmphasise

# Umgebungsdatei erstellen
cp .env.example .env
# .env mit den korrekten Werten befuellen (siehe Abschnitt 1.5)
nano .env

4. Phase 1: Tailscale/Headscale

4.1 Zweck

Tailscale stellt ein verschluesseltes VPN-Overlay-Netzwerk bereit, ueber das die Cribl Stream Web-UI sicher erreichbar ist. Die Verbindung erfolgt zum selbstgehosteten Headscale-Koordinationsserver.

4.2 Ausfuehrung

# Skript: scripts/01-install-tailscale.sh
sudo ./scripts/01-install-tailscale.sh

4.3 Ablauf des Skripts

1. Distributions-Erkennung: Liest /etc/os-release aus, um die Distribution (Debian/Ubuntu) und den Codename (z.B. bookworm) zu bestimmen.
2. Repository hinzufuegen: Fuegt das offizielle Tailscale APT-Repository hinzu, inkl. GPG-Schluessel unter /usr/share/keyrings/tailscale-archive-keyring.gpg.
3. Paket installieren: Installiert das tailscale-Paket via apt-get.
4. Daemon starten: Aktiviert und startet tailscaled.service via systemd.
5. Headscale-Verbindung: Fuehrt tailscale up --login-server <HEADSCALE_URL> aus.
   • Mit HEADSCALE_AUTH_KEY: Automatische Registrierung
   • Ohne Auth-Key: Login-URL wird angezeigt, manuelle Freigabe in Headscale erforderlich
6. Verifikation: Zeigt den Tailscale-Status und die zugewiesene IPv4-Adresse an.
7. Firewall-Empfehlungen: Gibt iptables/ufw-Regeln aus, um Port 9000 auf das Tailscale-Interface zu beschraenken.

4.4 Erwartete Ausgabe

>>> Adding Tailscale package repository
[OK]    GPG key installed to /usr/share/keyrings/tailscale-archive-keyring.gpg
[OK]    APT source added
[OK]    Package index updated
>>> Installing Tailscale package
[OK]    Tailscale package installed: 1.76.1
>>> Starting tailscaled service
[OK]    tailscaled is running
>>> Connecting to Headscale
[OK]    tailscale up completed
>>> Verifying Tailscale connection
[OK]    Tailscale IPv4 address: 100.64.x.x

5. Phase 2: Cribl Stream

5.1 Preflight-Check

# Systemvoraussetzungen pruefen
sudo ./scripts/00-preflight-check.sh

5.2 Pruefliste des Preflight-Checks

Der Preflight-Check validiert folgende Punkte:

5.3 Cribl Stream Installation

# Cribl Stream installieren (Skript 02)
sudo ./scripts/02-install-cribl-stream.sh

5.4 Erwarteter Ablauf

1. Download: Die Download-URL wird dynamisch von https://cdn.cribl.io/dl/latest-x64 aufgeloest. Ein statisches URL-Muster funktioniert nicht, da die CDN-URLs einen Build-Hash enthalten (z.B. cribl-4.16.1-20904e45-linux-x64.tgz).
2. Extraktion: Entpacken nach /opt/cribl
3. Service-User: Benutzer cribl mit passender Gruppenzugehoerigkeit erstellen
4. Eigentuemer setzen: /opt/cribl dem cribl-Benutzer zuweisen
5. Systemd-Service: cribl.service erstellen, aktivieren und starten
6. Warten auf Port 9000: Sicherstellen, dass die Web-UI erreichbar ist
7. Initiale Konfiguration: Admin-Passwort setzen, API-Token generieren

5.5 Verifikation

# Service-Status pruefen
systemctl status cribl

# Web-UI Erreichbarkeit testen
curl -s -o /dev/null -w '%{http_code}' http://localhost:9000

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

6. Phase 3: Cribl Edge

6.1 Ausfuehrung

# Cribl Edge (Linux) installieren
sudo ./scripts/03-install-cribl-edge-linux.sh

6.2 Detaillierter Ablauf

Das Skript 03-install-cribl-edge-linux.sh fuehrt folgende Schritte durch:

1. Umgebung validieren:
   • Root-Rechte pruefen
   • Benoetigte Befehle vorhanden: curl, tar, systemctl, id, getent
   • Alle erforderlichen Umgebungsvariablen gesetzt: CRIBL_VERSION, CRIBL_EDGE_HOME, CRIBL_SERVICE_USER, CRIBL_SERVICE_GROUP, CRIBL_EDGE_MGMT_PORT
   • Service-User cribl existiert
2. Bestehende Installation pruefen: Falls bereits vorhanden, wird Benutzerbestaetigung eingeholt. Laufender Service wird gestoppt.
3. Tarball herunterladen: Von cdn.cribl.io, oder gecachte Version unter /tmp/ verwenden.
4. Entpacken: Nach /opt/cribl-edge mit Backup bestehender lokaler Konfiguration.
5. Managed-Edge konfigurieren: Schreibt cribl.yml mit distributed.mode: managed-edge und Master-Verbindung zu 127.0.0.1:4200.
6. Systemd-Service erstellen: cribl-edge.service mit:
   • Service-User/Group: cribl
   • Supplementaere Gruppen: systemd-journal, adm, docker (falls vorhanden)
     Systemd-Hinweis: Die SupplementaryGroups-Direktive in der systemd-Unit erwartet leerzeichen-getrennte Werte, nicht komma-getrennt: SupplementaryGroups=systemd-journal adm docker
   • Capabilities: CAP_DAC_READ_SEARCH, CAP_SYSLOG
   • Sicherheits-Hardening: ProtectSystem=full, ProtectHome=true
   • Limits: LimitNOFILE=65536, LimitNPROC=8192
7. Service starten: Aktivieren, starten und auf Registrierung beim Stream-Leader warten (Timeout: 90s).
8. Verifikation: Binary-Check, Service-Status, Eigentuemer-Pruefung, optionaler API-Check.

6.3 Managed-Edge Konfiguration

Die generierte Konfigurationsdatei /opt/cribl-edge/local/cribl/cribl.yml:

distributed:
  mode: managed-edge
  master:
    host: "127.0.0.1"
    port: 4200
    tls:
      disabled: true
    authToken: ""

6.4 Verifikation

# Service-Status
systemctl status cribl-edge

# Edge-Version pruefen
/opt/cribl-edge/bin/cribl version

# Edge-Registrierung im Stream pruefen (API)
curl -s -u admin:<passwort> http://localhost:9000/api/v1/edge/nodes | jq .

# Logs pruefen
journalctl -fu cribl-edge

7. Post-Installations-Pruefungen

7.1 Checkliste

• Tailscale verbunden: tailscale status zeigt Verbindung an
• Cribl Stream laeuft: systemctl is-active cribl gibt active zurueck
• Cribl Edge laeuft: systemctl is-active cribl-edge gibt active zurueck
• Stream Web-UI erreichbar: http://<tailscale-ip>:9000 zeigt Login-Seite
• Edge-Node im Stream sichtbar: Unter Manage Edge Nodes aufgelistet
• Alle 5 Ports offen: 9000, 9420, 4200, 8088 (ausgehend), 9997 (ausgehend)
• Splunk-Destinations erreichbar: Health-Check in der Stream-UI gruen
• Keine Fehler in den Logs: journalctl -u cribl --no-pager -n 50

7.2 Automatisierte Pruefung

# Schnellpruefung aller Services
for svc in tailscaled cribl cribl-edge; do
    printf "%-20s: %s\n" "$svc" "$(systemctl is-active $svc 2>/dev/null || echo 'nicht gefunden')"
done

# Port-Pruefung
for port in 9000 9420 4200; do
    if ss -tlnp | grep -q ":${port} "; then
        echo "Port $port: OFFEN"
    else
        echo "Port $port: GESCHLOSSEN"
    fi
done

8. Rollback-Verfahren

8.1 Cribl Edge deinstallieren

# Service stoppen und deaktivieren
sudo systemctl stop cribl-edge
sudo systemctl disable cribl-edge

# Systemd-Unit entfernen
sudo rm /etc/systemd/system/cribl-edge.service
sudo systemctl daemon-reload

# Installationsverzeichnis entfernen
sudo rm -rf /opt/cribl-edge

8.2 Cribl Stream deinstallieren

# Service stoppen und deaktivieren
sudo systemctl stop cribl
sudo systemctl disable cribl

# Systemd-Unit entfernen (falls manuell erstellt)
sudo rm /etc/systemd/system/cribl.service
sudo systemctl daemon-reload

# Installationsverzeichnis entfernen
sudo rm -rf /opt/cribl

8.3 Tailscale deinstallieren

# Verbindung trennen
sudo tailscale down

# Paket entfernen
sudo apt-get remove --purge tailscale
sudo rm /usr/share/keyrings/tailscale-archive-keyring.gpg
sudo rm /etc/apt/sources.list.d/tailscale.list
sudo apt-get update

8.4 Vollstaendige Deinstallation

8.5 Service-User bereinigen

# Nur ausfuehren, wenn der cribl-User nicht mehr benoetigt wird
sudo userdel cribl
sudo groupdel cribl 2>/dev/null || true