netbird stays PUBLIC, and stays in corp, 2026-08-16
Owner ruling 2026-08-16, verbatim: “netbird stays PUBLIC: its management API is what peers dial to enrol, so LAN-only is circular.”
This document pins that ruling with the mechanism behind it, so the next person who reads “a VPN control plane on the public internet” as an obvious hardening target finds the reason it is not, before they change it.
It also answers the tenancy half, which the ruling did not have to ask
because netbird was never a candidate: netbird belongs in corp and is not
part of the “SHC’s own products leave the corp tenant” set.
| # | ruling | consequence |
|---|---|---|
| N1 | public = true stands. LAN-only breaks enrolment on two independent legs (DNS and TLS), and the second one cannot be worked around by a peer that has not joined yet. | No exposure change. Not now, not as a hardening sweep. |
| N2 | netbird stays in the corp tenant. It is a flagship catalogue app BitSpur runs as internal tooling, not an SHC vendor component. Its hosts are under corp.bitspur.com, the estate’s internal-tooling namespace. | It is not in the ruling’s product set at all. No tenant lane. |
| N3 | Even if someone wanted to move it, the platform refuses. Its closure spans scopes (keycloak@master), so a scope-changing -a move is refused up front with X400630CLNXSC. | The wrong answer is unavailable, not merely unwise. |
| N4 | ”Public” is an EXPOSURE axis, not a GATE. public = true + gated = false means internet-reachable with netbird’s own OIDC in front, not unauthenticated. | The hardening instinct is aimed at the wrong axis; the auth is already there. |
1. Measured, 2026-08-16
Section titled “1. Measured, 2026-08-16”Ingress, read off the estate:
FILE ROUTER HOST UPSTREAMingress-corp_prod_netbird.yaml corp_prod_netbird_0 vpn.corp.bitspur.com netbird-dashboard:80ingress-corp_prod_netbird.yaml corp_prod_netbird_1 vpn-api.corp.bitspur.com netbird-management:80Reachability, from off-estate:
$ curl -o /dev/null -w '%{http_code} ssl_verify=%{ssl_verify_result}' https://vpn-api.corp.bitspur.com/api/users401 ssl_verify=0$ curl -o /dev/null -w '%{http_code} ssl_verify=%{ssl_verify_result}' https://vpn.corp.bitspur.com/200 ssl_verify=0401 is the correct answer and the whole point of N4: the management API is
reachable and authenticated. ssl_verify=0 on both; publicly trusted
chain, resolver acme-prod-dns-hetzner.
Integration edges:
$ shc integration ls -t corp -e prod -s netbirdnetbird oidc keycloak oidc post_deployed 0netbird postgres netbird-db postgres post_deployed 02. Why LAN-only is circular: the mechanism, not the slogan
Section titled “2. Why LAN-only is circular: the mechanism, not the slogan”exposure is a two-value axis (internet | lan, modules/app/types.go).
Flipping netbird to lan changes two things, and each one alone is fatal to
enrolment.
Leg 1: DNS stops pointing at anything an outside peer can reach.
modules/app/dns_target.go publishes the traefik placement’s public
address only under internet; every other exposure takes the “historical
LAN fallback”: the node the system traefik runs on, else all swarm nodes, else
the advertise address. A laptop on a hotel network resolving
vpn-api.corp.bitspur.com would get an address it cannot route to.
Leg 2: the certificate stops being publicly trusted, and this is the one
that cannot be worked around. A publicly-trusted leaf is issued only for
exposure == "internet" && leEnabled; every other case (public_cert_host.go
names the set: “lan; OR no ACME provider resolved; OR internet with LE
disabled”) takes the SHC-signed leaf. SHC plants its own CA in the app
trust stores (inject_ca_trust.go), which is exactly the wrong side of the
problem here: the client that needs to trust it is a netbird peer that has
not joined yet, sitting on a machine SHC has never touched. It validates
TLS to the management API and fails.
That is the circle. A peer must reach the management API to enrol. Under LAN-only it can reach it only from inside the network, and the network it would need to be inside of is the VPN it is trying to join. There is no bootstrap order that works, which is why this is a design constraint and not a risk-appetite question.
The same holds for every self-hosted mesh control plane; it is not a netbird quirk. NetBird’s signal/relay path has the same requirement for the same reason.
3. “Public” is not “ungated”; the axis being aimed at is the wrong one
Section titled “3. “Public” is not “ungated”; the axis being aimed at is the wrong one”public (exposure) and gated (SSO forward-auth) are independent flags.
netbird runs public = true with its own OIDC integration to the master-realm
Keycloak (oidc → keycloak, measured above); the 401 is that auth
answering. The management API is authenticated today; making it unreachable
would not add authentication, it would remove availability from an endpoint
that already has authentication.
If the underlying worry is the dashboard rather than the API, that is a
different and answerable question (gated, CSP, IP allowlisting on the
dashboard host only) and it does not require touching public on
vpn-api.corp.bitspur.com.
4. Why netbird is not in the “SHC’s own products” set
Section titled “4. Why netbird is not in the “SHC’s own products” set”The ruling moves SHC’s own products out of corp. netbird is not one.
- It is a catalogue app:
apps/flagship/netbird/:app.yaml,vars.yaml,compose.yaml,oidc.plug.yaml,postgres.plug.yaml,backup.yaml, an exporter and tests. Customers install it on their own estates. Contrastlicense-broker/, whose README says “a vendor / SHC-infra component … never installed by customers”, anddeploy/shc/marketplace/, whoseapp.yamlsays it “is not a product anyone installs”. Those two are the vendor set. netbird is on the other side of that line. - Its hosts say so.
deploy/marketplace.shc.yamlsets out the estate’s two namespaces:*.corp.bitspur.comfor “BITSPUR’S INTERNAL TOOLS, named for the ROLE they play in the company” versus*.selfhostedcloud.orgfor “THE PRODUCT’S OWN PUBLIC SERVICES”. netbird isvpn.corp.bitspur.com/vpn-api.corp.bitspur.com, role-named, internal namespace. It is BitSpur’s VPN, sitting besideprojects=huly,knowledge=affine,grc=ciso,idm=midpoint.
So netbird is correctly placed. No tenant change.
5. And the platform would refuse the move anyway
Section titled “5. And the platform would refuse the move anyway”Worth recording because it is a nice independent confirmation rather than an argument anyone needs to win.
shc move refuses a scope-changing --all-connections move whose member
set is not scope-uniform: X400630CLNXSC, modules/clone/service.go:
refusing to move {member}: it lives in {member_scope} while the move targets {op_scope}, and a scope-changing move recreates every member in the operation’s scope, which would create a second copy of {member} there and destroy the original.
netbird’s closure is {netbird corp/prod, netbird-db corp/prod, keycloak master/default}; the keycloak edge is the magic-token cross-tenant provider
(ce/modules/app/integration_magic.go; the allowlist’s one in-tree row is
KEYCLOAK, always resolved at master/default). That set spans two scopes, so
a cross-tenant -a move of netbird is refused in preflight, read-only, before
anything is stopped.
(Contrast the license-broker closure, {license-broker, keygen, keygen-db},
all corp/prod; scope-uniform, so that one is allowed by this gate and has
to be stopped for entirely different reasons: shc_deployment.tenant is
RequiresReplace, terraform’s delete is shc uninstall … --yes (“full
teardown; backs up first”), and the third member is the Keygen licence
ledger. Written up in bitspur/ops hetzner/hel1/deployments/shc.tf, and see
the sibling ruling
docs/decisions/2026-08-16-marketplace-belongs-in-the-shc-tenant.md.)
6. ★ And while we are here: a tenant is an identity boundary, not a network one
Section titled “6. ★ And while we are here: a tenant is an identity boundary, not a network one”The instinct that produces “put the VPN control plane on the LAN” is the same
instinct that reads a tenant as a network. It is not one, and this estate
proves it. docker network ls, bitspur, 2026-08-16:
corp_prod_netbird_public corp_prod_keygen_publiccorp_prod_netbird_db_public corp_prod_keygen_db_publiccorp_prod_marketplace_public corp_prod_license_broker_defaultmaster_default_traefik_public master_default_traefik_defaultThe shape is <tenant>_<env>_<stack>_public, per stack. There is no
corp_* tenant-wide network for a stack to be inside of, so there is none for
a tenant move to take a stack out of. And every public deployment in every
tenant additionally joins the single shared ingress network
master_default_traefik_public; measured on the license-broker container,
which is attached to exactly three networks, that being one of them.
shc tenant --help calls a tenant owner of “its own stacks, overlay network,
and Keycloak realm”; the middle term is loose, and the same help text
corrects itself two lines later: “the network separation is a firewall policy
rather than a security boundary.” Read the firewall policy, not the sentence.
A tenant buys a Keycloak realm and a blast radius for identity. It buys no isolation, and nothing in this ruling set should be read as if it did.
7. If this is ever revisited
Section titled “7. If this is ever revisited”The bar is a bootstrap path that does not require the VPN to already work. Concretely, one of:
- an enrolment endpoint on a separate, publicly-trusted host while the rest of the management API goes LAN-only (splits the surface, keeps the circle open); or
- out-of-band peer provisioning (pre-seeded setup keys and a pre-planted CA bundle on every device before it needs to join), which is an MDM programme, not a flag.
Neither is a flag flip, and until one exists, public = true is not a posture
choice. It is the only working configuration.