How to Set Up Agent Tunnels

This page covers configuring, binding, and troubleshooting agent tunnels.

For an overview of when and why to use tunnels, see Agent Tunnels. For configuration parameter tables, see Agent Tunnel Reference.

Agent-Side Configuration

Add the server address to the agent configuration file using the simple one-line form:

ServerConnection = server.example.com
MasterServers = server.example.com

Multiple servers can be specified for redundancy by repeating the ServerConnection directive, one per server:

ServerConnection = server1.example.com
ServerConnection = server2.example.com
MasterServers = server1.example.com, server2.example.com

Each ServerConnection directive defines a separate tunnel.

ServerConnection only establishes the tunnel. You must also configure MasterServers, ControlServers, or Servers to authorize the server to send commands through the tunnel.

Advanced Configuration with [ServerConnection] Sections

For custom ports, certificates, or server fingerprint verification, use the section-based form:

[ServerConnection/primary]
Hostname = server1.example.com
Port = 4703
CertificateFile = /etc/nxagentd/agent-cert.pem
ServerCertificateFingerprint = E6:5A:5D:37:22:FC:EF:EA:4B:22:11:59:F4:35:B3:9C:07:C2:8A:C0:12:83:B0:38:A3:04:E7:B8:D3:6F:B0:82

[ServerConnection/backup]
Hostname = server2.example.com
Port = 4703

The section name after ServerConnection/ is an arbitrary identifier. Hostname is optional — if omitted, the section name itself is used as the hostname. Multiple [ServerConnection] sections can be defined for connections to different servers.

Additional parameters:

  • CertificateId — selects the agent certificate from the Windows certificate store instead of a file (Windows only)

  • Password — password for the private key of the certificate specified by CertificateFile or CertificateId

  • ServerCertificateFingerprint — expected SHA-256 fingerprint of the server certificate (64 hexadecimal digits, optionally colon-separated)

See Agent Tunnel Reference for all available parameters.

Server-Side Configuration

The server listens for agent tunnel connections on port 4703 by default. No additional server configuration is needed to accept tunnels, but you may want to adjust server configuration variables.

See Server-Side Variables for available settings.

Binding Agent Tunnels

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.

Manual Binding

  1. In the management client, navigate to Configuration > Agent Tunnels

  2. The list shows all active tunnels with their status (bound or unbound)

  3. Right-click an unbound tunnel and select Bind to node…​

  4. Select an existing node or create a new node for this agent

Automatic Binding with Hooks

Use the Hook::OpenUnboundTunnel hook to automatically bind tunnels. This is the recommended approach for large-scale deployments:

// Automatically bind tunnel to existing node matching the agent's hostname
hostname = $tunnel.systemName;
node = FindNodeBySysName(hostname);
if (node != null) {
    $tunnel.bind(node);
}

For more advanced logic, combine with node creation:

hostname = $tunnel.systemName;
node = FindNodeBySysName(hostname);
if (node == null) {
    // Create new node under "Infrastructure Services" using tunnel's IP address
    container = FindObject("Infrastructure Services");
    if (container != null)
        node = container.createNode(hostname, $tunnel.address.address);
}
if (node != null) {
    $tunnel.bind(node);
}

See Server Hooks for more hook examples.

Certificate Configuration

Agent-Side Certificate Validation

The agent can verify the server’s certificate chain for additional security. This prevents man-in-the-middle attacks by ensuring the agent only connects to trusted servers.

VerifyServerCertificate = yes
TrustedRootCertificate = /etc/nxagentd/ca-cert.pem

The TrustedRootCertificate parameter accepts a path to a CA certificate file (PEM format) or a directory containing CA certificates. It can be specified multiple times to trust multiple CAs:

TrustedRootCertificate = /etc/nxagentd/internal-ca.pem
TrustedRootCertificate = /etc/ssl/certs

When certificate verification is enabled (VerifyServerCertificate = yes or a server certificate fingerprint is configured), the agent also loads system CA certificates. The following platform-specific locations are tried in order, and only the first existing one is used:

  • /etc/ssl/certs (Ubuntu, Debian)

  • /usr/local/share/certs (FreeBSD)

  • /etc/pki/tls/certs (Fedora, RHEL, CentOS)

  • /etc/openssl/certs (NetBSD)

  • /var/ssl/certs (AIX)

When verification is not enabled, the server certificate is not checked at all.

For per-connection server certificate validation, use the ServerCertificateFingerprint parameter in the [ServerConnection] section.

Using Tunnels with Agent Proxy

Tunnels can be combined with agent proxy functionality. An agent that connects via tunnel can also serve as a proxy for other agents in its network segment:

# Agent at remote site connects to server via tunnel
ServerConnection = central-server.example.com
MasterServers = central-server.example.com
# This agent also proxies for other agents at the same site
EnableProxy = yes

Other agents at the remote site can then use this agent as a proxy. See Agent Proxies for details.

Monitoring Tunnel Status

Monitor tunnel health through:

  • Configuration > Agent Tunnels in the management client shows all tunnels, their state, uptime, and agent version

  • The node’s Communications tab shows whether the agent is reachable via direct connection or tunnel

  • Server events SYS_TUNNEL_OPEN and SYS_TUNNEL_CLOSED are generated on tunnel state changes

Troubleshooting

Tunnel Not Connecting

  1. Verify the agent can reach the server on port 4703: telnet server.example.com 4703

  2. Check the agent log for connection errors: look for tunnel entries

  3. Verify ServerConnection is set correctly in the agent configuration

  4. Enable debug logging on the agent: DebugLevel = 7

Tunnel Appears Unbound After Re-install

If the agent was re-installed or its data directory was cleared, the agent’s certificate is lost. The tunnel appears as a new unbound tunnel and needs to be re-bound:

  1. Delete the old node object (or unbind it from the old tunnel)

  2. Bind the new tunnel to the node

Tunnel Keepalive Failures

If tunnels drop frequently, check for network devices (firewalls, load balancers) that terminate idle TCP connections. Reduce the TunnelKeepaliveInterval on the agent below its default of 30 seconds:

TunnelKeepaliveInterval = 15