Running the edge on a VPS
ngstoned is the half of ngstone that lives on the public internet. This guide walks through DNS, certificates, and starting the process on a fresh Linux VPS.
DNS setup#
Point two records at your VPS's IP address: a wildcard covering every tunnel, and an apex record for the control plane.
amber-fox-42.ngstone.site, api.ngstone.site, and so on.4443, which the agent connects to.ACME and DNS-01#
Certificates are issued via the DNS-01 challenge, using a libdnsprovider — Cloudflare in the reference setup. DNS-01 is the only ACME challenge type that can issue a wildcard certificate; HTTP-01 and TLS-ALPN-01 can't. It also means individual tunnel names never appear in a Certificate Transparency log, since one wildcard cert covers all of them.
The DNS provider needs a scoped API token — Zone:DNS:Edit on the one zone you're using, nothing broader.
Starting ngstoned#
There's no ngstone token command — generate a token yourself first, and hash it:
$ TOKEN=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')$ HASH=$(printf '%s' "$TOKEN" | shasum -a 256 | cut -d' ' -f1) # sha256sum on LinuxWith DNS in place, start the edge with your domain, a certificate contact email, a scoped Cloudflare API token, and the hash above:
$ ngstoned --domain ngstone.site --cert-email you@ngstone.site \ --cf-api-token "$CF_API_TOKEN" --token-sha256 "$HASH"On first boot, ngstoned requests both certificates and starts listening — it does not generate or print a token itself; the edge only ever stores the hash you gave it. Keep $TOKEN for ngstone authon whichever machines will run the agent. From here it's typically run as a systemd service — see Deployment & systemd.
Apex vs wildcard certs#
This is two independent certificates, not one multi-domain cert. A wildcard for *.ngstone.site does not match SNI ngstone.site — a wildcard covers exactly one left-most label — so the control plane on port 4443 needs its own apex certificate, issued and renewed on its own schedule.
A healthy wildcard can hide a dead apex
ngstoned performs a startup check that a valid apex cert is loadable before it accepts connections on :4443, and exits loudly rather than listening with a certificate it can't serve.Health checks#
/healthz, served on the loopback-only ops endpoint at 127.0.0.1:4041, reports each certificate's NotAfter separately — check both, not just one. The same ops endpoint also exposes expvar counters and pprof, reachable over an SSH tunnel:
$ ssh -L 4041:127.0.0.1:4041 you@ngstone.site$ curl http://127.0.0.1:4041/healthz