Agent Tunnels

Agent tunnels provide a secure communication channel when agents cannot accept inbound connections. Instead of the server connecting to the agent on port 4700, the agent initiates an outbound TLS connection to the server on port 4703. All subsequent communication flows through this persistent tunnel.

For setup and configuration instructions, see How to Set Up Agent Tunnels. For configuration parameter tables, see Agent Tunnel Reference.

When to Use Tunnels

Use agent tunnels in any of these scenarios:

  • Agents behind NAT or firewalls that block inbound connections

  • Cloud-hosted VMs without public IP addresses or with restrictive security groups

  • Remote sites connected via VPN where only outbound connections are allowed

  • Environments where opening inbound port 4700 on every managed host is impractical

How Tunnels Work

  1. The agent initiates a TLS connection to the server on port 4703

  2. A new agent has no certificate yet, so its first connection is anonymous and results in an unbound tunnel (not yet associated with a node)

  3. Once the tunnel is bound, the server issues a certificate to the agent; on subsequent connections the agent presents this certificate, the server validates it, and the tunnel is established as bound (linked to a node object)

  4. For bound tunnels, the server uses the tunnel for all polling and data collection as if connected directly

  5. The agent maintains the tunnel connection and automatically reconnects if the connection drops

Tunnel Binding

When an agent connects via tunnel for the first time, it creates an unbound tunnel. The tunnel must be bound to a node object before the server can use it for monitoring. Binding can be done manually through the management client or automatically using server hooks.

For detailed binding procedures, see Tunnel Binding in the how-to guide.

Server-Initiated TLS Tunnels

Agent tunnels can also be established in the opposite direction: instead of the agent connecting to the server on port 4703, the server connects to the agent’s standard listener port (4700) and upgrades the connection to TLS. The agent accepts both TLS and legacy protocol connections on the same port, detecting the protocol automatically. This provides TLS protection for directly reachable agents without changing firewall rules or configuring tunnel sections on the agent.

How it works:

  1. The agent generates a self-signed certificate for its listener on first use and stores it in its certificate directory.

  2. The server learns that an agent supports TLS during normal communication (or from a rejection when the agent is configured with RequireTLS = yes), and connects with TLS from then on, subject to the node’s TLS mode.

  3. On the first TLS connection, the server stores (pins) the SHA-256 fingerprint of the agent’s certificate on the node and generates the SYS_AGENT_TLS_CERT_PINNED event.

  4. On subsequent connections the presented certificate is compared to the pinned fingerprint; on mismatch the connection is refused and the SYS_AGENT_TLS_CERT_MISMATCH event is generated.

The TLS mode is configured per node on the Agent property page (TLS connection section): Disabled, Allowed (default — TLS is used once the agent is known to support it), or Required (no fallback to the legacy protocol). The pinned fingerprint is shown on the same page and can be cleared to reset pinning, for example after an agent reinstallation.

On the agent side, setting RequireTLS = yes in the agent configuration file makes the agent reject legacy protocol connections, forcing all connecting servers to use TLS.

Server-initiated TLS tunnels are not available through agent proxies — proxied connections use the legacy protocol, so RequireTLS should not be enabled on agents reachable only via a proxy. The Agent Tunnels view shows the direction of each tunnel, distinguishing agent-initiated from server-initiated tunnels.

For parameter and event details, see Server-Initiated TLS Tunnels reference.

Certificate Management

Agent tunnels use TLS certificates for mutual authentication.

If no CA certificate is configured, the server automatically generates a self-signed CA certificate, stored as PEM files in the cert/ subdirectory of the server’s data directory. The auto-generated CA certificate is regenerated automatically when it is within 30 days of expiry. When a tunnel is bound, the server issues a certificate to the agent, which is stored in the agent’s data directory and used for subsequent connections. The initial (unbound) connection is anonymous — the agent has no certificate yet; certificate validation applies to bound tunnels.

Agent certificates are automatically renewed before expiration as long as the tunnel is active. If an agent’s certificate expires or is lost, the tunnel appears as unbound and needs to be re-bound.

The agent can optionally verify the server’s certificate chain for additional security, preventing man-in-the-middle attacks.

For certificate configuration details, see Certificate Configuration and Certificate Lifecycle Reference.