External route commands

Available in v0.11.0-rc.13. These commands require a matching client binary and an already configured egress resident.

gdsgate egress shows the saved profile. Select it with --config PATH or contexts use PATH. Editing routes writes an owner-private configuration and keeps a backup of the first pending change. It does not change live routing.

gdsgate egress route add api.example.com --via external-eu --protocol tcp --port 443
# UDP needs to be configured on the running resident already.
gdsgate egress route add 9.9.9.0/24 --via external-eu --protocol udp --port 443
gdsgate egress route list
gdsgate egress route check api.example.com --protocol tcp --port 443
gdsgate egress apply

The exit resource must already be visible and authorized. Client routing cannot expand Connector permissions. Each profile selects one exit; egress use RESOURCE changes that exit for all gate rules. Program launch is outside these commands.

Find an exit and choose an action

Run gdsgate resources list and find an accessible resource whose kind is web-egress. Use its resource identifier for egress use RESOURCE and --via; do not substitute a Connector name, host IP or the resource's .gds DNS name. egress show displays the exit already selected in the saved profile.

gdsgate resources list
gdsgate egress use external-eu
gdsgate egress route add api.example.com --via external-eu --port 443

Replace external-eu with the identifier from your catalog. If the profile already selects that exit, omit --via. Each profile uses one exit, so a rule cannot select a second exit without changing the profile's selection.

TCP destination requests use the httpRequest policy action; UDP uses udpConnect and audit code POL-0209. A one-time step-up grant is bound to its action: an HTTP grant cannot authorize UDP, and a UDP grant cannot authorize TCP.

gdsgate egress route add api.example.com --action gate --port 443
gdsgate egress route add updates.example.com --action direct --port 443
gdsgate egress route add blocked.example.com --action block
gdsgate egress apply

These commands save rules until egress apply reloads the running resident. Rules are checked in order; the first match wins. The editor inserts a new rule first by default, so a specific exception can precede an existing broad rule.

Route selection

Rules use first-match order, independently for TCP and UDP. A repeated identical addition is a no-op. --via on a rule must match the profile's exit. UDP rules require UDP endpoints; TCP configuration alone never enables UDP.

route check does not resolve a name, open a connection, or test remote permission. A domain route affects subsequent DNS lookups. Applications retaining real IPs from earlier lookups may need their own cache refreshed; use explicit IP/CIDR rules when those addresses must remain protected independently of DNS.

Apply without stopping

gdsgate egress apply uses the resident control socket to request reload. The process, interface, synthetic address assignments and kernel protection remain owned throughout. Existing connections retain their admitted policy snapshot; new connections use the replacement. Withdrawing an IP/CIDR route can interrupt connections using that route. A refused reload keeps the running policy and the saved edits remain pending. There is no automatic restart fallback.

Linux installs new IP/CIDR capture before publishing the replacement policy, then removes withdrawn capture. A cleanup error retains conservative protection and is reported in resident status. Windows permits destination/port policy edits that keep its kernel capture set unchanged; resizing that set is refused.

Changing interface/pools, enabling or removing egress, changing transport endpoint exclusions, DNS upstream or kill_switch is refused during reload. A cluster switch with active egress is also refused. Prepare these changes during a planned stop with explicit protection release.

The packaged Linux units expose systemctl reload gdsgate-client (or the matching instance) as the same resident reload operation. A manually installed unit needs ExecReload=/usr/local/bin/gdsgate reload before that operation is available.

Connection lifetime

Transparent access does not reset established TCP merely because the application sends no data for a minute. For ordinary key-bound user access, the client can renew an opaque CONNECT channel before its access certificate expires. It obtains a fresh credential, signs a single-use challenge bound to the same resource and session, and the Connector asks Authority to recheck both connect and access to the original destination. Accepted renewal updates the existing channel's deadline without opening another connection to the destination.

Renewal requires compatible Client, Proxy, Connector and Authority versions. Older components, delegated credentials, browser tickets and inspected channels retain the original certificate deadline. Refreshing the credential cache alone does not renew a channel. Failed renewal never extends the old grant; an explicit authorization denial closes the channel. UDP keeps its own lease limits.

Session termination and supported node/workload revocations can end a renewed channel through HA. A policy edit takes effect at the next authorization decision; it does not automatically terminate every established channel. Use explicit session termination when immediate disconnection is required. Transport failures and destination-side limits can also end a channel sooner.

The 15-second CONNECT opening deadline covers establishment, not the later application stream. Catalog and certificate requests have separate 20-second control deadlines. Proxy–Connector keepalive detects an unresponsive shared transport independently of application traffic. A configured external load balancer or destination server can also impose its own timeout.

Original DNS resolver

client.egress.dns_upstream is an optional literal IP:port override. Without it, the client discovers the original system DNS server. No public resolver is selected as a built-in fallback. Discovery failure reports an error and asks for an explicit server; startup currently requires an upstream even for a profile whose connections mostly use gate.

For an ordinary domain gate rule, the resident returns a synthetic address, then sends the original hostname through the tunnel. The Connector resolves that hostname and checks its destination addresses. Local dns_upstream is used for direct, forwarded queries outside intercepted names, and real-address lookups when IP/CIDR matching can change the selected action. A preceding CIDR rule and a later domain rule that both choose gate do not require a local lookup. A preceding CIDR block or direct rule still requires resolution before a later domain gate rule can apply.

Upstream queries currently use direct TCP, outside the egress tunnel. Setting dns_upstream does not select DNS over egress. A manual override changes which resolver receives those queries; omit it when system discovery is suitable.

Kill switch and explicit release

[client.egress].kill_switch defaults to true. When enabled, selected public IP/CIDR capture and the resident virtual address pool remain protected after a normal stop or process failure. Other destinations and other OS users keep their normal routes. This does not block every public address a domain might resolve to when the resident is absent; protect such destinations with explicit IP/CIDR rules.

With kill_switch = false, stopping the resident releases capture; loss of the interface permits direct fallback. Reload never removes protection as a side effect of applying destination rules.

After stopping, gdsgate egress release explicitly removes the retained guard and permits direct routing. Linux requires network-administration privileges for this operation; sudo gdsgate --config PATH egress release retains the invoking account's state directory. It refuses a live or inaccessible owner or foreign network objects. Use it only when releasing that protection is intended.

Command reference

gdsgate egress
gdsgate egress show [--json] [--wide] [--no-pager]
gdsgate egress use RESOURCE
gdsgate egress mode selective|full [--protocol tcp|udp]
gdsgate egress route list [--json] [--wide] [--no-pager]
gdsgate egress route add DESTINATION [--via RESOURCE] [--protocol tcp|udp]
    [--port PORTS] [--action gate|direct|block] [--at NUMBER]
gdsgate egress route remove NUMBER [--protocol tcp|udp]
gdsgate egress route check HOST --port PORT [--protocol tcp|udp]
    [--address IP] [--json] [--wide] [--no-pager]
gdsgate egress udp enable --endpoint IP:PORT [--endpoint IP:PORT ...]
gdsgate egress udp disable
gdsgate egress apply
gdsgate egress release

Put global options such as --config PATH before egress. --protocol defaults to tcp. --port accepts a comma-separated list, inclusive ranges and repeated arguments; its default is every nonzero port. --at and route numbers start at 1. New rules are inserted first, so a specific exception can precede a broader rule.

Human listings use the common CLI table renderer and terminal viewer. show includes a saved-profile summary; route list prints only the rules. Multiple destinations stay grouped under their rule number. --wide separates exact names, domain suffixes and CIDRs; --no-pager disables the viewer. Pipes remain plain output. Progress and saved/applied confirmations go to stderr.

In a terminal, route actions use the common palette: gate is green, direct is orange, and block is red. The summary emphasizes the selected exit and the saved kill-switch setting. NO_COLOR disables styling; pipes and JSON contain no terminal colour codes.

The tcp and udp summary lines show each transport's mode and rule count, not a count of live connections. selective sends matching gate rules through the exit; unmatched traffic uses the normal path. In full mode the exit is the default, with explicit direct or block exceptions. killswitch on describes the saved setting; it does not confirm that pending settings are already active.

UDP network endpoints appear only with show --wide or show --json. They are the Proxy ingress addresses used by the client, not Connector backend addresses. A Proxy and Connector on the same host can share a public IP. The client needs to know its Proxy address to connect.

show --json prints the saved configuration as one JSON object. route list --json prints one JSON object per rule, with protocol, rule, destination, action and via; an empty list has no output. route check --json prints one local decision object. These commands read saved settings; they do not claim that pending settings are already active or that a Connector permits the destination.

Initial setup and later edits

After connecting and logging in, configure capture before starting a resident that did not previously have egress:

gdsgate egress use external-eu
gdsgate egress route add api.example.com --protocol tcp --port 443
# Optional: select the reachable UDP Proxy address before starting capture.
gdsgate egress udp enable --endpoint 203.0.113.10:5443
gdsgate egress route add 9.9.9.0/24 --protocol udp --port 443
gdsgate up

Substitute the actual published exit and UDP endpoint. For an already running resident with this egress and UDP transport configured, edit destinations and apply them through reload:

gdsgate egress route add '*.example.com' --via external-eu --protocol tcp --port 443
gdsgate egress route add 9.9.9.9 --via external-eu --protocol udp --port 443
gdsgate egress route check api.example.com --protocol tcp --port 443
gdsgate egress apply
gdsgate status

To remove an exception, find its number with route list, then run route remove NUMBER --protocol tcp or --protocol udp, followed by egress apply. To block a destination, add it with --action block; to permit an explicit direct path, use --action direct. Direct/block rules do not take --via.

Linux recovery reuses the DNS upstream recorded in a retained capture lease. A change in the host's resolver ordering does not silently change transport exclusions during a guarded restart. An explicitly changed DNS upstream still requires a planned stop and protection release.