Proxy-Konfiguration für den Server-Agenten

Der Kabeen-Server-Agent übermittelt seine Daten per gRPC über TLS an das Backend, ausschließlich an intake.kabeen.io über den ausgehenden Port 443/TCP. Wenn der Server keinen direkten Internetzugang hat und über einen Unternehmens-Proxy (Zscaler, Squid, …) gehen muss, stehen drei Betriebsmodi zur Verfügung. Dieser Artikel beschreibt jeden davon.

Hinweis. Der Agent liest seine Datei config.toml automatisch alle 10 Sekunden neu ein: Keine Konfigurationsänderung erfordert einen Neustart des Dienstes. Nur der Import eines Zertifikats in den Vertrauensspeicher des Systems erfordert einen Neustart (damit es beim Start erneut eingelesen wird).

Den richtigen Modus wählen

Transparenter Modus (TLS-Inspektion / MITM)

Dies ist der Standardmodus von Zscaler ZIA / ZTNA, wenn der Datenverkehr auf Netzwerkebene geroutet wird. Auf Agentenseite ist keine proxy-Konfiguration erforderlich.

Die einzige Voraussetzung ist, dass das Stamm-Inspektionszertifikat Ihres Proxys im Vertrauensspeicher des Betriebssystems vorhanden ist. Der Agent liest diesen Speicher beim Start.

Linux (Debian / Ubuntu):

sudo cp zscaler-root.crt /usr/local/share/ca-certificates/zscaler-root.crt
sudo update-ca-certificates
sudo systemctl restart kabeen-server-agent.service

Linux (RHEL / Rocky / Alma):

sudo cp zscaler-root.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
sudo systemctl restart kabeen-server-agent.service

Windows (PowerShell als Administrator):

Import-Certificate -FilePath C:\Temp\zscaler-root.cer `
    -CertStoreLocation Cert:\LocalMachine\Root
Restart-Service KabeenServerAgent

Der Neustart ist nur erforderlich, um den Vertrauensspeicher neu einzulesen: Der Agent lädt ihn nicht zur Laufzeit neu.

Expliziter Modus (HTTP CONNECT)

Zu verwenden, wenn der Proxy explizit angegeben werden muss (kein transparentes Routing). Der Agent öffnet eine TCP-Verbindung zum Proxy, sendet eine HTTP CONNECT intake.kabeen.io:443-Anfrage und handelt anschließend Ende-zu-Ende-TLS innerhalb des aufgebauten Tunnels aus.

Tragen Sie das Feld proxy in der Konfigurationsdatei ein (/etc/kabeen-server-agent/config.toml unter Linux, C:\ProgramData\Kabeen\Server Agent\config.toml unter Windows):

api_key = "IHR_KABEEN_API_KEY"
proxy   = "http://proxy.corp.example:8080"

Einschränkungen des Felds proxy:

Aktuelle Einschränkungen (nicht unterstützt). Proxy-Authentifizierung (Basic, NTLM, Kerberos), PAC-/WPAD-Autokonfiguration sowie SOCKS5-Proxys werden nicht unterstützt.

Wenn Ihr Proxy eine Authentifizierung erfordert, sind zwei Umgehungslösungen möglich:

1. eine Regel zur Umgehung der Authentifizierung auf dem Proxy für die Quell-IP oder das Ziel intake.kabeen.io erstellen;
2. einen lokalen, nicht authentifizierten Hilfs-Proxy bereitstellen, der an den Unternehmens-Proxy weiterleitet (zum Beispiel Squid mit cache_peer + login=).

Über Umgebungsvariablen

Fehlt das Feld proxy in config.toml, berücksichtigt der Agent die standardmäßigen Umgebungsvariablen. Das Feld in config.toml hat weiterhin Vorrang: Ist es vorhanden, werden die Umgebungsvariablen ignoriert (einschließlich NO_PROXY).

• Sowohl Groß- als auch Kleinschreibung werden akzeptiert.
• Der Port kann weggelassen werden (80 für http://, 443 für https:// werden dann angenommen).
• Format von NO_PROXY: durch Kommas getrennte Liste. Jeder Eintrag wird auf exakte Gleichheit oder Suffix abgeglichen – kabeen.io und .kabeen.io passen beide auf intake.kabeen.io. Der Wert * deaktiviert den Proxy überall.

Linux (systemd):

sudo systemctl edit kabeen-server-agent.service

Hinzufügen (das Drop-in erstellt /etc/systemd/system/kabeen-server-agent.service.d/override.conf):

[Service]
Environment=HTTPS_PROXY=http://proxy.corp:8080
Environment=NO_PROXY=.internal,localhost,127.0.0.1

Anschließend neu laden und neu starten:

sudo systemctl daemon-reload
sudo systemctl restart kabeen-server-agent.service

Windows (PowerShell als Administrator):

[Environment]::SetEnvironmentVariable('HTTPS_PROXY', 'http://proxy.corp:8080', 'Machine')
[Environment]::SetEnvironmentVariable('NO_PROXY',    '.internal,localhost,127.0.0.1', 'Machine')
Restart-Service KabeenServerAgent

Verwenden Sie unbedingt den Geltungsbereich Machine. Auf User-Ebene definierte Variablen sind für einen Dienst, der als LocalSystem oder unter einem virtuellen Konto NT SERVICE\… läuft, nicht sichtbar.

Überprüfung

Nach einer Änderung übernimmt der Supervisor die neue Konfiguration beim nächsten Tick (≤ 10 s). Prüfen Sie die Protokolle:

sudo journalctl -u kabeen-server-agent.service -f

Erwartete Zeilen, wenn der Proxy verwendet wird:

Configuration changed, restarting tasks.
Connected to Kabeen endpoint: https://intake.kabeen.io via proxy http://proxy.corp.example:8080
All tasks running. Agent is operational.

oder, wenn ein NO_PROXY-Eintrag passt und die Verbindung direkt erfolgt:

[proxy] target host 'intake.kabeen.io' matches NO_PROXY='.kabeen.io', going direct
Connected to Kabeen endpoint: https://intake.kabeen.io

Typische Fehler (mit den Proxy-Protokollen abgleichen):

Für die Erstinstallation und die Konfiguration des API-Schlüssels siehe Manuelle Installation des Server-Agenten.