DNS

DNS in Netmaker

Netmaker includes a DNS management system (v1.1.0+), which lets you configure nameservers and manage DNS records directly in the admin UI.

Previously, DNS relied on manual CoreDNS configs. Now, DNS can be managed directly in Netmaker with no extra setup.

Why Use DNS?

• Simplifies connectivity – no need to memorize IPs; connect via hostnames.

• Consistency – devices always have a predictable name.

• Flexibility – supports both IPv4 and IPv6.

• Split DNS support – resolve only specific domains via a custom resolver.

Key Features

Name-servers

You can configure global or scoped nameservers for your network.

• Public resolvers: Google (8.8.8.8), Cloudflare (1.1.1.1), Quad9, etc.

• Custom resolvers: your own DNS infrastructure.

• Match Domain (Split DNS): send queries for specific domains (e.g., *.corp.local) to a given resolver.

• Search Domain: Adds the domain as a search suffix so peers can be resolved using short hostnames.

• Match All Queries: force all DNS traffic through the chosen resolver.

• Peer Scoping: apply DNS settings only to selected peers.

Important: When using an internal DNS server, ensure peers can access it via an egress gateway; without a valid route, DNS queries will fail.

Search Domain

The Search Domain option (available under Add/Edit Nameserver → Match domains) allows Netmaker to automatically append a specified domain when resolving unqualified hostnames.

When enabled, this feature simplifies hostname resolution for internal services — you can reach peers without typing their full domain names.

Purpose

The Search Domain setting helps clients resolve short hostnames by automatically completing them with a given domain suffix.

It’s especially useful in managed environments or when using internal DNS zones (e.g., corp.local, vpn.netmaker.io, iot-network.corp.com, etc.).

Example

If you configure:

Match domain: iot-network.corp.com
Search domain: enabled

Then a query for:

ping gateway-O1

will automatically be expanded by the system resolver into:

ping gateway-O1.iot-network.corp.com

and resolved using the configured nameserver(s).

Behavior Notes

• Applies only to unqualified hostnames (hostnames without dots, e.g., gateway-O2).

• The setting affects only local resolver behavior on connected peers — it does not change how records are created or stored in Managed DNS.

• Works with Stub and Static DNS modes, but does not work with Uplink mode.

• Search Domain toggle behavior:

  • ON: Example: gateway-O2 → system automatically tries gateway-O2.iot-network.corp.com.

  • OFF: Example: gateway-O2 → system tries just gateway-O2. Fully qualified hostnames like gateway-O2.server1.iot-network.corp.com still work.

DNS Records (Managed DNS)

Netmaker automatically creates DNS records for your nodes and gateways. These records make it possible to connect by hostname rather than IP address.

• Each netclient and gateway gets an auto-generated DNS record.

• Both IPv4 and IPv6 addresses are included.

• Records follow the format:

<node-name>.<network-name>.<dns-base-domain>

The DNS base domain is set under Settings → System Configuration.

Examples:

gateway-O1.iot-network.corp.com → 100.111.110.2, fd3c:e02d:d1b:8d7b::2

ny-office-egress.iot-network.corp.com → 100.111.110.4, fd3c:e02d:d1b:8d7b::4

server-endpoint.iot-network.corp.com → 100.111.110.1, fd3c:e02d:d1b:8d7b::1

Usage:

ping gateway-O1.iot-network.corp.com
ssh [email protected]

You can view and manage these from Networks → DNS → DNS Records in the admin UI.

Key Features of Manage DNS

1

How It Works

Manage DNS relies on the broker to synchronize DNS entries. Without the broker, the feature won't function properly.

It is an out-of-the-box feature that can be enabled by setting MANAGE_DNS=true in the netmaker.env file. Starting with version v0.99.0, this feature is configurable through the settings of your Netmaker dashboard.

It is independent of CoreDNS and does not require CoreDNS to be enabled.

2

Domain Name Format

Each device registered in the network is automatically assigned a domain name in the format:

<device-name>.<network-name>.<dns-base-domain>

Example: deviceA.networkA.corp.com

3

Netclient Configuration

No manual setup is required on the netclient side. The netclient automatically checks if Manage DNS is enabled during startup and activates the necessary DNS components.

4

Static Nodes Configuration

Manage DNS is enabled on static nodes by default, assigning the node’s gateway interface IP as the DNS. If a custom DNS is set in the WireGuard config under advanced settings when generating the conf file, Netmaker applies that instead.

Nodes resolve using the format <node-name>.<network-name>.<dns-base-domain>, where the DNS base domain is configured under Settings → System Configuration.

Troubleshooting for netclient and extClient

Failed DNS Restoration

If netclient fails to restore DNS settings:

• Check for a backup file at /etc/netclient/resolv.conf.nm.bkp. If it exists, replace /etc/resolv.conf with the backup.

• If no backup exists, manually edit /etc/resolv.conf to remove the Netmaker network IP and search domain.

Incorrect IP in Cache

If ping, nslookup, or dig returns an old IP, flush the local DNS cache:

resolvectl flush-caches

IPv6-Only extClient

If an IPv6-only device tries to connect via IPv4, edit the WireGuard config file and update the AllowedIPs section to include only IPv6 addresses/ranges.

CoreDNS (Legacy Method)

As of 0.22.0, CoreDNS is an active part of the Netmaker system. We deprecated setting entries on the hosts file which was not an ideal implementation. Netmaker server actively sets the DNS entries on the CoreDNS server. After you install the Netmaker server components, you can see the CoreDNS container running as well. You need to make some changes manually to activate the CoreDNS server; follow these steps on the Netmaker server:

1

Make sure that UDP Port 53 and TCP Port 53 are allowed to pass in the network where your Netmaker server lies.

2

Disable systemd-resolved (Reason: to avoid port conflict with CoreDNS server):

sudo systemctl disable systemd-resolved.service
sudo systemctl stop systemd-resolved

3

Make sure network_mode: host is set on the CoreDNS container spec in /root/docker-compose.yml and run:

docker-compose up -d

You can now point any machine in the network to use this DNS server and reach other peers by their domain names.

For external clients running Linux, make sure resolvconf is installed before setting the WireGuard configurations.

Refer to your operating system documentation for information about how to configure custom DNS network settings. General help guides:

• Linux: https://devilbox.readthedocs.io/en/latest/howto/dns/add-custom-dns-server-on-linux.html

• Mac: https://devilbox.readthedocs.io/en/latest/howto/dns/add-custom-dns-server-on-mac.html

• Windows: https://devilbox.readthedocs.io/en/latest/howto/dns/add-custom-dns-server-on-win.html

If your machine is virtually hosted in a cloud, refer to your VM provider’s documentation on how to permanently set the custom DNS resolver.

Summary

• v1.1.0+ introduces full DNS management in the UI: nameservers, split DNS (Match Domain), forced queries, and peer scoping.

• Managed DNS records give each node a predictable hostname.

• Legacy CoreDNS configs are only needed for older versions.