DocsAPI

DNS

DNS in NetmakerCopied!

Manage DNS is a powerful feature that enables devices in a Netmaker network to communicate using domain names instead of hard-to-remember IP addresses. This feature simplifies network management and improves usability, especially in larger or more dynamic environments. Currently, Manage DNS is supported only on Linux-based devices.

Why Use DNS?Copied!

Using DNS (Domain Name System) in a network offers several key advantages:

  1. Human-Friendly Communication:

    • Instead of memorizing and typing complex IP addresses (e.g., 10.207.89.124), users can use simple, descriptive domain names (e.g., deviceA.networkA).

    • This makes it easier to manage and interact with devices in the network.

  2. Scalability:

    • As networks grow, managing IP addresses becomes increasingly challenging. DNS allows for seamless scaling by assigning meaningful names to devices, regardless of how many are added.

  3. Improved Organization:

    • Domain names can reflect the purpose or location of a device (e.g., printer.office or sensor.warehouse), making it easier to identify and manage devices within the network.

By leveraging DNS, Netmaker's Manage DNS feature brings these benefits to your virtual network, making it more intuitive, scalable, and manageable.

Key Features of Manage DNSCopied!

  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.

    • 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>
      Example: deviceA.networkA.

  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. extClient Configuration:

    • Manage DNS is supported on extClient if the DNS field is specified in the WireGuard config file:
      DNS = <Remote Access Gateway IP>
      Replace <Remote Access Gateway IP> with the IP of the Remote Access Gateway in your network.

    • Additional manual setup may be required depending on the DNS configuration of the operating system.

Operating System-Specific Setup for extClientCopied!

The DNS configuration for extClient depends on the operating system's DNS management system. Below are the setup instructions based on the DNS mode used by the operating system:

1. systemd-resolved (STUB Mode):

  • No extra manual changes are needed. The DNS settings are interface-specific and automatically removed when the interface is down.

  • Distributions using STUB mode by default:

    • Ubuntu (18.04 and later)

    • Fedora (recent versions)

    • Debian (with systemd-resolved enabled)

    • Arch Linux (with systemd-resolved installed and configured)

2. systemd-resolved (UPLINK Mode):

  • Edit /etc/systemd/resolv.conf and add:

    DNS = <Remote Access Gateway IP>

    Replace <Remote Access Gateway IP> with the IP of the Remote Access Gateway in your netmaker network.

  • Then restart systemd-resolved:

    systemctl restart systemd-resolved

  • Revert these changes after extClient is stopped or uninstalled.

  • Distributions that may use UPLINK mode:

    • Older or custom configurations of Debian or Ubuntu (if systemd-resolved is manually configured in UPLINK mode).

    • Some minimal or server-oriented distributions where systemd-resolved is not the default.

3. Other DNS Managers (e.g., /etc/resolv.conf):

  • Edit /etc/resolv.conf and add:

    nameserver <Remote Access Gateway IP>
search <network-name> .

    Replace <Remote Access Gateway IP> with the netmaker IP and <network-name> with the network name the extClient belongs to.

  • Revert these changes after extClient is stopped or uninstalled.

  • Distributions using /etc/resolv.conf:

    • CentOS (prior to CentOS 8)

    • RHEL (Red Hat Enterprise Linux, prior to RHEL 8)

    • Alpine Linux

    • Slackware

    • Older versions of Debian or Ubuntu (without systemd-resolved enabled).

4. resolvconf:

  • Manage DNS does not support resolvconf for netclient. Most modern Linux distributions use systemd-resolved instead.

  • Distributions using resolvconf:

    • Debian (if systemd-resolved is not enabled)

    • Ubuntu (prior to 18.04, or if systemd-resolved is disabled)

    • Devuan (a systemd-free fork of Debian)

    • Some lightweight or custom distributions.

Troubleshooting for netclient and extClientCopied!

  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.

  4. Debian 11 on Digital Ocean:

    • By default, resolvconf is installed and enabled, which conflicts with Manage DNS. To fix:

      • Remove resolvconf and enable systemd-resolved

        apt remove resolvconf
systemctl enable systemd-resolved
systemctl restart systemd-resolved

      • Then install netclient.

CoreDNSCopied!

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.

SummaryCopied!

  • Manage DNS simplifies device communication using domain names in Netmaker networks.

  • Minimal setup required for netclient; manual configuration may be needed for extClient depending on the OS DNS manager.

  • Troubleshooting steps provided for common issues like DNS restoration failures, cached IPs, and IPv6-only configurations.

  • CoreDNS (introduced in v0.22.0) replaces the deprecated hosts file method:

    • Netmaker server actively manages DNS entries via CoreDNS.

    • Ensure UDP/TCP Port 53 is open and systemd-resolved is disabled to avoid port conflicts.

    • Update the docker-compose.yml with the correct network mode for CoreDNS.