Configuring a proxy for the server agent

The Kabeen server agent sends its data to the backend over gRPC on TLS, to intake.kabeen.io on outbound port 443/TCP only. When the server has no direct Internet access and must go through a corporate proxy (Zscaler, Squid, …), three modes of operation are available. This article describes each of them.

Reminder. The agent re-reads its config.toml file automatically every 10 seconds: no configuration change requires restarting the service. Only importing a certificate into the system trust store requires a restart (so it is re-read at startup).

Choosing the right mode

Transparent mode (TLS inspection / MITM)

This is the default mode of Zscaler ZIA / ZTNA when traffic is routed at the network level. No proxy configuration is required on the agent side.

The only requirement is that your proxy's root inspection certificate be present in the operating system trust store. The agent reads this store at startup.

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 (administrator PowerShell):

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

The restart is only needed to re-read the trust store: the agent does not reload it on the fly.

Explicit mode (HTTP CONNECT)

Use this when the proxy must be declared explicitly (no transparent routing). The agent opens a TCP connection to the proxy, sends an HTTP CONNECT intake.kabeen.io:443 request, then negotiates end-to-end TLS inside the established tunnel.

Set the proxy field in the configuration file (/etc/kabeen-server-agent/config.toml on Linux, C:\ProgramData\Kabeen\Server Agent\config.toml on Windows):

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

Constraints on the proxy field:

Current limitations (not supported). Proxy authentication (Basic, NTLM, Kerberos), PAC / WPAD auto-configuration, and SOCKS5 proxies are not supported.

If your proxy requires authentication, two workarounds are possible:

1. create an authentication bypass rule on the proxy for the source IP or for the intake.kabeen.io destination;
2. deploy a local unauthenticated auxiliary proxy that relays to the corporate proxy (for example Squid with cache_peer + login=).

Via environment variables

In the absence of the proxy field in config.toml, the agent honors the standard environment variables. The config.toml field remains authoritative: if present, the environment variables are ignored (including NO_PROXY).

• Both uppercase and lowercase variants are accepted.
• The port may be omitted (80 for http://, 443 for https:// are then assumed).
• NO_PROXY format: comma-separated list. Each entry matches on exact equality or suffix — kabeen.io and .kabeen.io both match intake.kabeen.io. The value * disables the proxy everywhere.

Linux (systemd):

sudo systemctl edit kabeen-server-agent.service

Add (the drop-in creates /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

Then reload and restart:

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

Windows (administrator PowerShell):

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

Always use the Machine scope. Variables defined at the User level are not visible to a service running as LocalSystem or under a NT SERVICE\… virtual account.

Verification

After a change, the supervisor picks up the new configuration at the next tick (≤ 10 s). Inspect the logs:

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

Expected lines when the proxy is used:

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.

or, when a NO_PROXY entry matches and the connection goes direct:

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

Common errors (correlate with the proxy logs):

For the initial installation and API key configuration, see Manual Server Agent Installation.