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 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 require a server restart. Certificate validity is read when issuing a certificate; the reissue interval is read when checking certificate renewal.

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.