Configuración del proxy en el agente de servidor

El agente de servidor de Kabeen transmite sus datos al backend mediante gRPC sobre TLS, hacia intake.kabeen.io únicamente por el puerto saliente 443/TCP. Cuando el servidor no dispone de acceso directo a Internet y debe pasar por un proxy corporativo (Zscaler, Squid, …), existen tres modos de funcionamiento. Este artículo describe cada uno de ellos.

Recordatorio. El agente vuelve a leer su archivo config.toml automáticamente cada 10 segundos: ningún cambio de configuración requiere reiniciar el servicio. Solo la importación de un certificado en el almacén de confianza del sistema requiere un reinicio (para que se vuelva a leer al arrancar).

Elegir el modo adecuado

Modo transparente (inspección TLS / MITM)

Es el modo predeterminado de Zscaler ZIA / ZTNA cuando el tráfico se enruta a nivel de red. No se requiere ninguna configuración proxy en el lado del agente.

La única condición es que el certificado raíz de inspección de su proxy esté presente en el almacén de confianza del sistema operativo. El agente lee este almacén al arrancar.

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 como administrador):

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

El reinicio solo es necesario para volver a leer el almacén de confianza: el agente no lo recarga sobre la marcha.

Modo explícito (HTTP CONNECT)

A utilizar cuando el proxy debe declararse explícitamente (sin enrutamiento transparente). El agente abre una conexión TCP hacia el proxy, envía una solicitud HTTP CONNECT intake.kabeen.io:443 y, a continuación, negocia el TLS de extremo a extremo dentro del túnel establecido.

Rellene el campo proxy en el archivo de configuración (/etc/kabeen-server-agent/config.toml en Linux, C:\ProgramData\Kabeen\Server Agent\config.toml en Windows):

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

Restricciones del campo proxy:

Limitaciones actuales (no admitidas). La autenticación del proxy (Basic, NTLM, Kerberos), la autoconfiguración PAC / WPAD y los proxies SOCKS5 no son compatibles.

Si su proxy exige autenticación, son posibles dos soluciones alternativas:

1. crear una regla de omisión de autenticación en el proxy para la IP de origen o para el destino intake.kabeen.io;
2. desplegar un proxy auxiliar local sin autenticación que reenvíe al proxy corporativo (por ejemplo, Squid con cache_peer + login=).

Mediante variables de entorno

A falta del campo proxy en config.toml, el agente respeta las variables de entorno estándar. El campo de config.toml sigue teniendo prioridad: si está presente, las variables de entorno se ignoran (incluida NO_PROXY).

• Se aceptan tanto las variantes en mayúsculas como en minúsculas.
• El puerto puede omitirse (se asumen 80 para http:// y 443 para https://).
• Formato de NO_PROXY: lista separada por comas. Cada entrada se compara por igualdad exacta o por sufijo — kabeen.io y .kabeen.io coinciden ambos con intake.kabeen.io. El valor * desactiva el proxy en todas partes.

Linux (systemd):

sudo systemctl edit kabeen-server-agent.service

Añadir (el drop-in crea /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

Luego recargar y reiniciar:

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

Windows (PowerShell como administrador):

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

Utilice obligatoriamente el ámbito Machine. Las variables definidas a nivel de User no son visibles para un servicio que se ejecuta como LocalSystem o bajo una cuenta virtual NT SERVICE\….

Verificación

Tras un cambio, el supervisor toma la nueva configuración en el siguiente ciclo (≤ 10 s). Inspeccione los registros:

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

Líneas esperadas cuando se utiliza el proxy:

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.

o, cuando una entrada NO_PROXY coincide y la conexión se realiza directamente:

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

Errores típicos (correlacionar con los registros del proxy):

Para la instalación inicial y la configuración de la clave de API, consulte Instalación manual del agente de servidor.