Skip to content
SHC Docs

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.

#rulingconsequence
N1public = 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.
N2netbird 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.
N3Even 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.

Ingress, read off the estate:

FILE ROUTER HOST UPSTREAM
ingress-corp_prod_netbird.yaml corp_prod_netbird_0 vpn.corp.bitspur.com netbird-dashboard:80
ingress-corp_prod_netbird.yaml corp_prod_netbird_1 vpn-api.corp.bitspur.com netbird-management:80

Reachability, from off-estate:

$ curl -o /dev/null -w '%{http_code} ssl_verify=%{ssl_verify_result}' https://vpn-api.corp.bitspur.com/api/users
401 ssl_verify=0
$ curl -o /dev/null -w '%{http_code} ssl_verify=%{ssl_verify_result}' https://vpn.corp.bitspur.com/
200 ssl_verify=0

401 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 netbird
netbird oidc keycloak oidc post_deployed 0
netbird postgres netbird-db postgres post_deployed 0

2. 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. Contrast license-broker/, whose README says “a vendor / SHC-infra component … never installed by customers”, and deploy/shc/marketplace/, whose app.yaml says 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.yaml sets out the estate’s two namespaces: *.corp.bitspur.com for “BITSPUR’S INTERNAL TOOLS, named for the ROLE they play in the company” versus *.selfhostedcloud.org for “THE PRODUCT’S OWN PUBLIC SERVICES”. netbird is vpn.corp.bitspur.com / vpn-api.corp.bitspur.com, role-named, internal namespace. It is BitSpur’s VPN, sitting beside projects=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_public
corp_prod_netbird_db_public corp_prod_keygen_db_public
corp_prod_marketplace_public corp_prod_license_broker_default
master_default_traefik_public master_default_traefik_default

The 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.

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.