NetBird
Before you install
Section titled “Before you install”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.
Do I have to open ports on each machine?
Section titled “Do I have to open ports on each machine?”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.
Where does the peer list live?
Section titled “Where does the peer list live?”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.
Do I need Keycloak?
Section titled “Do I need Keycloak?”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.
Private DNS for VPN clients
Section titled “Private DNS for VPN clients”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:
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:
shc config set dns.lan_address 10.0.0.8 --scope globalWith 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.