Connect resources to an HA Proxy pool

A Connector registers through the public Proxy entry and keeps tunnels to distinct Proxy identities. Use this procedure with either Authority routing topology. The public LB carries registration and tunnels; Proxy peers and Authority addresses stay private.

Before you start

Input	IP-only example	Check
Ready Proxy pool	Public entry 203.0.113.10	Both Proxy backends ready; round-robin tunnel routing
Registration	https://203.0.113.10:50064	Join relay enabled on Proxies and advertised by every Authority
Trust	Approved cluster CA fingerprint	Obtain from the Authority operator through a trusted channel
Resource	SSH host demo-ssh, onward mode local	Catalogue entry and matching Connector backend
Identity	Unique name conn-1 and persistent state directory	Preserve this node's identity across restarts

For DNS public TLS, use https://gate.example.com:50061 and its public trust for the DNS variant of these registration commands. A private Authority registration certificate is independent of that public certificate.

Declare the resource and issue a token

On a provisioned Authority, as the deployment administrator:

gdsgate --config /etc/gdsgate/authority.toml authority set-resource demo-ssh \
  --kind ssh --onward-auth local
(umask 077
 gdsgate --config /etc/gdsgate/authority.toml authority create-token \
   --role connector > connector.token)
openssl x509 -in /etc/gdsgate/transport-ca.pem -noout -fingerprint -sha256

Transfer connector.token through the protected operator channel. Record the CA fingerprint separately. --serve declares what this node serves; it does not create the catalogue row. A successful registration does not grant a user access: the active policy must permit that user and resource.

Register and start

Choose a system service for a deployed Connector. A foreground installation is useful for a workstation or a temporary diagnostic run. Use separate state directories and node identities for separate installations.

Linux system serviceForeground on a workstationDocker Compose

On the Connector host in a root shell, with the transferred token:

CA_FINGERPRINT='<approved SHA-256 fingerprint>'
gdsgate join 203.0.113.10 --name conn-1 \
  --enroll-endpoint https://203.0.113.10:50064 \
  --enroll-fingerprint "$CA_FINGERPRINT" \
  --enroll-sni enroll.gdsgate.internal --route tunneled \
  --serve demo-ssh=ssh --recording central \
  --state-dir /var/lib/gdsgate/connector \
  --output /etc/gdsgate/connector.toml < connector.token
gdsgate setup change --connector-config /etc/gdsgate/connector.toml \
  --set connector:connector.proxy_connection_count=2 \
  --set connector:security.profile=pilot
gdsgate config check /etc/gdsgate/connector.toml --role connector
gdsgate --config /etc/gdsgate/connector.toml service install connector
systemctl start gdsgate-connector
rm connector.token
journalctl -u gdsgate-connector -n 50

The service needs its configuration and state under the service paths. Its sandbox does not grant access to a workstation's home directory. service install checks the shared /var/lib/gdsgate parent and prepares the role's private state. See service permissions.

Run as the account that will own this installation:

CA_FINGERPRINT='<approved SHA-256 fingerprint>'
gdsgate join 203.0.113.10 --name conn-workstation \
  --enroll-endpoint https://203.0.113.10:50064 \
  --enroll-fingerprint "$CA_FINGERPRINT" \
  --enroll-sni enroll.gdsgate.internal --route tunneled \
  --serve demo-ssh=ssh --recording central \
  --state-dir ~/.gdsgate/connector-ha-state \
  --output ~/.gdsgate/connector-ha.toml < connector.token
gdsgate setup change --connector-config ~/.gdsgate/connector-ha.toml \
  --set connector:connector.proxy_connection_count=2 \
  --set connector:security.profile=pilot
gdsgate config check ~/.gdsgate/connector-ha.toml --role connector
rm connector.token
gdsgate --config ~/.gdsgate/connector-ha.toml connector

Keep that process running while checking it from another terminal. A resource already owned by another Connector cannot be reassigned by starting this second installation. Use the intended serving node or follow node replacement.

Use the topology's Compose registration steps. join, setup change and config check have the same arguments; the launcher supplies the configuration and identity volume. Set connector.proxy_connection_count=2 before starting the Connector. Preserve that volume when recreating the container.

--recording central selects buffered delivery to Authority. For recordings kept on this node, use --recording disk. Delivery checks: recordings.

Verify admission and access

On the Connector host, using its actual configuration:

gdsgate --config /etc/gdsgate/connector.toml doctor --explain

For a foreground installation, use ~/.gdsgate/connector-ha.toml. The tunnel check must report 2 verified distinct Proxy nodes, 2 desired; the catalogue check must admit demo-ssh with onward_auth=local. Read the named checks: doctor can also infer other roles from this configuration, so unrelated local Authority checks do not describe the remote Authority group.

On Authority, verify the serving route:

gdsgate --config /etc/gdsgate/authority.toml authority list-resources
gdsgate --config /etc/gdsgate/authority.toml authority list-serving

Then perform an allowed native SSH operation and a denied one from a logged-in client. A catalogue row or serving=yes alone does not prove native access. Complete HA acceptance, including a new connection after one Proxy stops and delivery of the resulting recording.

Startup and failures

Message / symptom	Meaning	Action
INFO acquiring activation receipt before serving resource	This run has not obtained its capability receipt yet	Wait for renewal through the bootstrap relay
INFO activation receipt acquired; re-registering tunnel	Planned registration with the new receipt	Confirm both verified tunnels and admitted resources afterwards
not_in_catalog	No matching catalogue row	Declare the resource on Authority
mode_not_confirmed	Catalogue has no required SSH mode	Set the intended onward_auth or ssh_profile on Authority
Persistent gate_not_offered	Capability receipt has not made the resource admissible	Inspect renewal, activation and Authority errors; adding the existing row again does not obtain a receipt
owned_by_another_node	Another enrolled node owns the serving lease	Use that node or follow the node replacement procedure
Proxy identity could not be confirmed	Authority could not attest the actual TLS peer	Inspect relay, node registry and Authority logs; the tunnel remains unverified
Only one verified Proxy	LB affinity, unreachable backend, or duplicate Proxy identity	Check round-robin tunnel routing, separate identities and both readiness endpoints
UnknownIssuer during join	Registration CA is not trusted	Use the approved CA pin or --enroll-ca; inspect the endpoint and TLS name

Receipt acquisition happens on each process start, even when the persisted transport identity is reused. An identity lookup interrupted by a replaced relay can repeat its read within the call ceiling. Credential issuance and state-changing RPCs are not automatically replayed by that mechanism.

Restarting this process uses the same transport identity. A fresh token and --force are for deliberate node replacement, not recovery of a tunnel.