Deployment & systemd
ngstoned is meant to run as a long-lived systemd service on the VPS, restarted automatically on crash and surviving reboots without re-issuing certificates.
The systemd unit#
[Unit]Description=ngstone edge serverAfter=network-online.targetWants=network-online.target [Service]Type=simpleExecStart=/usr/local/bin/ngstoned --domain example.com --cert-email you@example.comDynamicUser=yesStateDirectory=ngstonedAmbientCapabilities=CAP_NET_BIND_SERVICENoNewPrivileges=yesEnvironmentFile=/etc/ngstoned/envRestart=alwaysRestartSec=2 [Install]WantedBy=multi-user.target--domain is required and has no default. For a DNS host other than Cloudflare, add --dns-provider NAME to ExecStartand put that provider's credentials in the environment file; for raw TCP tunnels, add --tcp-ports MIN-MAX and open that range in the firewall. deploy/install-edge.sh writes this unit for you — see Fast path installer.
DynamicUser & StateDirectory#
DynamicUser=yes paired with StateDirectory=ngstoned is the mechanism systemd provides specifically to make dynamic, unprivileged users work with persistent state. systemd creates the directory under /var/lib/private/ and re-chowns it to the current transient UID on every service start, so the certificate cache survives restarts intact even though the UID changes each time.
Reference the certificate path via ${STATE_DIRECTORY}/certs (or the systemd-bind-mounted /var/lib/ngstoned/certs) rather than hardcoding /var/lib/private/... — the literal private path silently becomes a different, unmanaged directory if DynamicUser is ever removed from the unit.
Binding to port 443#
AmbientCapabilities=CAP_NET_BIND_SERVICE lets the process bind privileged ports without running as root. It composes cleanly with both DynamicUser=yes and NoNewPrivileges=yes — NoNewPrivileges only blocks privilege gain via setuid binaries or file capabilities; it does not strip an ambient capability the service manager itself granted.
Secrets#
Never pass secrets as ExecStart flags
/proc/<pid>/cmdline is world-readable on stock Linux, so a token hash or API token passed as a command-line flag is readable by any local user via ps auxww. Put NGSTONE_DATABASE_URL, NGSTONE_EDGE_ID, NGSTONE_PEER_ADDR, NGSTONE_CREDENTIALS_FILE, NGSTONE_TOKEN_SHA256, NGSTONE_ADMIN_TOKEN_SHA256, and your DNS provider's credentials (for Cloudflare, NGSTONE_CF_API_TOKEN) in the unit's EnvironmentFile=instead. Other DNS providers' credentials have no flags at all. (The plaintext token itself, NGSTONE_TOKEN, belongs on the agent side, not on the VPS.)Configure NGSTONE_DATABASE_URL to SQLite for a single edge or to the same PostgreSQL URL on every edge in an active/active group, with a distinct NGSTONE_EDGE_ID per edge. For any edge to serve any tunnel, each edge also sets NGSTONE_PEER_ADDR to a private ip:portthat only the other edges can reach; without it, a request is served only by the edge holding the tunnel's connector. Issue credentials with ngstone admin credentials issue through the loopback API. Each credential is limited to one subdomain (HTTP or TLS) or TCP port and has a bounded TTL; credentials revoke invalidates it independently. OIDC browser login is available for team access to the management API; configure the provider group mappings and keep the client and cookie secrets in EnvironmentFile=. Team members and automation can authenticate with client certificates on a dedicated mTLS listener (NGSTONE_ADMIN_MTLS_ADDRand NGSTONE_ADMIN_MTLS_CLIENT_CA). The management API uses loopback access by default; configure NGSTONE_ADMIN_TOKEN_SHA256 only when a private, TLS-protected automation path is required.
Local ops dashboard#
By default, ngstoned exposes a read-only operations dashboard on 127.0.0.1:4041. It shows routed tunnels, connector capacity, request counters, per-tunnel latency/status/byte metrics, certificate expiry, and recent in-memory edge events. Reach it from your workstation with an SSH forward:
The management API exposes GET /api/v1/observability/tunnelsand the Prometheus endpoint exposes the same per-tunnel counters. Configure NGSTONE_ALERT_WEBHOOK_URL and optionallyNGSTONE_ALERT_WEBHOOK_TOKEN for non-blocking lifecycle alerts covering reconnects, lease loss, and expired or revoked credentials.
$ ssh -L 4041:127.0.0.1:4041 root@example.com$ open http://127.0.0.1:4041/The same listener serves /api/state as JSON and /metrics in Prometheus text format. Keep the -ops address on loopback. The dashboard remains read-only, while /api/v1 provides authenticated management operations:
$ ngstone admin status$ ngstone admin tunnels --json$ ngstone admin observability --json$ ngstone admin credentials issue --subdomain demo --ttl 24h$ ngstone admin policies list$ ngstone admin domains list$ ngstone admin tunnel drain demoThe CLI defaults to http://127.0.0.1:4041 and is intended to run through the SSH forward above. Set NGSTONE_ADMIN_TOKEN when the edge has an admin token hash. Set -ops "" to disable the entire listener.
Do not expose the ops listener
/api/v1. If -ops is changed to a public address, the dashboard,/api/state, metrics, health, and pprof remain separate endpoints. Put the listener behind a private network, firewall, and TLS-authenticated proxy instead.Restart behavior#
Restart=always means a crash or OOM typically recovers in under two seconds. Because certificates are cached under StateDirectory, a restart makes zero ACME traffic — provided the unit is configured correctly. Get DynamicUser/StateDirectorywrong and every restart instead re-issues against Let's Encrypt's rate limits, which is the failure this unit is written specifically to avoid.