Configuring Thinfinity Primary Broker

This article presents the steps to configure the Thinfinity Primary Broker.

Registering Communications Gateway URLs

When the primary Gateway sits behind a load balancer, the Broker can be configured to hand out a Communications Gateway URL — the dedicated address used for the session data plane (WebSocket, file transfers, PDF viewer, virtual channels) instead of the load-balanced Gateway URL. The primary Gateway continues to serve the portal and web resources. Registering one or more Communications Gateway URLs is a Broker-side setting; for the Gateway-side counterpart (declaring the local gateway as a communications gateway), see Configuring Thinfinity Gateway.

Which Installations Need the List

The Communications Gateway list lives in each machine’s own settings.ini, and three kinds of processes read it there.

Each Broker process reads its own settings.ini and registers with the Communications Gateways it finds there. A Broker without the list doesn’t register with them, and sessions handled by that process aren’t reachable through the Communications Gateway — this applies to every Broker, primary and secondary.

The Agent service doesn’t register with the Communications Gateways, but it uses the addresses to build the Content-Security-Policy headers it serves, so that the browser is allowed to open the session connection to the Communications Gateway host. When the list is missing on an Agent, the policy falls back to the Agent’s own origin.

The session processes the Agent launches (RDP, VNC, and VirtualUI hosts) also depend on the Agent’s own settings.ini. When the Broker starts a session with url: '*' (see DefaultCommGatewayURL below), the session process expands that wildcard against its local file and registers with every Communications Gateway listed there. An Agent whose settings.ini is missing CommGatewayURL_N can’t have its session processes register with any Communications Gateway, even if the Broker’s own list is correct.

Configuring via settings.ini

When to use this method: on-premises deployments where the Gateway topology is managed manually, and you need to add or change Communications Gateway addresses after installation without reinstalling.

Edit settings.ini, located at:

Open it with a text editor running as administrator, and set the following keys in the [Broker] section:

[Broker]
CommGatewayURL_0=https://comm-gw-1.example.com:443/
CommGatewayURL_1=https://comm-gw-2.example.com:443/

# Strongly recommended whenever any Communications Gateway is registered.
# Points the browser at a single public session-data address — typically
# a load balancer in front of the Communications Gateways, but also used
# in single-Communications-Gateway deployments. See the key reference
# below.
DefaultCommGatewayURL=https://comm-nlb.example.com:443/

# Optional, index-aligned parallel list — use when the registration URL
# above is internal (for example, behind NAT) and the browser must reach
# the Communications Gateway through a different public address:
# PublicCommGatewayURL_0=https://public-comm-1.example.com:443/
# PublicCommGatewayURL_1=https://public-comm-2.example.com:443/

• CommGatewayURL_N — an indexed list of the Communications Gateway addresses the Broker registers with. The client uses one of these addresses at connection time for session data traffic. Numbering starts at _0 and must be contiguous — the Broker stops reading at the first gap, so an entry such as CommGatewayURL_3 after a missing _2 is ignored.
• PublicCommGatewayURL_N — optional. An index-aligned parallel list of the public-facing URLs the browser should use in place of the registration URLs above. Set this when the registration URL is an internal address (for example, a private IP behind NAT) and the browser must reach the Communications Gateway through a different public address. Must have the same length and order as CommGatewayURL_N — otherwise the list is ignored.
• DefaultCommGatewayURL — the public address the client is told to connect to for session data. A common use is a load balancer (NLB) sitting in front of the Communications Gateways, but the key is strongly recommended whenever any Communications Gateway is registered, including deployments with a single Communications Gateway and no load balancer. When this key is set, the Broker launches each session with url: '*', which tells the session process to register with every Communications Gateway listed in its own settings.ini; DefaultCommGatewayURL itself is not added to the registration set (an NLB address is not a registration endpoint). The URL is also used to build the browser’s Content-Security-Policy header. This key has no Configuration Manager equivalent — it can only be set in settings.ini.
• PublicDomain — optional. The explicit Domain attribute set on the GWSID cookie, overriding the value otherwise derived from the request URL. Set this when the primary Gateway and the Communications Gateway are hosted under names that do not share a parent domain by default — gw1.example.com and comm.example.com share .example.com automatically, but gw1.example.com and comm.different-domain.com do not. A value such as PublicDomain=.example.com scopes GWSID to the shared parent so the browser sends it to both hosts, which the Communications Gateway requires to recognise authorised browsers (see the “Confirm the browser cookie reaches both hosts” verification step below).

Every URL in these keys must include the scheme (http:// or https://), the host, the port, and a trailing slash: https://host:port/. This is the canonical form Configuration Manager writes, and the PublicCommGatewayURL_N substitution pairs entries by exact string match — a CommGatewayURL_N written in a non-canonical shape doesn’t pair with its PublicCommGatewayURL_N counterpart, and the public substitution is silently dropped. Use HTTPS on port 443 when the Communications Gateway has a TLS certificate installed; use HTTP on port 9443 when it doesn’t.

Save and close the file, then restart the Broker service for the new values to take effect.

DefaultCommGatewayURL vs. PublicGatewayURL

Both keys are public addresses, but they answer different questions and are read by different components, so they aren’t interchangeable.

How the Broker Picks a Communications Gateway

With one or two CommGatewayURL_N addresses registered, GeoIP distance lookup is off and the Broker distributes sessions among the registered Communications Gateways by pool load alone.

With three or more addresses, the Broker auto-enables GeoIP-based distance routing — even if [Protection] GeoIpEnabled is left at its default false. For each new session it measures the distance from the user’s browser to every registered Communications Gateway, keeps the ones within roughly 100 km of the one closest to that browser, and uses pool load as a tie-breaker within that set. The practical consequence is that a user is only routed to Communications Gateways that are nearly as close to them as the nearest one — so load distribution happens within each user’s local cluster of gateways, not across the full global list.

Configuring at Install Time or via Cloud Provisioning

When to use this method: cloud deployments provisioned from a VM template or auto-scaling group, or any scripted/unattended installation where hand-editing settings.ini after the fact isn’t practical.

The same setting is also available as the commGatewayUrls JSON parameter (paired with gatewayUrls for the primary gateway) — set at silent-install time as a command-line argument or a JSON file, or populated automatically on Azure and Oracle Cloud from instance metadata. See the JSON Parameters Reference and the Secondary Broker Forwarding Metrics example.

Verifying the Configuration

After registering Communications Gateway URLs, verify that the setup is active: