Client configuration

The flat configuration hub remains the compatibility route. This page is the canonical source-checked field reference for its family, including nested tables and list rows.

Paths in the tables are relative to [client] or its nested heading. Each row gives the serde type and source default or unset meaning; keep transport and identity material in protected files. Check parsing and address cross-field rules with gdsgate doctor --config <PATH> --json, then follow the client connection guide.

[client]

Used by: Client, and, for the addressing keys, the Proxy.

Trust anchor for the client commands (login, ssh, db, kube, tcp, mcp, ca) and settings of the resident client (gdsgate up).

A client normally gets this section from gdsgate connect instead of typing it: the command asks the cluster for its settings and writes ~/.gdsgate/config.toml plus the trust anchor beside it, which is also the file every command reads when --config names nothing else.

Addressing keys are also read on the Proxy

transport_sni, [client.direct].v4_pool, [client.direct].basic_port_range and [client.transparent].dns_zone / v4_pool are what a Proxy publishes to bootstrapping clients. Put them in the Proxy's own configuration and every client of the cluster picks the same ones up, instead of each user's file getting its own zone and its own pool.

access and resolver are not published: they turn on what the local machine may do, bind an address or own a name zone, which the cluster is in no position to decide. They stay per-host.

Nothing in a published bundle identifies anybody. A client is told where to go and whom to trust; who it is remains a separate question, settled by gdsgate login or gdsgate machine-id.

Key	Type	Default	Purpose
transport_ca	string	unset	Path to the cluster transport CA anchor (PEM) used to verify the Proxy's public TLS. The same transport-ca.pem a registered Proxy or Connector writes into its state_dir. Unset, the gateway is verified against the certificate authorities this host trusts, which is what a publicly trusted listener needs; a client that neither has an anchor nor is accepted by that store refuses to connect. Plaintext is a separate, explicit opt-in; see allow_insecure_http.
transport_sni	string	unset	TLS server name the client sends and verifies against. Unset, it is the shared internal name gdsgate.internal when transport_ca names an anchor, and the host being dialled when trust comes from this host's own store. Set it to proxy.gdsgate.internal, or to whatever name your front expects, when several roles sit behind one address and the front routes by server name.
allow_insecure_http	bool	false	Whether the client may talk to the gateway over plaintext http://. It is a switch rather than a consequence of leaving transport_ca unset, so that forgetting to name an anchor never resolves to an unencrypted connection. On such a connection nothing is encrypted or authenticated: the identity token travels in the clear, and so does everything relayed through the session it opens. For developing against a local gateway that serves no TLS.
access	enum	auto	Where the resident client puts the addresses resources answer on: off (no local listeners; resources are reached with the per-command relays), basic (one port per resource on 127.0.0.1), direct (one loopback address per resource, on the protocol's own port), transparent (a virtual address each, on the protocol's own port, on an interface the client creates, which needs CAP_NET_ADMIN and Linux), auto (probe and use the most capable level this host allows). A level named explicitly and found impossible is an error; only auto falls back.
resolver	enum	auto	How resource names are served, independently of access: off (no names), hosts (a block in the operating system's hosts file), system (the client serves the zone and the system resolver is pointed at it, which needs port 53, a network link, and a host whose lookups go through the resolver), auto (system where the client can set it up itself, else hosts, else off). A mode that cannot run degrades rather than failing, and gdsgate status says why. See Resident client → Names.
warm_access	bool	true	Obtain each resource's access certificate on the catalog pass instead of on the first connection. The first connection then opens without a round-trip to the gateway, and gdsgate status can tell a resource you may reach from one you only see. Certificates are renewed before they lapse, a few at a time; a refused resource is not asked about on every poll, and a refusal a single-use step-up grant cures is not asked about at all, since asking would spend the grant. See Resident client → Certificate prefetch.
notify	bool	true	Announce a refusal with a notification from the operating system, on top of the log and gdsgate status. Sent with the desktop's own program (notify-send); a host that has none says so on the status board and carries on. The same refusal is announced once, and again at most every quarter of an hour.
step_up_on_denial	bool	false	Raise the step-up a refusal offers instead of only reporting the command that would. Off by default: the only ceremony a process with no terminal can raise is the passkey confirmation, which opens a browser window on its own. A one-time code and an access request are reported as the command that runs them either way. See Resident client → When access is refused.
intercept_names	array of strings	[]	Whole domains this machine is willing to answer for by their own name, such as app.example.com, rather than a label of [client.transparent].dns_zone. A name is answered for only where this list and the catalog agree: the catalog's native_name on a kind = "web" resource says which resource a domain belongs to, this says which domains the person running this client is willing to give up, and a domain only one of the two names is not intercepted, so nothing a control plane declares can widen this list. Empty means no name outside the client's own zone is answered for. Each entry has to be a whole name (at least two labels) and outside dns_zone. See Resident client → An application's own name.

[client]
transport_ca = "/etc/gdsgate/transport-ca.pem"
# transport_sni = "proxy.gdsgate.internal"
access = "auto"

The name has to appear in the certificate the client is shown, otherwise the handshake fails with a name mismatch. Roll it out in that order: reissue the Proxy's certificate first (see [connector].authority_transport), then switch the clients.

[client.direct]

Settings the two loopback levels share. basic and direct use the same catalog poll and the same address map, one handing each resource a port and the other an address.

Key	Type	Default	Purpose
v4_pool	string	127.70.0.0/16	Address pool direct hands addresses out of. Must lie inside 127.0.0.0/8: a loopback address binds with no privilege and no network interface. A pool outside loopback is refused at start-up, since every listener would fail to bind.
basic_port_range	string	15000-15999	Port range basic hands ports out of, as first-last. Must be unprivileged.
catalog_sync_secs	u64	60	How often the resident client re-reads the catalog. Refused below 5: the catalog changes a few times a day, so a faster poll only adds steady load on the control plane.

[client.direct]
v4_pool = "127.70.0.0/16"
basic_port_range = "15000-15999"
catalog_sync_secs = 60

An address, once given to a resource, stays with it, which is what ~/.gdsgate/endpoints.json is for. Changing v4_pool or basic_port_range renumbers every resource whose address falls outside the new range, so connection strings written down against the old ones stop working. Pick them once.

[client.transparent]

Settings of the level that gives every resource a virtual address of its own on a network interface the client creates. dns_zone sits here but applies at every level: which level is in force decides what a name resolves to, and [client].resolver decides whether it is served at all.

Key	Type	Default	Purpose
v4_pool	string	198.18.0.0/15	Pool virtual addresses are handed out of, and which is routed to the interface. Must lie outside 127.0.0.0/8, and must not overlap a route this host already has.
v6_pool	string	unset	Recognised, not acted upon: this release hands out IPv4 only.
dns_zone	string	gds	Zone names are published under, one label, so pg-prod.gds. Served according to [client].resolver, at every level.
reuse_grace_secs	u64	86400	How long the address of a resource that has left the catalog is held before another resource may take it. Applies at every level, like dns_zone. 0 allows it from the next poll onwards. Even past the grace an address is only handed on after the client that published it is restarted, and only when the pool has none nobody has ever held; see Resident client → when a resource goes away.

The pool's first host address goes on the interface itself (198.18.0.1 for the default), so resources start at the second. Running the level needs the CAP_NET_ADMIN capability and Linux; see Resident client → the transparent level.