Node join¶

join --role authority installs an HA Authority using a restricted configuration permission. join --role proxy installs an enrolled Proxy. Connector and agent-host roles register transport identities.

Authority join¶

On an existing Authority host, issue a permission:

umask 077
sudo gdsgate authority tokens create --role authority > authority.token

Keep this file private. Transfer the permission to the joining host, then run:

sudo gdsgate join cluster.example.com --role authority --listen 10.0.0.2 \
    --start < authority.token

For unattended discovery with a private CA, add an approved --fingerprint. The command checks cluster identity and bootstrap capability before sending a proof. It receives the shared PostgreSQL connection, OIDC and security settings, keyring material and current peers in an encrypted recipient-bound response. No root, keyring file or ordinary Authority configuration is copied by hand.

Defaults: control 50051, registration 50050, platform authority.toml, platform state authority/keyring-sync. With no --listen, the command uses the sole active non-loopback IPv4. Multiple addresses require an explicit listener. Use --enroll-listen for a different individual registration address. The joining host's listeners are individual endpoints, never the public LB address.

--local-config supplies a private local template for provider declarations, custom registration TLS and host paths. Providers named by the shared settings must already be declared locally; provider commands and host credentials are not copied from another Authority. --output and --state-dir override paths. Initialization stays disabled on a joined Authority.

The permission assigns the Authority ID. --name and Connector backend options do not apply. Authority join requires verified HTTPS and refuses --insecure.

After a lost reply, retry the original command with the same permission and local inputs. The private intent retains the nonce and receiver keys. Once the verified encrypted response is saved, local installation can resume without another network exchange. Failed credential or configuration writes never replace an existing different root. Start occurs only after complete persistence. After installation, --if-missing validates the saved bindings without spending a new permission; --start also installs and starts its service.

Authority/pair permissions expire after 600 seconds by default. Keep the original permission for recovery after a saved response. A saved intent is bound to that exact permission, owner and local inputs: a newly issued permission cannot resume it. If the permission expires before a response is saved, issue a new permission for the same cluster, owner and role, then repeat the command with the same local inputs and state directory. The saved receiver keys, nonce and listeners are retained; Authority checks their membership before accepting the new proof. A refused replacement leaves the original intent in place. A saved response still requires the permission that authenticated it, including for offline recovery.

Proxy join¶

On an Authority with individual TLS listeners, issue a Proxy permission:

umask 077
sudo gdsgate authority tokens create --role proxy > proxy.token

On the joining host:

sudo gdsgate join cluster.example.com --role proxy --listen 10.0.0.2 \
    --start < proxy.token

Add an approved --fingerprint for unattended private-CA discovery. The command checks entry trust, cluster identity and Proxy bootstrap support before sending the permission. It receives authorized Authority peers and the full OIDC policy. An assigned Proxy identity is saved separately from Authority credentials.

Defaults: local public 50061, internal tunnel 50062, WebSocket 50063, registration relay 50064, peer relay 50065; all use the selected local IP. Without --listen, the sole active non-loopback IPv4 is selected. Multiple addresses require an explicit listener. The platform paths are proxy.toml and state proxy/. --name defaults to this host's name.

[proxy].public_addr records the common entry independently of local listeners. Authority membership refresh is enabled. Explicit local endpoint, peer and registration-trust overrides in --local-config are retained. The local security profile cannot lower the Authority's minimum. Deployment labels and metrics can be set with --profile and --metrics-listen.

For an entry using an independently issued public certificate, supply this host's public_cert_file and public_key_file in the private local template. The pair must match the accepted entry issuer and certificate name before permission redemption. A node transport certificate does not replace that pair.

A retained private key survives an uncertain enrollment reply. If that reply was lost, issue a fresh Proxy permission and retry with the original inputs; the registered identity stays the same. After the verified grant is saved, failed local writes resume offline with the original permission. Service startup occurs after identity and configuration persistence. --if-missing validates an installed identity without network enrollment; use setup change for edits.

Authority and Proxy on one host¶

Issue a permission on an existing HA Authority:

umask 077
sudo gdsgate authority tokens create --role pair > pair.token

On the new host:

sudo gdsgate join cluster.example.com --role pair --listen 10.0.0.3 \
    --start < pair.token

The command installs Authority first through recipient-bound encrypted delivery, then enrolls a separate Proxy using the installed Authority's credentials. No second permission or running local service is required to finish installation. Both roles use one accepted discovery result. Unknown private CA confirmation is optional with an approved --fingerprint; role selection stays explicit.

Authority defaults to this IP on 50051/50050; Proxy uses 50061–50065. --listen controls the public Proxy bind, while an explicit local Authority control endpoint in --local-config is retained. --enroll-listen overrides its individual registration listener. --name, deployment label and metrics apply to Proxy. Shared OIDC and security settings come from Authority.

Default configurations are platform authority.toml and proxy.toml; state is in separate platform authority/ and proxy/ directories. For Pair, --output names their configuration directory and --state-dir names their common state parent. Authority receiver/root credentials and Proxy transport keys remain separate. Authority storage, keyrings and provider commands are excluded from the Proxy document.

Local requirements and installation privilege are checked before root proof. If Proxy installation fails, the error identifies the completed Authority stage. Retry with the original inputs: the saved root response and accepted routes are retained. --if-missing checks installed bindings and missing keys; it does not recreate an identity. Services start only after both role documents and identities have been saved.

Connector and agent-host join¶

Global flags are in the CLI hub. Kinds gdsgate join --serve accepts:

ssh postgres mysql tcp mcp rdp

`gdsgate join <address>`¶

Registers a node and writes its configuration file and transport identity. Add --start to install, enable and start the Connector service on Linux or Windows. Without it, run gdsgate connector or install the service separately.

TOKEN_FILE="<provision-token-file>"
sudo cat -- "$TOKEN_FILE" | sudo gdsgate join acme.example.com \
    --serve prod-db=postgres@10.0.0.5:5432 \
    --serve jump-host=ssh connect

On Windows, from an elevated PowerShell prompt:

Get-Content -Raw $TOKEN_FILE | gdsgate join acme.example.com `
    --serve prod-db=postgres@10.0.0.5:5432 `
    --serve jump-host=ssh connect

Input: the cluster's entry address (host[:port], default port 50061) and a one-time join token (gdsgate authority tokens create --role connector). Output:

Path (Linux)	Path (Windows)	Contents
`/etc/gdsgate/connector.toml`	`%ProgramData%\gdsgate\connector.toml`	`[endpoints]`, `[enroll]`, `[connector]`, one `[[connector.backends]]` per `--serve`; the deployment label and health address when the flags set them
`/var/lib/gdsgate/connector/`	`%ProgramData%\gdsgate\state\connector\`	`transport.key` (mode `0600` on Linux; owner-and-`SYSTEM`-only ACL on Windows), `transport.crt`, `transport-ca.pem`, `cluster-id`, `node-metadata.json`; `registration-ca.pem` when discovery supplies a registration CA

New join tokens carry the cluster ID and authorized role. Join checks these against the verified bundle and registration listener before sending the token. A mismatch leaves the token unspent. The configuration saves cluster_id, and the transport identity retains the same binding when its certificate renews. An older registration listener without the identity capability refuses a bound token; existing opaque tokens keep their previous registration path.

Authority also returns the registered node ID, role and authentication mode with a successful enrollment. Join stores them in the private node-metadata.json file. Renewal preserves the node ID and role. Invalid metadata refuses the grant before writing the configuration or private key; invalid saved metadata stops identity reuse.

These are the paths the gdsgate-connector.service unit reads on Linux and the gdsgate-connector service reads on Windows.

To register and start the service in one command:

sudo cat -- "$TOKEN_FILE" | sudo gdsgate join acme.example.com \
    --serve prod-db=postgres@10.0.0.5:5432 --start

Get-Content -Raw $TOKEN_FILE | gdsgate join acme.example.com `
    --serve prod-db=postgres@10.0.0.5:5432 --start

Use root on Linux or an elevated PowerShell prompt on Windows. Linux requires an installed binary visible to systemd, a configuration outside home and temporary directories, a visible path for an explicit CA, and state under /var/lib/gdsgate/<directory>. These checks run before registration; a refused invocation leaves its token valid. --start is unavailable for agent-host and on other platforms, and conflicts with --print. Relative output and state paths become absolute so the service uses the same files from its own working directory.

If service installation or startup fails after registration, the configuration and identity remain saved. The error gives the retry command:

sudo gdsgate --config /etc/gdsgate/connector.toml service install connector --start

Alternatively, repeat the original join arguments with --if-missing --start. No token is needed. A running service is left running; configuration changes still require an explicit restart. A successful --start exits 0, including when registration was already current. It checks service startup and immediate exit; it does not wait for the cluster to mark resources as serving.

On Windows, a key rewritten by the service may have a service-only ACL. If --if-missing cannot read that identity, it refuses without spending a token. Use service install connector --start with the saved configuration to start the service; this keeps its key ownership and ACL intact.

With --role agent-host:

Path (Linux)	Path (Windows)
`/etc/gdsgate/agent-host.toml`	`%ProgramData%\gdsgate\agent-host.toml`
`/var/lib/gdsgate/agent-host/`	`%ProgramData%\gdsgate\state\agent-host\`

The file has [agent_host] and no backend list. It sets [endpoints].proxy_public (the Proxy listener agents open sessions through) and [client].transport_ca (the CA in the state directory) from values the cluster sends. When the Proxy's [endpoints].proxy_public is unset or a wildcard address, the cluster sends neither; set both by hand. See agent host. On Windows the agent host registers and starts but runs no agents; running agents is Linux-only.

The token is read from standard input; as an argument it is refused. It is spent by join and written to no file. The first line is the token, in UTF-8 with or without a byte-order mark or in UTF-16 with one: what create-token ... > connector.token writes in PowerShell 7 and Windows PowerShell 5.1. Standard input is read to the end even when no token is needed, so a loop that pipes one on every pass gets no broken pipe.

Before the token is read, join checks that it can write the state directory (each identity file it would replace, or the nearest existing directory above a new one) and the directory of the configuration file. A refusal names the path and the error, for example cannot write the transport identity at /var/lib/gdsgate/connector: Permission denied (os error 13); nothing is sent and the token stays valid.

Without --enroll-endpoint, join reads the public bundle at the given address. The verified registration capability must support the selected role. A Proxy with public_join enabled advertises registration on that same listener. No proxy. prefix is added. A server that advertises no registration capability requires an explicit --enroll-endpoint.

A certificate trusted by this host needs no confirmation. For an unknown CA, join shows its SHA-256 fingerprint and asks for confirmation on the controlling terminal. Enter declines. It reads the answer separately from stdin, which holds the join token. Without a controlling terminal and terminal stderr, supply an approved --fingerprint; discovery otherwise refuses. --sni selects the public bundle's TLS name.

For an IP-only cluster with public_join and enrolled Proxy transport TLS, the public bundle supplies its CA. With no advertised name or --sni, discovery verifies proxy.gdsgate.internal; registration on the same listener reuses that verified name and CA:

CA_FINGERPRINT='<approved public bundle CA fingerprint>'
sudo cat -- "$TOKEN_FILE" | sudo gdsgate join 203.0.113.10 \
    --fingerprint "$CA_FINGERPRINT" --serve demo-ssh=ssh --start

Registration uses its own verified CA and TLS name. Discovery saves a supplied registration CA to <state-dir>/registration-ca.pem, separate from the node's transport-ca.pem. --enroll-ca, --enroll-fingerprint and --enroll-sni explicitly override registration trust; they do not verify public discovery. The registration TLS connection is checked before any token is sent.

The registration answer supplies the gateway's connector addresses, the route to Authority and the renewal address; --route replaces the last two. See What the cluster tells a registering node. When the answer lacks a value, join names what is missing and derives no address.

Resources come only from the command line. Each --serve takes <resource>=<kind>[@<addr>]; ssh may omit the address (the connector terminates it). Each id needs a matching catalogue entry, or the gateway closes the connector's tunnel; see Resource catalog lifecycle.

Flags:

Flag	Effect
`--role {connector\\|agent-host\\|authority\\|proxy\\|pair}`	Role the permission was issued for. Default `connector`; `pair` installs separate Authority and Proxy identities. Authority, Proxy and pair installation are described above.
`--name <NAME>`	Node name in the registry (`[enroll].node_name`) and at the gateway (`[connector].id`); one string for both. Default: the host's fully qualified name, printed by the run.
`--serve <SPEC>`	A resource this node serves. Repeatable. Kinds: `ssh`, `postgres`, `mysql`, `tcp`, `mcp`, `rdp`. `cockroach` is rejected; declare a CockroachDB backend in `--backends-file`.
`--backends-file <PATH>`	TOML fragment with `[[connector.backends]]` entries only, for backends `--serve` cannot express: a Kubernetes API with its bundle and service-account token, CockroachDB, a model service addressed by base URL, a jump host with pinned host keys.
`--fingerprint <SHA256>`	Approved CA fingerprint for public bundle discovery. Required for unattended discovery with an unknown CA. Conflicts with `--enroll-endpoint`.
`--sni <NAME>`	Public bundle TLS name. Independent from registration SNI; conflicts with `--enroll-endpoint`.
`--enroll-ca <PATH>`	Explicit PEM anchor for the registration listener. Overrides registration metadata. Without an override, discovery selects registration trust; explicit endpoints use system roots.
`--enroll-fingerprint <SHA256>`	SHA-256 fingerprint of the cluster CA that issued the registration certificate: `transport_ca.fingerprint` from `setup prepare`, the value clients pass to `gdsgate connect --fingerprint`. For a gateway reached by IP address (`enroll_cert_from_cluster_ca`). The listener's chain is read before the token; a chain without that CA is refused with the token unspent. Writes `[enroll].transport_ca` = `<state-dir>/transport-ca.pem`, the cluster CA bundle renewal keeps current. With `--enroll-ca`, `--insecure` or an `http://` endpoint: argument error.
`--enroll-sni <NAME>`	Name the registration certificate is checked against, and the TLS server name sent. Default: verified registration metadata, or the host in an explicit `--enroll-endpoint`. Written to `[enroll].transport_sni`. For a certificate issued for an internal name, e.g. `authority.internal`, reached through the join relay, or for the gateway's name on its client port dialled by address. An IP address or a control-plane transport name is an argument error. `enroll.gdsgate.internal` is accepted for registration; `proxy.gdsgate.internal` works on the public listener with enrolled Proxy TLS and `public_join`, but not on the separate join relay; `--insecure` with it is an argument error.
`--route {direct\\|tunneled\\|fronted}`	Route to Authority written to the connector's file. Default: the route the cluster sends. See the table below. `--role agent-host` with it is an argument error.
`--insecure`	Explicit cleartext registration. Public discovery allows it only on loopback. With an explicit endpoint, the existing manual cleartext route remains available. The token is sent without encryption.
`--enroll-endpoint <URL>`	Explicit registration URL. Skips public discovery, including its trust confirmation. An `https://` IP address sends the server name `enroll.gdsgate.internal` and checks the certificate against the address; see Registration at an IP address.
`--profile <LABEL>`	Deployment label on every metric series, log line and exported trace of this node (`profile`). Default: no label.
`--metrics-listen <ADDR>`	Address for `/healthz`, `/readyz` and Prometheus `/metrics` (`[telemetry].metrics_listen`). Plain HTTP; keep it on loopback unless read from another host. Default: off.
`--recording <disk\\|central>`	Where session casts go (`[recording].mode`): `disk` under `[enroll].state_dir`, `central` uploaded to Authority. Default: no `[recording]` section, connector default `disk`. An explicit `disk` writes the section, so `--if-missing` re-runs treat it as set. Any other value is an argument error.
`--output <PATH>`, `-o`	Write the configuration to this path.
`--start`	Install, enable and start the selected native services. Default off; requires root or an elevated prompt. Existing running services are not restarted. Unavailable for `agent-host`.
`--state-dir <DIR>`	Keep the identity in this directory. It must survive restarts.
`--print`	Render without network or writes. Without an explicit registration endpoint, leave it unresolved and mark it with a comment. Stdin is drained; no token is redeemed.
`--if-missing`	Connector/agent-host: reconcile the config from the complete arguments, retaining identity and saved registration trust; see re-join. Authority/Proxy/pair: validate saved installation bindings without applying a new template. Spend no new token. Without it, an existing configuration requires `--force`. Exit `3` when unchanged, or `0` with a successful `--start`. Connector registration address changes use the moving procedure.
`--force`	Connector/agent-host: overwrite the configuration and enroll a fresh identity. Authority/Proxy/pair: permit configuration replacement during the role-specific join or saved-state recovery; the flag does not transfer an owner, namespace or lost credentials. See the role instructions above.

Exit codes: 0 done, 3 nothing to change (--if-missing), 1 failed, 2 invalid arguments. With --start, successful installation and startup exit 0.

--route writes these keys. The registration address is the host:port selected by verified metadata or --enroll-endpoint: the Proxy's join relay, or its client port with public_join. Both pass renewal and control-plane calls to Authority.

`--route`	`[connector].authority_transport`	`[endpoints].authority`	`[enroll].renew_endpoint`
unset	from the cluster	from the cluster	from the cluster
`fronted`	`fronted`	the registration address	`https://` + the registration address
`direct`	`direct`	from the cluster	from the cluster
`tunneled`	`tunneled`	none	from the cluster when it sends `tunneled`, otherwise `https://` + the registration address

--route direct against a cluster that sends no Authority address, as with tunneled, is refused before the token is redeemed. Nothing is written and the token stays valid. An Authority older than this check refuses it after registration, with the token spent.

--if-missing with --route renews at the address the route writes. A node joined without --route fronted is fixed by the same command with --route fronted --if-missing; no token is needed, and the run names the restart it needs.

A connector of a gateway setup prepare wrote, registering and renewing on its client port; the cluster sends tunneled:

sudo cat -- "$TOKEN_FILE" | sudo gdsgate join gate.example.com \
    --enroll-endpoint https://gate.example.com:50061 \
    --serve demo-ssh=ssh

The same gateway at its address, with a certificate that carries IP:203.0.113.10 or, without that entry, with --enroll-sni gate.example.com:

sudo cat -- "$TOKEN_FILE" | sudo gdsgate join gate.example.com \
    --enroll-endpoint https://203.0.113.10:50061 --enroll-ca /etc/gdsgate/root.pem \
    --serve demo-ssh=ssh

A gateway reached by IP address alone, prepared with --join-relay and no --enroll-cert; the fingerprint is transport_ca.fingerprint from setup prepare:

CA_FINGERPRINT='<approved SHA-256 fingerprint>'
sudo cat -- "$TOKEN_FILE" | sudo gdsgate join 203.0.113.10 \
    --enroll-endpoint https://203.0.113.10:50064 \
    --enroll-fingerprint "$CA_FINGERPRINT" --enroll-sni enroll.gdsgate.internal \
    --serve demo-ssh=ssh

The same gateway with a registration certificate from your own CA (setup prepare --enroll-cert): --enroll-ca /etc/gdsgate/enroll-ca.pem in place of --enroll-fingerprint.

A connector behind a fronted gateway with public_join:

sudo cat -- "$TOKEN_FILE" | sudo gdsgate join gate.example.com \
    --enroll-endpoint https://gate.example.com:50061 --route fronted \
    --serve demo-ssh=ssh

A registration certificate for an internal name, through the join relay:

sudo cat -- "$TOKEN_FILE" | sudo gdsgate join gate.example.com \
    --enroll-endpoint https://gate.example.com:50064 \
    --enroll-sni authority.internal --enroll-ca /etc/gdsgate/enroll-ca.pem \
    --serve demo-ssh=ssh

Renewal does not read --enroll-sni: it is a mutual-TLS call to the control plane, checked against the cluster's CA.

--if-missing is for a loop on a timer:

State found	Action
Identity fresh	Kept; no token spent.
Identity near its expiry	Renewed over mutual TLS; no token spent.
Identity expired	Refused: an expired certificate cannot renew. `--force` with a fresh token.
Configuration differs from what the arguments render	Rewritten; the run names the service restart it needs. `join` does not restart anything.
Nothing differs	Nothing written; exit `3`. With `--start`, install/start the service and exit `0` on success.

A token piped in and not needed is read and discarded. --if-missing together with --force is refused.

--print performs no discovery or registration. It renders what the arguments determine, marks values supplied by the cluster, and parses as a configuration. Stdin is drained without using its token.

join does not:

Start anything without --start. The run prints commands for separate service installation. An agent host is run as gdsgate --config /etc/gdsgate/agent-host.toml agent-host.
Write catalogue rows. It prints them; on a host whose authority.toml names an administrative identity ([admin].identity_dir), with --config of that file.
Grant service access without --start. The service installer grants the service account access to its configuration and identity.
Accept an unknown CA silently. Public discovery requires terminal confirmation or an approved fingerprint. Registration then verifies its own selected trust.
Write configuration or identity on registration refusal: an unreachable listener, an unverified certificate, a refused token, or a cluster with nothing to advertise leaves the filesystem unchanged.

For deployment behind a Proxy LB, use the HA Connector steps: explicit configuration/state paths, matching catalogue mode, two verified Proxy identities and startup receipt checks.

A node that loses its state_dir needs a fresh token and registers as a second registry row. Persist that directory.

Re-join a connector¶

Choose whether to reuse this Connector or replace its identity. An installed Connector needs no new join for a restart or binary upgrade: keep its configuration and state directory, then restart its service.

Operation	Identity and resources
`join --if-missing` with valid saved identity	Reuses the existing Registry node, namespace and publication scope; no token spent. A leaf needing renewal uses mTLS.
`join --force` with a fresh token	Generates a new key and registers a new node. It does not recover the previous node's UUID, automatic namespace or manual assignments.
Missing state or expired identity	`--if-missing` refuses. Restore the original usable configuration/identity pair from protected backup, or enroll a replacement explicitly.

For a repeat on Linux, use the original paths and complete desired backend arguments. This example assumes the installation has only demo-ssh:

sudo gdsgate join gate.example.com --name conn-1 --if-missing \
  --output /etc/gdsgate/connector.toml \
  --state-dir /var/lib/gdsgate/connector \
  --serve demo-ssh=ssh < /dev/null

Reconciliation preserves additional backends, discovery sources, local settings and comments. New declarations are added by resource ID. A declaration that changes an existing backend is refused: use setup change --replace for an explicit update, or setup change --unserve for removal. Omission from a repeat join does not remove a backend. Fresh renewal settings update cluster-owned routes. For backend or discovery changes, use gdsgate reload --role connector; changes to identity or cluster routes require restart. Transport identity renewal alone needs no restart. --start installs and starts the service; it does not restart one already running.

For an automatic Connector, the previous namespace remains reserved. A forced join claiming the same name can fail with resource namespace is already reserved; that refusal rolls back enrollment and leaves the token unspent. Use an unused replacement name. Its automatically published resources have new qualified IDs and DNS names. Review policy references and client mappings; revoking the old node does not transfer its namespace to the replacement.

For manual resources, inspect and explicitly update serving assignments using the new Registry UUID. Legacy ownership can also prevent takeover until the old node is revoked or its ownership lease expires. That legacy timeout does not transfer automatic namespaces or explicit manual assignments.

Inspect the old and replacement rows on the administrator's host. Revoke the retired node when the intended cutover is ready:

gdsgate --config /etc/gdsgate/authority.toml authority nodes list
gdsgate --config /etc/gdsgate/authority.toml authority nodes revoke '<old-node-id>'

Stop the Connector before replacing its identity. Retain protected backups of its configuration and state for recovery; include pending recording deliveries. The platform steps below handle access to the service-owned state directory.

Host	Owner of the state directory	Steps
Linux	the unit's transient account; root writes it	As root: `systemctl stop gdsgate-connector`, the `join` with `--force` and an unused replacement name, then `systemctl start gdsgate-connector`. The unit hands `/var/lib/gdsgate/connector` back to its account at the start. Update resource assignments and revoke the retired node.
Windows	`NT SERVICE\gdsgate-connector`; `join` does not write over its files, and an elevated prompt cannot read the lists of the files the service rewrote or remove them	The steps below. `gdsgate service uninstall connector` leaves the directory in place.

Windows, elevated PowerShell:

sc.exe stop gdsgate-connector
takeown /F C:\ProgramData\gdsgate\state\connector /R /D Y
icacls C:\ProgramData\gdsgate\state\connector /reset /T
Remove-Item -Recurse -Force C:\ProgramData\gdsgate\state\connector
# the join, with --force and an unused replacement name
gdsgate service install connector
sc.exe start gdsgate-connector
# on the Authority host: authority nodes revoke '<old-node-id>'

takeown gives the tree to Administrators and icacls /reset replaces the service's lists with inherited ones. Without them Remove-Item stops at transport.key: Access to the path is denied. /D Y is the English answer; a localized Windows takes its own letter (/? shows it).

On Windows without these steps, join refuses before the token is read, and the same token serves the join in the steps. Over a key the service has not rewritten since service install:

cannot write the transport identity at C:\ProgramData\gdsgate\state\connector\transport.key: it belongs to NT SERVICE\gdsgate-connector, and an owner-only rewrite from this account would shut that account out of it. Nothing was sent, and the token on the standard input is unspent. C:\ProgramData\gdsgate\state\connector belongs to NT SERVICE\gdsgate-connector, the account gdsgate-connector runs as. To join this host again, stop the service, take the directory over and remove it, run this join again, and give the directory back to the service:

Over a key the service has rewritten, the reason is Access is denied. (os error 5). The steps above follow either way, the authority nodes revoke of the old row included.

Moving the registration address¶

A tunneled connector moves to another registration listener on the Proxy, for example from the join relay (50064) to the client port with public_join. No token:

sudo gdsgate join gate.example.com --if-missing \
    --enroll-endpoint https://gate.example.com:50061 \
    --serve demo-ssh=ssh

The other arguments are the ones the connector joined with. The move applies when the new address differs from the file's [enroll].endpoint and from its [enroll].renew_endpoint, compared as host:port. direct and fronted nodes renew where they did.

Result	Output	Files
Moved	`renewed the transport identity in <dir> at https://gate.example.com:50061`, `renewal moved: <old> -> <new>`, exit `0`	identity renewed, current or not; `[enroll].renew_endpoint` from the cluster's answer
Cluster still advertises the old address	`Authority's file still sets [endpoints].proxy_join`; remove it, restart Authority, run again	configuration unchanged; identity renewed
Renewal at the new address fails	`renewing at <address>` and the error	unchanged
Identity expired	refused before any connection	unchanged; `--force` and a fresh token
Run again	`nothing to do`, exit `3`	unchanged

A renewal replaces the key the registry knows the node by. Restart the connector after a run that renewed: the running process holds the previous key, and Authority refuses its renewals with unknown identity.

Kinds `--serve` accepts¶

--serve accepts only the kinds listed at the top of this page. The configuration file has no such limit. gdsgate setup change accepts every kind on its --serve, with --backend <id>:<key>=<value> for the remaining settings.