Configuration
The agent keeps a small JSON config file; the edge is flags and environment variables only, with no config-file dependency.
Agent (ngstone)#
ngstone auth, ngstone config set, and ngstone logout read and write:
$XDG_CONFIG_HOME/ngstone/config.json# falls back to ~/.config/ngstone/config.json if XDG_CONFIG_HOME is unsetngstone auth <token> after it verifies against the edge. Cleared by ngstone logout.ngstone auth or ngstone config set server <addr>. Falls back to ngstone.site:4443 if never set.The file is written mode 0600 inside a 0700directory, via a temp-file-plus-rename so a crash mid-write can't corrupt it. See ngstone config for the commands that read and write it.
Project (ngstone up)#
ngstone up starts several tunnels from a checked-in JSON project file. It searches the current directory for ngstone.json, then .ngstone.json; use --file to select another path.
{ "tunnels": { "web": { "target": "3000", "subdomain": "demo", "host_header": "demo.localhost:3000", "credential_env": "NGSTONE_WEB_TOKEN", "multi_connector": true, "connector_token_env": "NGSTONE_CONNECTOR_TOKEN", "policy_file": "traffic-policy.json", "ttl": "2h" }, "grpc": { "target": "http://127.0.0.1:50051", "http2": true }, "database": { "kind": "tcp", "target": "5432", "remote_port": 15432 } }}-, _, and ..http, tcp, or tls. A tls tunnel is routed by SNI and passed through without decryption; see TLS passthrough. It accepts subdomain and allow_cidr, and rejects the HTTP-only fields and remote_port.host:port for TCP or TLS, or a full HTTP URL.demo.localhost:3000 for a tenant-aware local app.https:// target uses TLS HTTP/2; an http:// target uses cleartext h2c. Enable this for native gRPC, trailers, streaming, and full-duplex requests.multi_connector mode. The project file stores only the variable name, never the secret itself.NGSTONE_TOKEN or the saved config token is used.0 means assigned.2h. The tunnel stops when the duration from process start expires.auto tries raw TLS first and falls back to the authenticated WebSocket endpoint on HTTPS port 443; use raw or websocket to force one path.user:pass credential per line. Relative paths are resolved from the project file directory.The project format is strict JSON: unknown fields fail fast. It never accepts token; ngstone up resolves the token from NGSTONE_TOKEN or the saved credential file, just like ngstone port. Keep credential files out of source control, and protect any basic_auth_file with mode 0600.
Edge (ngstoned)#
example.com. There is no default.-insecure.expvar, /healthz, pprof). Empty disables it./api/v1 accepts only loopback requests. Defaults to $NGSTONE_ADMIN_TOKEN_SHA256. Store only the hash on the edge and keep the plaintext token with the operator.NGSTONE_OIDC_CLIENT_SECRET and NGSTONE_OIDC_COOKIE_SECRET.https://edge.example.com:4041/api/v1/auth/oidc/callback.admin, operator, and viewer roles. A user must match a group unless -oidc-default-role is set.BindOK.URL — http or https.$NGSTONE_CREDENTIALS_FILE.$NGSTONE_DATABASE_URL or SQLite at /var/lib/ngstoned/control.db when no legacy credential source is configured. Use a PostgreSQL URL for multiple edge servers.sqlite or postgres override. The driver is inferred from the database URL when omitted.$NGSTONE_EDGE_ID or a generated ID.-credentials-file and $NGSTONE_CREDENTIALS_FILE are unset. See Generating a token.staging or production. A config mistake against production can rate-limit the domain for a week.-insecure.certmagic.FileStorage path; must match the systemd StateDirectory.<name>.crt and <name>.key pairs served for active custom domains. Keys must be mode 0600. Needs durable storage and a TLS public listener. Read at start-up, so changes need a restart; an expired or unreadable pair stops the edge. Also $NGSTONE_CUSTOM_CERTS_DIR.cloudflare, route53, digitalocean, hetzner, vultr, ovh, desec, or bunny. Its credentials are read from the environment only — see below. -dns-provider help prints the providers and the variables each reads, then exits.-dns-provider cloudflare when $NGSTONE_CF_API_TOKEN is unset. Prefer the environment variable.Every value in the timeouts and limits table — request timeouts, body caps, rate limits, concurrency caps — is also flag-overridable on the edge (-read-header-timeout, -idle-timeout, -max-header-bytes, -max-body-bytes, -response-header-timeout, -per-ip-rate, -per-ip-burst, -per-ip-lru, -global-inflight, -per-session-inflight, -upgrade-inflight, -per-session-upgrade, -handshake-concurrency, -unauth-sessions, -unauth-per-addr, -per-ip-inflight, -client-idle-timeout, -tcp-idle-timeout, -webhook-max-body-bytes, -webhook-buffer-bytes, -max-share-ttl, -share-audit-log). See Limits & timeouts for the full set and their defaults.
Environment variables#
ngstone port, tcp, and up, below a --token flag where one exists and above the saved config file.ngstone admin. It defaults to http://127.0.0.1:4041.ngstone admin. Prefer this environment variable to --token so the secret is not visible in process listings.NGSTONE_CREDENTIALS_FILE.-custom-certs; the environment value wins over the flag.sqlite or postgres.-dns-provider cloudflare: API token with Zone / DNS / Edit on the zone only. Preferred over -cf-api-token.-dns-provider route53: region and the keys of an IAM user allowed route53:ListHostedZonesByName, ListResourceRecordSets, ChangeResourceRecordSets, and GetChange.-dns-provider digitalocean: personal access token with domain read and write.-dns-provider hetzner: read and write API token of the Hetzner Console project holding the zone. Zones on the deprecated dns.hetzner.com must be migrated first.-dns-provider vultr: API key, with the VPS's IP allowed in its access control.-dns-provider ovh: endpoint ovh-eu, ovh-ca, or ovh-us, plus a consumer key limited to GET, POST, and DELETE on /domain/zone/*.-dns-provider desec: API token. deSEC's 3600 s minimum TTL and rate limits can make issuance take a few minutes.-dns-provider bunny: account API key./api/v1; without it, that API is loopback-only. Prefer this environment variable to the equivalent command-line flag.$NGSTONE_ALERT_WEBHOOK_URL. The optional NGSTONE_ALERT_WEBHOOK_TOKEN is sent as a bearer header.Only providers whose libdnsmodule adds and removes individual TXT values are supported, because the apex and wildcard certificates publish challenges at the same name concurrently. GoDaddy, Namecheap, Porkbun, IONOS, Azure, DNSimple, and netcup are not; move the zone's DNS hosting to a supported provider instead. See Choosing a DNS provider.
Never pass secrets as flags
/proc/<pid>/cmdline is world-readable on stock Linux, so anything passed as an ExecStart flag is readable by any local user via ps auxww. Load secrets from EnvironmentFile= instead.Precedence#
On the edge, an explicit flag always wins over its environment fallback; anything left unset falls back to its documented default. DNS provider credentials other than Cloudflare come from the environment only.
On the agent, resolving the token or server address for direct tunnel commands and ngstone up follows this chain:
--token / --server.credential_env for a project tunnel, otherwise NGSTONE_TOKEN. There is no environment override for the server address.ngstone auth or ngstone config set last saved.