Hosting and Exposure — Guardian — VeilNet documentation

Inbound Port

The guardian stack publishes a single port, 443/tcp. The front door, a reverse proxy, terminates TLS on that port and routes each request by its path:

Path	Goes to	Used by
`/auth/*`	Identity service	Operators' browsers, for sign-in and identity administration
`POST /nodes/<id>/credential`	API server	Machines that renew, including a machine whose credential has expired
Telemetry (OTLP)	Telemetry intake	Machines that export metrics and flow records
Everything else	Operator console	Operators' browsers

Nothing else is published. The state store and the metrics store sit on an internal network with no route off the host. Operators reach the API server only through the console. Your bootstrap nodes run on your own machines, not on this host.

Fig. 01 — One port in, two ways out

Operators and machines reach the guardian on 443/tcp, and on no other port. Two connections leave the stack. For an online deployment only, the guardian renews the realm credential with VeilNet, and a failure stops nothing. The admin nodes send UDP out to your own bootstrap nodes, and nothing connects back in. The state store and the metrics store sit on an internal network with no route off the host.

Outbound Connections

The stack opens two kinds of outbound connection:

Connection	When	If it fails
Realm credential renewal, over HTTPS to VeilNet. Redirects are not followed.	Online deployments only. An offline credential has no renewal address, so the guardian never makes this call.	The guardian records the failure and tries again. Nothing stops.
UDP from the admin nodes, in the API server's container, to each of your bootstrap nodes	Always. Nothing connects back in.	In-band telemetry shows machines as unreachable, and the console refuses control actions until a route exists.

Nothing in the stack needs the internet. In brokered mode, the identity service also connects to your identity provider, which can stay inside your network.

Turning console control off does not change these connections. With GUARDIAN_CONSOLE_CONTROL=off, the admin nodes still connect out to request telemetry. See Console Control.

Address and Certificate

GUARDIAN_HOST is the one address that operators and machines use to reach the guardian. It does not need to be public, or even in DNS. Use it exactly as you set it, because sign-in redirects and the renewal address in every manifest are built from it.

The address can take three forms:

An IPv4 address, which works as it is.
A DNS name. Create the record yourself, in internal DNS or as a hosts entry on each operator's machine and each node.
localhost, with the port kept off the network. Use it to try the console through an SSH tunnel. No machine can renew against it.

GUARDIAN_TLS sets where the front door gets its certificate:

GUARDIAN_TLS	Where the certificate comes from
`internal`	The guardian's own certificate authority. This is the default, and it works offline. Install `secrets/tls/ca-public/ca.crt` as trusted on every operator's machine and every node. Otherwise browsers show warnings and machines refuse to renew.
`own`	Your own certificate and key, named by `GUARDIAN_TLS_CERT` and `GUARDIAN_TLS_KEY`. Setup checks that the key matches and that the certificate names the address. When you renew the certificate, run setup again to copy in the new files.
`acme`	A certificate that the front door fetches and renews from a public ACME authority. The address must be in public DNS and point at this host, and the host needs internet access.

Guardian console — SettingsIllustrative

Settingsguardian-adminSettingsHow this guardian stack is configured, read back from the API and the deployment.Read-only. The API has no settings routes — every value here is set on the host, and each one names where.GeneralWhere this stack lives and what it answers to.Deployment nameTaken from the realm credential; shown in the sidebar and on every manifest.Northern Commandguardian.guardian_nameApp URLWhere an operator's browser reaches this console. Sign-in redirects are built from it, so the browser has to use exactly this address.https://guardian.example.govGUARDIAN_HOST · secrets/.envJurisdiction profilePassword policy, session lengths, audit settings and the system-use notice, rendered into the sign-in realm.au-ismGUARDIAN_PROFILE · secrets/.envPublishedThe front door on 443 is the only port this stack publishes; the console, sign-in, the renewal route and OTLP are all behind it.0.0.0.0:443GUARDIAN_BIND_ADDR · secrets/.envCertificateWhere the front door's certificate comes from. With the stack's own CA, browsers and nodes trust secrets/tls/ca-public/ca.crt.internalGUARDIAN_TLS · secrets/.env

Firewall Rules

Add these rules to the guardian host's firewall:

0 of 4 done

Allow traffic to the address in GUARDIAN_BIND_ADDR from the networks your operators and machines use. By default, the stack listens on every address.

Edge Protections

The stack protects its published port in these ways:

Protection	What it does
Unauthenticated access	Without sign-in, the API server answers only two health probes and the renewal route. Each machine renews with its own secret, and every refusal looks the same to the caller.
Rate limits	The renewal route accepts 10 requests a minute from one source. Every other API route accepts 120 requests a minute.
No caching	Every response from the API server and the console carries Cache-Control: no-store. No browser or intermediate cache keeps a manifest or a control credential.
Telemetry credentials	The telemetry intake accepts data only with a machine's own collector credential, which is separate from its renewal secret. Revoking a machine cuts off its telemetry at once.

Planning a Deployment

To prepare the host and run setup, see Deploying a Guardian.
For a host with no route out, see Air-Gapped Installation.
To see where the guardian fits in a sovereign network, see Sovereign Networks.

Inbound Port

Outbound Connections

Address and Certificate

Firewall Rules

Allow 443/tcp in+

Allow the renewal call out+

Allow the admin nodes out+

Narrow 443 to your own ranges+

Edge Protections

Planning a Deployment