Agent Tunnel Reference

This page lists all configuration parameters for agent tunnels.

For an overview of tunnels, see Agent Tunnels. For setup and troubleshooting guides, see How to Set Up Agent Tunnels.

Agent Configuration Parameters

ServerConnection Sections

Each tunnel is defined as a sub-section of the form [ServerConnection/<name>], one sub-section per tunnel:

[ServerConnection/primary]
Hostname = server1.example.com
Port = 4703

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

A bare [ServerConnection] section does not work: every key directly under it is parsed as a separate tunnel definition. Always use the [ServerConnection/<name>] sub-section form, or the flat single-line ServerConnection directive described below.

Parameter Default Description

Hostname

(sub-section name)

Server DNS name or IP address. If omitted, the sub-section name is used as the hostname.

Port

4703

TCP port for tunnel connection

CertificateFile

(none)

Path to agent certificate file (PEM format) for this connection

CertificateId

(none)

Certificate ID in the Windows Certificate Store (Windows only)

Password

(none)

Password for the certificate file

ServerCertificateFingerprint

(none)

Expected SHA-256 fingerprint of the server certificate (colon-separated hex). If set, the fingerprint is compared against every certificate in the server’s certificate chain during TLS handshake; the connection is accepted if any of them matches. Setting it also turns on full server certificate verification, so the server certificate or its CA must be in TrustedRootCertificate.

Global Tunnel Parameters

Parameter Default Description

ServerConnection

(empty)

Flat single-line form of a tunnel definition: address[:port][,certificate[%password]]. The part after the comma is a certificate file path with optional %password suffix, not a second server. To connect to multiple servers, repeat the ServerConnection directive once per server.

TunnelKeepaliveInterval

30

Interval in seconds between keepalive packets

Server-Initiated TLS Tunnels

For an overview, see Server-Initiated TLS Tunnels.

Agent Configuration Parameters

Parameter Default Description

RequireTLS

no

Reject incoming legacy protocol connections with a "TLS connection required" error, forcing servers to connect using a TLS tunnel. Has no effect if the agent was compiled without encryption support. Do not enable on agents reachable only through an agent proxy — proxied connections use the legacy protocol.

The agent’s listener certificate is self-signed, generated on first use, and stored in the agent’s certificate directory as listener.crt and listener.key. If the agent cannot save these files, a new certificate is generated on every restart and the fingerprint pinned on the server no longer matches.

Node TLS Mode

Set on the Agent property page of the node, TLS connection section:

Mode Behavior

Disabled

Server never initiates TLS connections to this agent; the legacy protocol is used.

Allowed

Server uses TLS once the agent is known to support it, and falls back to the legacy protocol otherwise. This is the default.

Required

Server always connects using TLS; fallback to the legacy protocol is not attempted.

Server-initiated TLS tunnels are not used for nodes that communicate through an agent proxy or nodes set to communicate only through an agent-initiated tunnel.

The Pinned certificate fingerprint field on the same page shows the SHA-256 fingerprint stored on first TLS connection; clear the field to reset pinning (for example, after reinstalling the agent).

Events

Event Severity Generated

SYS_AGENT_TLS_CERT_PINNED

Normal

When the agent certificate fingerprint is stored on the first TLS tunnel connection to the agent. Parameters: fingerprint, IP address.

SYS_AGENT_TLS_CERT_MISMATCH

Major

When the agent certificate does not match the fingerprint pinned on the node; the connection is refused. Parameters: expected fingerprint, actual fingerprint.

Server Configuration Variables

Variable Default Description

AgentTunnels.ListenPort

4703

Port for incoming tunnel connections

AgentTunnels.TLS.MinVersion

2

Minimum TLS version, given as the TLS minor version number (0 = TLS 1.0, 1 = TLS 1.1, 2 = TLS 1.2, 3 = TLS 1.3)

AgentTunnels.UnboundTunnelTimeout

3600

Time in seconds before an unbound tunnel times out

AgentTunnels.UnboundTunnelTimeoutAction

0

Action when unbound tunnel times out (see below)

AgentTunnels.Certificates.ValidityPeriod

90

Agent certificate validity period in days

AgentTunnels.Certificates.ReissueInterval

30

Certificate age in days after which the certificate of an active tunnel is reissued

AgentTunnels.NewNodesContainer

(empty)

Container name for auto-created nodes (used with timeout action 3)

AgentTunnels.BindByIPAddress

false

Also match by IP address when auto-binding tunnels
Changes to AgentTunnels.ListenPort, AgentTunnels.Certificates.ValidityPeriod, and AgentTunnels.Certificates.ReissueInterval take effect only after a server restart.

Unbound Tunnel Timeout Actions

The AgentTunnels.UnboundTunnelTimeoutAction variable controls what happens when an unbound tunnel remains unbound for longer than AgentTunnels.UnboundTunnelTimeout seconds:

Value Action Description

0

Reset tunnel

Disconnects the tunnel. The agent will reconnect and the timeout restarts. This is the default.

1

Generate event

Generates a SYS_UNBOUND_TUNNEL event and resets the timeout timer. The tunnel remains connected.

2

Bind to existing node

Attempts to match the tunnel to an existing node (see below). If no match is found, nothing happens: the tunnel stays connected and unbound, and matching is retried after the next timeout.

3

Bind or create node

Same as option 2, but if no matching node is found, a new node is created. New nodes are created unmanaged with primary IP address 0.0.0.0 and placed in the container named by AgentTunnels.NewNodesContainer; if that container is not found, the node is linked under Infrastructure Services.
With actions 2 and 3, tunnels that use externally provisioned certificates are shut down instead of being bound.

Node Matching for Automatic Binding

When automatic binding is enabled (actions 2 and 3), the server matches an unbound tunnel against existing nodes in three stages:

  1. Agent ID and hardware ID together

  2. Hardware ID alone

  3. Tunnel IP address, hostname, or system name compared against the node’s primary hostname or object name, with the node’s zone checked against the tunnel’s zone

Certificate Lifecycle

Server-Side Certificates

On first startup the server generates two certificates, stored as files in <DataDirectory>/cert/:

  • An internal CA certificate (ca_cert.pem and ca_key.pem) used to sign agent certificates

  • A server certificate (server_cert.pem) presented by the tunnel TLS listener

Agent Certificate

When a tunnel is bound, the server issues a certificate to the agent, signed by the internal CA. The agent stores it in its certificate directory as <hash>.crt and <hash>.key, where <hash> is the SHA-1 hash of the server hostname, and uses it for subsequent tunnel connections.

If an agent’s certificate expires or is lost, the tunnel will appear as unbound and needs to be re-bound.

Certificate Renewal

Agent certificates are automatically reissued as long as the tunnel is active:

  • AgentTunnels.Certificates.ValidityPeriod controls the certificate validity period (default: 90 days).

  • AgentTunnels.Certificates.ReissueInterval counts days since issuance: a certificate is reissued once its age reaches this many days (default: 30).

  • Independently of the reissue interval, a certificate that is within 30 days of expiry is always renewed; this threshold is hard-coded.