DNS

NetBird provides private DNS capabilities that allow you to:

Resolve private domain names within your network
Use custom nameservers for specific domains
Implement split DNS configurations
Control DNS resolution per peer group

DNS Architecture

NetBird’s DNS system consists of two main components:

1. Nameserver Groups

Nameserver groups define DNS servers and the domains they handle. Each group specifies:

List of DNS nameservers
Domains to match
Peer groups that should use this DNS configuration
Whether the nameserver group is primary or domain-specific

2. DNS Settings

Account-level DNS settings control:

Which peer groups have DNS management disabled
Global DNS behavior

Nameserver Groups

A nameserver group contains DNS server configuration and distribution rules:

type NameServerGroup struct {
    ID                   string       // Unique identifier
    Name                 string       // Group name (1-40 chars)
    Description          string       // Purpose description
    NameServers          []NameServer // DNS servers (1-3 servers)
    Groups               []string     // Distribution groups
    Primary              bool         // Primary resolver
    Domains              []string     // Match domains
    Enabled              bool         // Active status
    SearchDomainsEnabled bool         // Add to search domains
}

Nameserver Configuration

Each nameserver specifies:

type NameServer struct {
    IP     netip.Addr       // DNS server IP address
    NSType NameServerType   // Server type (UDP)
    Port   int              // DNS port (typically 53)
}

Currently supported:

UDP nameservers: Standard DNS over UDP

Format: udp://1.1.1.1:53

NetBird validates that each nameserver group has between 1 and 3 nameservers. This limit ensures reliable DNS resolution without overwhelming client configurations.

Primary vs. Domain-Specific Nameservers

Primary Nameservers

Primary nameservers handle all DNS queries that don’t match domain-specific rules:

Name: "Default DNS"
Primary: true
Domains: []  # Empty for primary
NameServers:
  - udp://1.1.1.1:53
  - udp://8.8.8.8:53
Groups: ["all-peers"]

Characteristics:

Acts as the default/fallback resolver
Cannot have domains specified
Cannot have search domains enabled
Handles all queries not matched by domain-specific groups

Domain-Specific Nameservers

Domain-specific nameservers handle queries for particular domains:

Name: "Internal Services"
Primary: false
Domains: ["internal.company.com", "service.local"]
NameServers:
  - udp://10.0.0.53:53
Groups: ["employees"]
SearchDomainsEnabled: true

Characteristics:

Handles only specified domains
Must have at least one domain
Can be added to search domains list
Takes precedence over primary nameservers for matched domains

What are search domains?

Search domains are automatically appended to incomplete hostnames. For example:With search domain company.com:

Query: server1 → Resolves as server1.company.com
Query: server1.company.com → Resolves as-is

This simplifies accessing internal resources by allowing short names.In NetBird:

Domains: ["company.com"]
SearchDomainsEnabled: true

Peers in the distribution groups can use server1 instead of server1.company.com.

Creating Nameserver Groups

DNS Configuration Examples

Basic Primary DNS

Name: "Public DNS"
Description: "Cloudflare public DNS for all queries"
Primary: true
Domains: []
NameServers:
  - udp://1.1.1.1:53
  - udp://1.0.0.1:53
Enabled: true
Groups: ["all-peers"]
SearchDomainsEnabled: false

Internal Domain DNS

Name: "Corporate Internal"
Description: "DNS for internal company domains"
Primary: false
Domains: ["internal.company.com", "corp.local"]
NameServers:
  - udp://10.0.0.53:53
  - udp://10.0.1.53:53
Enabled: true
Groups: ["employees", "contractors"]
SearchDomainsEnabled: true

Split DNS Configuration

# Primary for internet
Name: "Internet DNS"
Primary: true
NameServers:
  - udp://8.8.8.8:53
Groups: ["all-peers"]

# Internal domains
Name: "Private Networks"
Primary: false
Domains: ["private.company.com"]
NameServers:
  - udp://192.168.1.53:53
Groups: ["internal-team"]

# Cloud domains
Name: "AWS DNS"
Primary: false  
Domains: ["aws.company.com", "ec2.internal"]
NameServers:
  - udp://10.100.0.2:53
Groups: ["cloud-team"]

Development Environment DNS

Name: "Dev Environment"
Description: "DNS for development and testing"
Primary: false
Domains: ["dev.company.com", "test.local"]
NameServers:
  - udp://172.16.0.53:53
Enabled: true
Groups: ["developers", "qa-team"]
SearchDomainsEnabled: true

DNS Settings

Account-level DNS settings provide additional control:

type DNSSettings struct {
    DisabledManagementGroups []string // Groups with DNS management disabled
}

Disabled Management Groups

Peers in disabled management groups don’t receive DNS configuration from NetBird:

DisabledManagementGroups: ["external-contractors", "iot-devices"]

Use cases:

Exclude specific peers from NetBird DNS management
Allow peers to use their own DNS configuration
Prevent DNS conflicts on certain devices

When you add a group to disabled management groups, peers in that group immediately stop receiving DNS updates from NetBird. They will revert to their system’s default DNS configuration.

DNS Resolution Flow

When a NetBird peer needs to resolve a domain name:

DNS Validation

NetBird validates nameserver groups when creating or updating:

// From nameserver.go:validateNameServerGroup
func validateNameServerGroup(ctx context.Context, transaction store.Store, 
    accountID string, nameserverGroup *NameServerGroup) error

Validation rules:

Primary XOR Domains: Must be primary OR have domains, not both
Nameserver count: Must have 1-3 nameservers
Name uniqueness: Names must be unique within the account
Name length: 1-40 characters
Domain format: Domains must be valid DNS names
No wildcards: Wildcard domains (*.example.com) are not allowed for nameservers
Group existence: All referenced groups must exist
Search domains: Cannot enable search domains for primary nameservers

Domain Validation

// From nameserver.go:validateDomain
func validateDomain(d string) error

Domains are validated to ensure:

Valid DNS syntax
No wildcard prefixes
Proper punycode for international domains
Optional trailing dot (FQDN format) is allowed

Examples:

✅ "example.com"
✅ "api.service.local"
✅ "example.com." (FQDN with trailing dot)
✅ "münchen.de" (converted to punycode)
❌ "*.example.com" (wildcards not allowed)

DNS Updates and Peer Impact

Changes to nameserver groups and DNS settings trigger peer updates intelligently:

// From nameserver.go:areNameServerGroupChangesAffectPeers
func areNameServerGroupChangesAffectPeers(ctx context.Context, 
    transaction store.Store, newNSGroup, oldNSGroup *NameServerGroup) (bool, error)

Peer updates occur only when:

The nameserver group is enabled (or becomes enabled)
Distribution groups contain peers or resources
DNS settings changes affect groups with peers

This optimization minimizes unnecessary network updates.

DNS Event Logging

All DNS operations are logged for audit purposes: Nameserver group events:

NameserverGroupCreated: New nameserver group created
NameserverGroupUpdated: Nameserver group modified
NameserverGroupDeleted: Nameserver group removed

DNS settings events:

GroupAddedToDisabledManagementGroups: Group excluded from DNS management
GroupRemovedFromDisabledManagementGroups: Group included in DNS management

Event metadata:

meta := map[string]any{"name": nsGroup.Name}

DNS Best Practices

Use Descriptive Names

Name nameserver groups based on their purpose:✅ Good:

"Corporate Internal DNS"
"AWS VPC Resolver"
"Public Cloudflare DNS"

❌ Bad:

"DNS1"
"Nameservers"
"Test"

Implement Split DNS

Separate internal and external DNS resolution:

# Internet traffic
Primary: true
NameServers: [Cloudflare, Google]

# Internal domains  
Primary: false
Domains: ["*.company.com"]
NameServers: [Internal DNS]

This improves security and performance.

Use Multiple Nameservers

Configure 2-3 nameservers for redundancy:

NameServers:
  - udp://10.0.0.53:53   # Primary
  - udp://10.0.1.53:53   # Secondary
  - udp://10.0.2.53:53   # Tertiary

If one fails, clients automatically fail over to the next.

Limit Distribution Groups

Only distribute DNS configurations to peers that need them:

# Specific distribution
Groups: ["engineering", "cloud-team"]

# Not
Groups: ["all-peers"]

This reduces configuration size and improves performance.

Enable Search Domains Carefully

Only enable search domains when beneficial:✅ Enable for:

Internal company domains
Development environments
Private networks

❌ Avoid for:

Public domains
Third-party services
Primary nameservers

Incorrect search domain configuration can cause DNS resolution issues.

Test DNS Changes

Before deploying DNS changes widely:

Create a test nameserver group
Distribute to a small test group
Verify resolution works correctly
Expand to production groups

This prevents widespread DNS outages.

Common DNS Patterns

Corporate Split DNS

# Public internet DNS
Name: "Internet Resolution"
Primary: true
NameServers: ["udp://1.1.1.1:53", "udp://8.8.8.8:53"]
Groups: ["all-peers"]

# Internal corporate domains
Name: "Corporate Internal"
Primary: false
Domains: ["corp.company.com", "internal.local"]
NameServers: ["udp://10.0.0.53:53"]
Groups: ["employees"]
SearchDomainsEnabled: true

Multi-Cloud DNS

# AWS resources
Name: "AWS DNS"
Primary: false
Domains: ["aws.company.com", "ec2.internal"]
NameServers: ["udp://10.0.0.2:53"]
Groups: ["cloud-team"]

# Azure resources  
Name: "Azure DNS"
Primary: false
Domains: ["azure.company.com"]
NameServers: ["udp://10.1.0.2:53"]
Groups: ["cloud-team"]

# GCP resources
Name: "GCP DNS"
Primary: false
Domains: ["gcp.company.com"]
NameServers: ["udp://10.2.0.2:53"]
Groups: ["cloud-team"]

Environment-Based DNS

# Production
Name: "Production DNS"
Primary: false
Domains: ["prod.company.com"]
NameServers: ["udp://10.100.0.53:53"]
Groups: ["production-access"]

# Staging
Name: "Staging DNS"
Primary: false
Domains: ["staging.company.com"]
NameServers: ["udp://10.200.0.53:53"]
Groups: ["developers", "qa"]

# Development
Name: "Dev DNS"
Primary: false
Domains: ["dev.company.com"]
NameServers: ["udp://10.300.0.53:53"]
Groups: ["developers"]
SearchDomainsEnabled: true

Troubleshooting DNS

DNS Not Resolving

Check:

Is the nameserver group enabled?
Is the peer in the distribution group?
Is the peer’s group in disabled management groups?
Are the nameserver IPs reachable from the peer?
Is the domain correctly specified?

Verify with:

# Check NetBird status
netbird status

# Test DNS resolution
nslookup example.com
dig example.com

Split DNS Not Working

Ensure:

Domain-specific nameserver groups are not marked as primary
Domains are correctly specified without wildcards
Distribution groups include the affected peers
Primary nameserver exists for non-matched queries

Domain matching is exact - api.company.com won’t match nameserver group with domain company.com. You need to specify the full domain or use a broader match.

DNS Changes Not Applied

Possible causes:

Peer is offline - it will receive updates when it reconnects
Group membership is incorrect - verify peer is in distribution group
DNS management is disabled for peer’s group
Changes haven’t propagated yet - wait a few seconds

Force peer update:

netbird down
netbird up

API Reference

Key DNS management functions:

// Nameserver Groups
GetNameServerGroup(ctx, accountID, userID, nsGroupID) (*NameServerGroup, error)
ListNameServerGroups(ctx, accountID, userID) ([]*NameServerGroup, error)
CreateNameServerGroup(ctx, accountID, name, description, nameServers, 
    groups, primary, domains, enabled, userID, searchDomainsEnabled) 
    (*NameServerGroup, error)
SaveNameServerGroup(ctx, accountID, userID, nsGroup) error
DeleteNameServerGroup(ctx, accountID, nsGroupID, userID) error

// DNS Settings
GetDNSSettings(ctx, accountID, userID) (*DNSSettings, error)
SaveDNSSettings(ctx, accountID, userID, dnsSettings) error

Access Control - Overview of security model
Groups - Organize peers for DNS distribution
Routes - Network routing configuration
Policies - Access control rules

Get Started

Architecture

Deployment

Client Setup

Network Management

Security

Operations

DNS

DNS

DNS Architecture

1. Nameserver Groups

2. DNS Settings

Nameserver Groups

Nameserver Configuration

Primary vs. Domain-Specific Nameservers

Primary Nameservers

Domain-Specific Nameservers

Creating Nameserver Groups

DNS Configuration Examples

Basic Primary DNS

Internal Domain DNS

Split DNS Configuration

Development Environment DNS

DNS Settings

Disabled Management Groups

DNS Resolution Flow

DNS Validation

Domain Validation

DNS Updates and Peer Impact

DNS Event Logging

DNS Best Practices

Common DNS Patterns

Corporate Split DNS

Multi-Cloud DNS

Environment-Based DNS

Troubleshooting DNS

API Reference

​DNS

​DNS Architecture

​1. Nameserver Groups

​2. DNS Settings

​Nameserver Groups

​Nameserver Configuration

​Primary vs. Domain-Specific Nameservers

​Primary Nameservers

​Domain-Specific Nameservers

​Creating Nameserver Groups

​DNS Configuration Examples

​Basic Primary DNS

​Internal Domain DNS

​Split DNS Configuration

​Development Environment DNS

​DNS Settings

​Disabled Management Groups

​DNS Resolution Flow

​DNS Validation

​Domain Validation

​DNS Updates and Peer Impact

​DNS Event Logging

​DNS Best Practices

​Common DNS Patterns

​Corporate Split DNS

​Multi-Cloud DNS

​Environment-Based DNS

​Troubleshooting DNS

​API Reference

​Related Resources

DNS

DNS Architecture

1. Nameserver Groups

2. DNS Settings

Nameserver Groups

Nameserver Configuration

Primary vs. Domain-Specific Nameservers

Primary Nameservers

Domain-Specific Nameservers

Creating Nameserver Groups

DNS Configuration Examples

Basic Primary DNS

Internal Domain DNS

Split DNS Configuration

Development Environment DNS

DNS Settings

Disabled Management Groups

DNS Resolution Flow

DNS Validation

Domain Validation

DNS Updates and Peer Impact

DNS Event Logging

DNS Best Practices

Common DNS Patterns

Corporate Split DNS

Multi-Cloud DNS

Environment-Based DNS

Troubleshooting DNS

API Reference

Related Resources