DocsAPI

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.

  • 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.

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 user@server-endpoint.iot-network.corp.com

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 WG 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

  1. 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.

  2. Incorrect IP in Cache:
    If ping, nslookup, or dig returns an old IP, flush the local DNS cache:
    resolvectl flush-caches.

  3. 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 corendns container running as well. You need to make some changes manually to activate the corendns 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 the systemd-resolved (Reason: to avoid port conflict with coredns server)

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

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

And now you can point any machine in the network to use this DNS server and you can reach the other peers in the network 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. Here are some general help guides on how to add custom DNS server:

  1. Linux - https://devilbox.readthedocs.io/en/latest/howto/dns/add-custom-dns-server-on-linux.html. Configuration depends on what distribution of Linux you use.

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

  3. 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, you might want to 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.