Deploy

Service commands

Commands that run and install the server roles. Writing a first configuration from flags is gdsgate setup. Global flags are in the CLI hub.

0.11.x

Commands that run and install the server roles. Writing a first configuration from flags is gdsgate setup. Global flags are in the CLI hub.

gdsgate proxy

Run the Proxy: public listener, internal reverse-tunnel listener, WebSocket fallback listener and an Authority pool. Preserve its enrolled identity directory across restarts. Live sessions belong to their Proxy process and do not migrate when it stops; see Proxy HA.

Reads: [endpoints], [enroll], [proxy].

Shell
TOKEN_FILE="<proxy-enrollment-token-file>"
GDSGATE_ENROLL_TOKEN="$(<"$TOKEN_FILE")" \
    gdsgate --config proxy.toml proxy

The Proxy registers on first start, consuming the token, persists its identity to [enroll].state_dir, and on subsequent starts reuses the persisted identity. With no [enroll].endpoint, the Proxy runs plaintext, for dev and loopback only.

gdsgate proxy init --domain <name>

Write the configuration a Proxy is started from. Writes a file and starts nothing; enrolling the node is gdsgate join.

Writes: [endpoints], [proxy], [telemetry]. Composed by setup prepare it also writes [enroll] and, where the deployment named one, [oidc].

Shell
gdsgate proxy init --domain gate.example.com \
    --tls-cert /etc/letsencrypt/live/gate.example.com/fullchain.pem \
    --tls-key /etc/letsencrypt/live/gate.example.com/privkey.pem \
    --output /etc/gdsgate/proxy.toml
Flag Default Meaning
--domain <name> required The name clients dial. The certificate has to carry it.
--listen <addr> 0.0.0.0:50061 Client-facing bind. A port below 1024 is accepted with a condition in the plan: the shipped systemd unit cannot bind it. Put a front or an nftables redirect ahead of it.
--authority <addr> 127.0.0.1:50051 Where Authority answers.
--authority-enroll <addr> 127.0.0.1:50050 Where Authority answers registration; the relay forwards a joining node's first exchange there. Written only with --join-relay. The plan names it as a condition when left at the default.
--join-relay off Bind proxy_join, for nodes whose only route to the control plane is this gateway.
--tls-cert, --tls-key unset What the client-facing listener presents.
--output <path> /etc/gdsgate/proxy.toml Where the configuration goes.
--save <dir>, --node <name> unset Write a bundle for another machine; nothing on this machine changes.
--approve-plan <digest> unset Refuse unless the plan is the one that digest names.
--dry-run, --json off Show the plan; print it as JSON.

proxy_internal (0.0.0.0:50062) and proxy_ws (0.0.0.0:50063) are always written. proxy_join is bound only with --join-relay; it accepts callers that have not authenticated, and the plan says so. With it comes authority_enroll, the address the relay forwards registration to. If Authority's ports were moved and this address was left at the default, a joining node is told its token is unknown.

An existing file is refused; change it with setup change. Exit codes are the setup contract.

gdsgate connector

Run the Connector: dials the Proxy's reverse-tunnel listener, registers the resources declared in [[connector.backends]], and serves them.

Reads: [endpoints], [enroll], [connector].

Shell
TOKEN_FILE="<connector-enrollment-token-file>"
GDSGATE_ENROLL_TOKEN="$(<"$TOKEN_FILE")" \
    gdsgate --config connector.toml connector

For any SSH backend, of either model, the connector loads its host key from <state_dir>/ssh_host_ed25519_key, generating one on first start. A jump host appears in the caller's known_hosts under this key.

An enrolled connector serving an SSH backend also keeps <state_dir>/activation.json, the highest activation epoch it has seen. It refuses to start when that file cannot be read or written. See gdsgate authority epochs activate.

On Windows a connector refuses to start with an SSH backend that uses ssh_profile = "git", login_mode = "host_user", or session ceilings in [connector.backends.session].

gdsgate agent-host

Runs the agent host: starts the agents declared for this node, each in its own cage. See the agent host guide.

Reads: [endpoints].authority, [enroll], [agent_host], [telemetry].metrics_listen.

Shell
TOKEN_FILE="<agent-host-enrollment-token-file>"
GDSGATE_ENROLL_TOKEN="$(<"$TOKEN_FILE")" \
    gdsgate --config agent-host.toml agent-host

Binds no listener. Connects to Authority over mutual TLS. The enrollment token is used once; the node certificate is renewed without a token.

The agents and their access are declared on Authority with authority agents set; this host has no configuration for them. Enroll the node with gdsgate join --role agent-host, using a token from gdsgate authority tokens create --role agent-host.

A node holding no enrolled identity is refused under [security].profile = "pilot" or "production".

Agents run on Linux only. On Linux, install the unit from packaging/systemd/gdsgate-agent-host.service by hand; service install does not offer this role. On Windows the process starts but runs no agents, and logs each declared agent as not held.

gdsgate connector recordings push [--dry-run]

Delivers the recordings a running connector is holding in central mode but has not yet gotten to Authority, or says why not, without waiting for the next scheduled delivery pass.

Shell
gdsgate --config connector.toml connector recordings push --dry-run
gdsgate --config connector.toml connector recordings push

--dry-run lists what is on disk and, for each cast, why it is still there; nothing is uploaded and nothing is removed. A real run uploads and removes what the store accepts, printing one line per cast, delivered or held back, and a summary.

The command asks the running connector to deliver, over its local control channel: the socket ${enroll.state_dir}/connector.sock on Linux, a named pipe derived from that path on Windows. When no connector is listening, the command says so and exits 1; the connector's next start runs a delivery pass.

When a delivery pass is already running, the command says it is waiting, waits for it, then runs its own.

Exit codes, the same four gdsgate join uses:

Exit Meaning
0 At least one cast was delivered.
1 Nothing was delivered and something is held back, including a pass that stopped partway through, an unreachable store for one.
2 The arguments do not parse.
3 There was nothing to deliver.

See gdsgate doctor to check whether anything is waiting before running this by hand, and the admin guide for the operator recipe this command is part of.

gdsgate all

Run Authority, Proxy and an embedded Connector in one process. store_url defaults to a SQLite file (~/.gdsgate/state/store.db) that survives restarts. Other connectors can still register on the registration listener.

Reads: every section.

Shell
gdsgate --config all.toml all

gdsgate service install|uninstall <role>

Installs a role as a service, or removes it. Server roles require root on Linux and an elevated prompt on Windows. install does not start the service unless --start is supplied. An already running service stays running. The agent host is not offered; see gdsgate agent-host.

Successful installation records the configuration the service now uses. A reinstall with a different --config replaces that role's previous service path; other role records and the selected client cluster are retained.

Shell
gdsgate service install authority --start
gdsgate service install proxy --start
gdsgate service install connector --start

gdsgate join --start also installs and starts the Connector service after saving its registration. Both commands use this service installer; a failed start can be retried without another join token.

--start checks for an immediate process exit. Setup startup uses the same start check and also waits for its control plane and Proxy readiness endpoints. If registration or startup fails, the error names the completed stage and a retry command. Existing configuration and identities are retained.

Linux

Roles: authority, proxy, connector. The unit is the shipped one from packaging/systemd, with the paths filled in.

Property Value
Unit /etc/systemd/system/gdsgate-<role>.service, enabled
Program the gdsgate that runs install; refused under /tmp, /var/tmp, /home, /root and /run/user, which the unit hides from the service
Account DynamicUser=yes, in the gdsgate group
Configuration --config, otherwise the installed role configuration (including standard platform files); its directory, its *.toml, *.cedar and *.keys, and every file the configuration names inside it (a registration key, a certificate) are given to the gdsgate group, files 0640
Environment <role>.env beside the configuration, optional
State /var/lib/gdsgate/<dir>, the one directory the service may write
Log journalctl -u gdsgate-<role>
Start with the machine; Restart=on-failure after 2 s
Configuration reload systemctl reload gdsgate-<role> applies supported changes and confirms the result; see reload.

<dir> is the directory under /var/lib/gdsgate that the role's configured paths are in: [enroll].state_dir for proxy and connector, the SQLite store and [audit].export_path for authority. Without one, it is the role's name. A file the role reads from under /var/lib/gdsgate has to be in the same directory. install refuses the configuration if one of these paths is elsewhere:

Refusal Fix
... is under ... which the unit hides Move the configuration under /etc/gdsgate, or the program under /usr/local/bin. Home and temporary paths are hidden.
... is outside /var/lib/gdsgate Move the written path under /var/lib/gdsgate/<role>.
... is where every role's directory is Name a directory under it, such as /var/lib/gdsgate/connector.
... is directly in /var/lib/gdsgate Move the file into the role's directory and change the path in the configuration.
... are in two directories under /var/lib/gdsgate Keep the role's files in one directory.

When /var/lib/gdsgate is a link into /var/lib/private (left by units that shared one state directory), install turns it into a directory. Role directories stay where they were; files that sat directly in it move back. A unit that still has StateDirectory=gdsgate no longer starts, and install names it: install that role again.

Every Linux service install, including client, checks the shared parent /var/lib/gdsgate. An install run as root creates or repairs this directory to mode 0755 before registering the service. A parent left at 0700 blocks service accounts from reaching their private state. The repair changes only the common parent; role directories and key files keep their permissions. An unprivileged install reports an invalid existing parent and requires an administrator to repair it. Unexpected links and non-directory entries are refused. doctor reports the same parent problem without changing permissions.

Shell
gdsgate --config /etc/gdsgate/authority.toml service install authority --start
gdsgate service uninstall authority

Resident client

Linux also supports client: the default protected system unit runs as the original user and retains their configuration and identity. It needs elevation and the trusted kernel filter command. A user unit is available with local_user_only = false and a loopback access level. Normal gdsgate up handles installation and startup, asking for elevation once when needed. --foreground runs the resident directly. See Resident service.

Shell
sudo gdsgate --config "$CLIENT_CONFIG" service install client --start
sudo gdsgate service uninstall client

On Windows, client installs the same privileged network helper as client-net; the resident remains in the user session. An ordinary up ensures that helper is running.

Windows

Roles: authority, proxy, connector, client-net, client.

Property Value
Service name gdsgate-<role>
Account virtual account NT SERVICE\gdsgate-<role>; client-net runs as SYSTEM
Configuration --config, default %ProgramData%\gdsgate\<role>.toml; client-net reads none
State %ProgramData%\gdsgate\state\<role>, owned by the service account
Log %ProgramData%\gdsgate\logs\gdsgate-<role>\gdsgate-<role>.log, rotated at 32 MiB, three kept; the service account writes its own directory there and no other
Start with the machine; restarted 5 s after a failure, including an exit with an error
Configuration reload gdsgate.exe reload --role <role> applies supported changes through the running service's local channel.
Certificate refresh sc.exe control gdsgate-<role> paramchange re-reads listener certificates.

install gives the service account read access to the configuration, every file it names, and gdsgate.exe. It also makes the account the owner of its state directories. Secret files lose every entry except their owner, SYSTEM and the gdsgate service accounts. Running install again for a registered server service renews those grants and updates its binary/config launch paths. It keeps the virtual account, operator startup mode, dependencies, display name, error control and failure policy. A service registered under another account is refused. Run install after adding a file or moving the binary or configuration; restart an already running service to load the updated paths.

On both systems uninstall stops the service and removes the unit or the registration. Configuration, state and log stay where they are. Removing a service that is not installed succeeds.

powershell
gdsgate service install authority --start
gdsgate service uninstall authority

macOS

On macOS, service installation accepts authority, proxy, connector, client and client-net. The executable must be root-owned, outside user and temporary directories, with no group/other-writable ancestors or writable ACLs. For example, install the verified executable at /opt/gds/gdsgate first.

For the Resident, choose your existing user-owned client profile and install client. This command also installs its helper; installing client-net separately beforehand is unnecessary. Keep the client profile and identity under the ordinary user's account.

Shell
CLIENT_CONFIG="$HOME/.gdsgate/config.toml"
sudo /opt/gds/gdsgate --config "$CLIENT_CONFIG" service install client --start

Server roles use their own configurations and state, separate from the client. The installer prepares /etc/gdsgate when missing, but does not move an existing configuration or credential/state tree. Before registering a server, put its configuration in a root-controlled directory, make it root-owned and use explicit persistent credential/state paths. Preserve existing identities when preparing a service installation.

Shell
sudo /opt/gds/gdsgate --config /etc/gdsgate/authority.toml service install authority --start
sudo /opt/gds/gdsgate --config /etc/gdsgate/proxy.toml service install proxy --start
sudo /opt/gds/gdsgate --config /etc/gdsgate/connector.toml service install connector --start

Server roles run as separate hidden service accounts, with separate state under /var/lib/gdsgate/<role>. Existing role directories retain their contents and are assigned only to that role; foreign owners, links and special files are refused. Configurations and external credentials must be root-controlled. Installation grants the role read access using file ACLs. Existing relative credentials/state that would change location require explicit absolute paths. No shell or environment file is sourced; use file-backed secret references that the service can read.

client also installs the root network helper. The Resident uses the invoking user's configuration and identity and runs as a LaunchAgent at graphical login. The helper is a LaunchDaemon started with the machine. A root session without sudo must name the client owner with --owner-uid UID. Only one owner can hold the machine helper. To install the helper separately:

Shell
sudo /opt/gds/gdsgate service install client-net --owner-uid "$(id -u)" --start

PF approval during installation is persistent: the helper may enable PF and hold its own reference after every reboot, activating all loaded PF rules. The installer asks in a terminal, default No; unattended approval requires --pf-enable yes. --pf-enable no installs without permission to take a new reference. A previously approved persistent installation reuses its choice unless another choice is supplied. An approved live reference alone does not silently authorize future boot-time activation. Protected access still needs all PF prerequisites.

Stop a manually started Resident and foreground helper before starting the installed jobs. Keep their recovery journals. --start loads the job now; without it, installation only writes files for the next boot/login. Starting a user agent immediately requires that owner's graphical login session. An already running job is not restarted by reinstalling it; a changed definition applies on its next start. A clean gdsgate down is not automatically restarted, while a failed process is retried with throttling. gdsgate up starts an installed user agent through launchd.

Client installation with --start checks access to the helper socket as the actual user. If the Resident reports Permission denied, check the helper and Resident logs below. The root-owned directory /var/run/gdsgate-client-net must allow the user to traverse it. If its mode is 0700, use sudo chmod 0755 /var/run/gdsgate-client-net on that directory only; keep its private recovery journals intact. Reinstalling a running helper does not load a replacement executable; stop the Resident normally and restart the managed helper before starting it again. A fresh boot also loads the replacement executable.

Item Location
System jobs /Library/LaunchDaemons/dev.gds.gdsgate.<role>.plist
User Resident ~/Library/LaunchAgents/dev.gds.gdsgate.client.plist
System logs /Library/Logs/gdsgate/<role>.log
Resident log ~/.gdsgate/logs/resident-launchd.log
Shell
sudo /opt/gds/gdsgate service uninstall authority
sudo /opt/gds/gdsgate service uninstall proxy
sudo /opt/gds/gdsgate service uninstall connector
/opt/gds/gdsgate service uninstall client
sudo /opt/gds/gdsgate service uninstall client-net

Removing a role stops/unloads only its managed job. Configuration, credentials, PKI, service accounts, logs and retained network-protection journals remain. Removing client leaves the root helper installed; remove client-net separately when appropriate. Uninstall does not flush PF or release retained egress protection. After installation, check service readiness, a resource connection and normal restart/recovery behavior.

gdsgate client-net

On Windows this runs the machine helper. It is refused on Linux, where the resident client runs from gdsgate-client@.service. The service sets the NRPT rule and holds the Wintun adapter for the resident client; see Resident client on Windows. A delegated run under --sandbox basic or strict uses it to let the run's container reach its endpoints, read drive letters and use NUL; see The sandbox on Windows. The Windows installer registers it with gdsgate service install client-net. Do not run it by hand.

The macOS backend uses gdsgate client-net --owner-uid UID, started as root, while the Resident runs as that non-root account. This is a separate role of the same executable. It prepares a compatible PF hook and asks before taking its own PF enable reference. --pf-enable ask|yes|no controls that decision; the default is ask, with no enable in a non-interactive launch. yes is explicit operator approval, and no preserves the enable state without taking a new reference. Already enabled PF needs our approved reference so another program cannot release the last reference underneath protection. A confirmed previously approved reference is reused without another enable or prompt. See PF preparation and approval for compatibility, retained guards and cleanup. Register the helper through macOS service installation.

Service lifecycle

proxy, connector, authority and all run in the foreground until stopped; run them under systemd on Linux, launchd on macOS or the service manager on Windows. Before treating a replacement as ready, check /healthz and /readyz: a process can be live while its dependencies are not ready.

Search this documentation edition.