# DNS {% embed url="" %} ## 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. ![](https://1465744049-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSqMcN3gvfPLhO0hh4agC%2Fuploads%2FspNeyZq6jxic54XHR7lO%2Fdns1.png?alt=media\&token=2a3a0135-0a36-4703-9a21-dda321ce394f) * **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. {% hint style="warning" %} Important: When using an internal DNS server, ensure peers can access it via an egress gateway; without a valid route, DNS queries will fail. {% endhint %} ### 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: ```plaintext Match domain: iot-network.corp.com Search domain: enabled ``` ![](https://1465744049-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSqMcN3gvfPLhO0hh4agC%2Fuploads%2FTnHChAvoIUQvMthfIzS4%2Fdns2.png?alt=media\&token=d3d313f3-3149-43fc-b20d-e163796c190b) Then a query for: ```plaintext ping gateway-O1 ``` will automatically be expanded by the system resolver into: ```plaintext 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: ```plaintext .. ``` The DNS base domain is set under **Settings → System Configuration**. Examples: ```plaintext 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: ```plaintext 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. ![](https://1465744049-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSqMcN3gvfPLhO0hh4agC%2Fuploads%2FVAiTkxdpHhgK1MA5KweO%2Fdn3.png?alt=media\&token=d1904ab7-66d2-4729-9d01-ec6c1a2119cd) ### Key Features of Manage DNS {% stepper %} {% step %} ### 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. ![](https://1465744049-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSqMcN3gvfPLhO0hh4agC%2Fuploads%2F8VOM6vxjsQC279ToqI4s%2Fdns4.png?alt=media\&token=570d3083-2b3b-4866-aec3-7e2e7502055b) It is independent of CoreDNS and does not require CoreDNS to be enabled. {% endstep %} {% step %} ### Domain Name Format Each device registered in the network is automatically assigned a domain name in the format: `..` Example: `deviceA.networkA.corp.com` {% endstep %} {% step %} ### 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. {% endstep %} {% step %} ### 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 `..`, where the DNS base domain is configured under Settings → System Configuration. ![](https://1465744049-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSqMcN3gvfPLhO0hh4agC%2Fuploads%2F4taEsTURQFr4uHpMa3aW%2Fdns5.png?alt=media\&token=444b829e-a2e2-484f-9b00-75661a7984f1) {% endstep %} {% endstepper %} ## 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: ```bash 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: {% stepper %} {% step %} Make sure that UDP Port 53 and TCP Port 53 are allowed to pass in the network where your Netmaker server lies. {% endstep %} {% step %} Disable systemd-resolved (Reason: to avoid port conflict with CoreDNS server): ```plaintext sudo systemctl disable systemd-resolved.service sudo systemctl stop systemd-resolved ``` {% endstep %} {% step %} Make sure `network_mode: host` is set on the CoreDNS container spec in `/root/docker-compose.yml` and run: ```plaintext docker-compose up -d ``` {% endstep %} {% endstepper %} 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: * Mac: * Windows: 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. ![](https://docs.netmaker.io/Base64-Image-Removed) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://learn.netmaker.io/features/dns.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.