Reload configuration

gdsgate reload re-reads a running component's configuration. Choose a server with --role; without it, the command targets the resident client.

gdsgate reload
gdsgate reload --role authority
gdsgate reload --role proxy
gdsgate reload --role connector
gdsgate reload --role agent-host

Server commands use the installed role's configuration to find its local control channel. They do not follow contexts use. For a foreground process or a custom file, name the file explicitly:

gdsgate --config /etc/gdsgate/connector.toml reload --role connector
gdsgate --config /etc/gdsgate/connector.toml doctor --role connector --json

Without --config, the server re-reads the file it loaded last. An explicit path becomes the loaded source after successful application. It must retain the same state directory and settings that require restart. The command starts no process and installs no service. Configurationless development processes have no reload channel.

Apply changes

1. Edit the component's file or use setup change.
2. Run reload --role ROLE as the process owner or a machine administrator.
3. Read the result. Success includes the role, loaded path and reload generation. A refusal names the settings that require restart or the failed preparation.
4. Run doctor --role ROLE --explain to inspect the last reload result. Its JSON includes runtime_reload with role, config_path, generation and error. The field is null when no running reload channel can be reached.

The server validates and prepares every replacement before applying changes. A preparation failure retains the loaded source and live configuration. Accepted application finishes even if the requesting command disconnects. An interrupted command should be followed by doctor before retrying.

Files must belong to the service account or a machine administrator and must not be writable by another account. Read access for a service group is allowed. The local channel admits the owning account and machine administrators; it is not a network listener.

On Unix, a reload socket cannot be served from a directory that another account can write unless the directory has the sticky bit. At startup, Connector, Proxy and Agent Host tighten an owned node state directory with unsafe write permissions to 0700. This changes the directory itself, without recursively changing its contents. Shared system directories, foreign owners and symbolic links are not rewritten. Authority store directories retain their configured permissions.

A state directory may be a symbolic link, including one created by a service manager. The link, its containing directories and its resolved target must be owned by root or the service account and protected from replacement by another account. Sticky ancestors remain supported when the entries below them have these owners. Reload binds at the checked target without changing permissions through the link. Unsafe links disable reload with a diagnostic.

If the protected reload channel cannot be created, the component logs an ERROR and continues without configuration reload. This does not bypass transport, authentication or resource authorization checks. reload then fails to connect; correct the local channel problem and restart the component to enable it.

Windows service install makes the server configuration owned by Administrators, writable by Administrators and SYSTEM, and readable by the service account. setup change preserves that owner and access list. Reinstall an existing server service once to apply these permissions before using configuration reload.

Changes supported without restart

Role	Settings	Effect
Authority	transport.cert_ttl_secs	Validity of subsequently issued transport identities. Existing identities retain their expiry.
Authority	ha.max_cluster_sessions	Limit for subsequent session admission. Existing sessions remain open.
Authority	policy.editor.min_approvers	Approval threshold used by later policy transitions.
Authority	mcp.destructive_patterns	Classification of later MCP decisions.
Proxy	proxy.public_addr	Address advertised to subsequent clients and joining nodes. It does not move a listener.
Proxy with proxy.authority_topology = true	endpoints.authority, authority_failover, authority_enroll, authority_enroll_failover	Replaces explicit route overrides. Verified membership and cached topology remain intact.
Connector	connector.backends, connector.discovery_sources	Replaces local declarations and probes. Open sessions retain their original backend. Changed declarations wait for admission before new sessions start.
Agent host	endpoints.authority, endpoints.proxy_public	Changes later Authority calls and the Proxy route for newly acquired works. Existing works retain their clients. Requires an enrolled Authority client.
all	Authority limits, proxy.public_addr, Connector declarations and probes	Prepares all components before applying any changes. Uses the existing local listeners.

Connector reload requires every desired tunnel to be registered with an updated Proxy and Authority supporting live declarations. An older peer or a missing tunnel refuses local reload. Discovery retains its existing reconnect behavior when communicating with older peers.

Connector success confirms local application. Cluster admission and automatic publication follow asynchronously. Authority still checks node identity, publication scope, catalogue modes and activation receipts. A denied resource remains unavailable. Inspect doctor, the catalogue and serving status after application. Authority outages, revocations and expired leases still stop access.

An automatic publisher keeps its existing namespace, journal and generation counter. Removed routes are withdrawn, and new routes wait for Authority's accepted snapshot. A manual discovery reload cancels old probes before starting replacements.

Authority limits are local settings. Reload each HA Authority after updating its file. Reload does not distribute configuration files or move sessions between processes. Keyring synchronization and CA rotation retain their existing commands.

Changes requiring restart

The [admin] block configures the administrative CLI. Server roles do not use it; updating its endpoint, identity directory or transport does not require a server restart and does not replace the server's enrolled identity.

Other settings outside the table require restart. These include cluster identity, enrollment and transport identity, database or state paths, listeners, TLS paths and names, OIDC, workload validation, keyrings, HA membership, telemetry, recording sinks and Agent host runtime settings. Static Proxy Authority routes also require restart when proxy.authority_topology is disabled.

A file containing both supported changes and a change requiring restart is refused as a whole. Resolve the named fields and retry, or restart deliberately. Changed environment variables or service environment files require restart.

Certificate contents at existing configured paths use the separate TLS refresh mechanism. Invalid replacements keep the previous certificate. SIGHUP and Windows service paramchange retain their certificate-refresh behavior; they do not acknowledge configuration application.

Services and platforms

Linux units installed by this build use an acknowledged reload command:

sudo systemctl reload gdsgate-authority
sudo systemctl reload gdsgate-proxy
sudo systemctl reload gdsgate-connector

Reinstall an existing unit with the installed new binary and the same config:

sudo gdsgate --config /etc/gdsgate/authority.toml service install authority

Use the corresponding role and config for Proxy or Connector. The installer updates ExecReload and runs systemctl daemon-reload automatically. Until then, use gdsgate reload --role ROLE directly. A binary upgrade also requires a separate process restart; unit installation and configuration reload leave an already running process in place. Follow the 0.11 service upgrade. The role remains running during configuration reload.

On Windows, run the same gdsgate.exe reload --role ROLE command from an elevated terminal. It reaches the running service through its protected local channel. For a container or an unmanaged process, run the command as the process owner, with the same configuration and state paths available.

Authority places its channel beside the SQLite store, or in the HA keyring-sync state directory when no file store is configured. Explicit enroll.state_dir selects the remaining Authority case; otherwise the audit export directory or platform Authority state directory is used for a configured database. A manual, unprivileged database deployment should set a private enroll.state_dir. Other server roles use their enrolled state directory. None of these paths are shared with the resident's control socket.

For resident settings, context switching and OS resources requiring restart, see resident reload.