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.

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.