|Manuals

Configuring Thinfinity Primary Broker

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

1

Set Thinfinity Workspace Role as Primary Broker

Launch the Thinfinity Configuration Manager, navigate to the Services tab, select Primary Broker, and select Apply.

2

Set the Network ID Parameter

In the General tab, go to the Gateways section and enter the same Network ID used during the Gateway configuration.

3

Add Users and Permissions

In the Permissions tab:

  • Select Add in the Users and groups section.
  • Search and select the users or groups to be granted access.
  • Configure access by enabling the appropriate permissions.
4

Commit Changes

Select Apply to save the configuration.

Important

All Thinfinity Workspace components must be installed on machines that belong to the same domain to ensure proper discovery and communication.

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.

Every Broker needs the same [Broker] entries.

Each Broker process reads its own settings.ini and registers with the Communications Gateways it finds there. A Broker without the list will not register with them, and sessions handled by that process will not be reachable through the Communications Gateway. Update every Broker installation — primary and secondary — not only the primary Broker.

Agents read the same entries, but they do not register with the Communications Gateways. On an Agent the addresses are used 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. Keep the lists in sync on Agent installations as well — when the list is missing, the policy falls back to the Agent’s own origin.

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:

C:\ProgramData\Cybele Software\Thinfinity\Workspace\DB\settings.ini

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/

# 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/

# Optional — a fallback Communications Gateway address (for example, a
# load balancer in front of the Communications Gateways):
# DefaultCommGatewayURL=https://comm-nlb.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 fallback Communications Gateway address the client is told to connect to when a profile does not resolve one of its own. A common use is a load balancer (NLB) sitting in front of the Communications Gateways. 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.
URL format

Every URL above 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 will not 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 does not.

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

Interaction with GeoIP

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.

That same flag also controls the GeoIP request filtering described in GeoIP Filtering, so with 3 or more Communications Gateways configured, that filtering is active as well, whether or not you set it explicitly.

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.

Note

Registering a Communications Gateway is Thinfinity Workspace’s built-in, by-design mechanism for gateway-side load-balancing on the Desktop Client path — the standard way the platform hands out a directly-reachable address when the primary Gateway sits behind a load balancer, rather than an advanced tuning knob. The configuration surface documented here reflects the current build; it is expected to become more automatic in future releases.

Verifying the Configuration

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

1

Check the getServerUrl response.

Make a request to GET /<vpath>/getServerUrl for any profile that runs through a Communications Gateway. The response body should contain a "gateway" field with the Communications Gateway URL — if the field is absent or empty, the Broker did not resolve a Communications Gateway for that profile.

2

Confirm on the browser side.

Open the browser’s developer console during a session and read the client state:

  • THIN.httpConnection — a non-empty URL pointing at the Communications Gateway host.
  • THIN.hasSecondaryGateway — true.

An empty httpConnection means the session is running same-origin against the primary Gateway; the Communications Gateway is not in effect.

3

Check traffic separation in DevTools.

On the browser’s Network tab during an active session, requests should split by host:

  • HTML, CSS, JavaScript, and other web resources — served from the primary Gateway (the page origin).
  • Session traffic — cmd?, ft/, the PDF viewer, and the WebSocket — served from the Communications Gateway host.

If every request goes to a single host, the traffic split is not active.

4

Check the gateway log on the Communications Gateway machine.

Every Broker should register cleanly against the Communications Gateway. A log line reading Invalid network ID indicates that the registering process has a Network ID that does not match the one configured on the Communications Gateway — see Configuring Thinfinity Gateway.