some file

Extra DNS Labels

Extra DNS labels let you assign additional DNS names to peers beyond their default hostname. Other peers in your NetBird network can then reach the labeled peer using these names. When multiple peers share the same label, queries are resolved in round-robin order, providing basic DNS-based load balancing.

Prerequisites

Extra DNS labels require a setup key with the Allow Extra DNS Labels option enabled. Without this, the management server rejects the labels during registration.

Assigning Labels

Pass labels as a comma-separated list with the --extra-dns-labels flag:

netbird up --setup-key AAAA-BBB-CCC-DDDDDD --extra-dns-labels vpc1,api

You can also use the NB_EXTRA_DNS_LABELS environment variable, which is useful for containerized deployments:

Container environment

environment:
  - NB_SETUP_KEY=AAAA-BBB-CCC-DDDDDD
  - NB_EXTRA_DNS_LABELS=vpc1,api

This creates DNS records vpc1.netbird.cloud and api.netbird.cloud (or your custom peer DNS domain) pointing to the peer's NetBird IP. All other peers in the account can resolve these names.

To clear previously set labels, pass an empty string:

netbird up --extra-dns-labels ""

Labels must be valid DNS names: ASCII alphanumeric characters, hyphens, and underscores. Unicode domain names are not auto-converted to punycode. Maximum 32 labels per peer.

Wildcard Labels

You can use a wildcard prefix to match any single subdomain level:

netbird up --setup-key AAAA-BBB-CCC-DDDDDD --extra-dns-labels "*.myserver"

This creates a wildcard DNS record *.myserver.netbird.cloud. Any single-level subdomain query resolves to the peer's IP:

  • app1.myserver.netbird.cloud - resolves
  • app2.myserver.netbird.cloud - resolves
  • anything.myserver.netbird.cloud - resolves

Wildcard matching follows standard DNS rules (RFC 4592): only a single subdomain level is matched. deep.sub.myserver.netbird.cloud would not match *.myserver.netbird.cloud.

Wildcard labels are useful when running a reverse proxy on a peer that serves multiple applications on different subdomains. You don't need to add a new label each time you add an application.

Round-Robin Load Balancing

When multiple peers share the same label, DNS queries for that label rotate through all matching peers' IPs. For example, if three peers all register with the label api:

# On peer-1, peer-2, and peer-3:
netbird up --setup-key AAAA-BBB-CCC-DDDDDD --extra-dns-labels api

Queries for api.netbird.cloud from any other peer cycle through the three IPs, distributing connections across them.

This is DNS-level round-robin only. There is no health checking. If a peer goes offline, its IP may still be returned until the peer is removed from the network.