Skip to content
SHC Docs

NetBird

These answers used to sit on this app’s store listing. They moved here on 2026-08-17: a shopper deciding whether to install is not reading six hundred words of Q&A, and the listing page is the pitch. The knowledge is no less true for being off the storefront: it is the part you want before you commit, which is what a guide is for.

No. That is the point of a mesh built on WireGuard with a signal server in front of it. Peers negotiate a direct path where they can, and fall back to the relay in this deployment where they cannot.

In the PostgreSQL this deployment uses, behind a datastore encryption key held in your own vault. There is no external directory of your network to subpoena, breach or lose.

In practice yes: the OIDC settings are how the dashboard and the peers authenticate at all. In this catalogue that provider is the estate’s own Keycloak, and binding it also supplies the console’s allowed origin.

A NetBird client resolves a hostname through the zones NetBird serves it. A name missing from the zone falls through to public DNS, the client leaves the tunnel, and an app behind the LAN allowlist refuses it. SHC keeps the zone in step with what it routes, so nobody adds a record by hand.

Create the zone in NetBird first (DNS, Zones), distributed to the groups that should resolve it. SHC writes records into a zone and does not create one, and it writes only into a zone you declare by its own name: a NetBird zone below a declared one is left alone. Then connect it. The token is a NetBird personal access token, and the command asks for it:

Terminal window
shc connection connect netbird --type netbird \
--zone corp.example.com --purpose private --scope system -t master \
--cred api_url=https://vpn.example.com --cred token=-

A netbird connection requires --purpose private. --purpose public is refused (X400914DNSOVP).

From then on every host SHC routes under that zone gets an A record there on install and loses it on uninstall. The public record is still published.

Which address. dns.lan_address when it is set. Otherwise the underlay address of the node the system Traefik runs on, if that address is private. SHC never publishes the public address into this zone. shc dns ls prints the address in use and says when it was derived, and the daemon logs X200990DNSOVD once per start. Pin it with:

Terminal window
shc config set dns.lan_address 10.0.0.8 --scope global

With neither, the zone gets no records, each host logs X200921DNSPRV, and shc dns ls warns that the overlay plane publishes nothing.

Marker records. NetBird records have no owner field and no TXT type, so SHC keeps its ownership claim for a host as a second record at the host’s claim name, _shc-owner.<host>, a CNAME into shc-owner.invalid. Leave these alone. SHC removes a host’s record only when its marker names this cluster. A record with no marker, one you added in the dashboard for instance, is never removed. When SHC routes that same host it claims the record first and corrects it on the next pass. Host labels starting with _shc-owner, and _acme-challenge, are refused in this zone (X400118DNSNBR).

Why a new zone fills in over a few minutes. NetBird pushes the network map to every peer on each record write. A replay of every host (once per leadership term, and again when the ingress changes) makes at most 10 writes, logs how many it deferred (X200930DNSWBS) and continues a minute later. A host that does not resolve yet is written before the claims of hosts that already do. A host whose address or record type changes has its record rewritten in place, so the name answers throughout. If the deferred count stops going down for three passes the replay stops (X200937DNSWBX) until the ingress changes or the leader moves. An install, an update and an uninstall are not held back.

A deployment pinned to one DNS provider (--dns-provider) publishes only there and gets no record in the NetBird zone.