Single-label hostnames not resolved by Enclave Gateway¶

Single-label hostnames (e.g., printer) are not resolvable via the Enclave Gateway because, by default, the operating system doesn’t pass these requests to the local Enclave stub resolver. Single-label queries are typically handled by local resolution methods or augmented by any configured DNS suffixes before being passed to an external resolver. As a result, unless a DNS search suffix is correctly applied, single-label DNS queries never reach the Enclave Gateway.

This article explains why this occurs, how it impacts hostname resolution, and the steps administrators can take to configure DNS suffixes for proper resolution on Linux, Windows, and macOS systems.

Symptoms¶

Users may experience issues when trying to resolve single-label hostnames over the network using Enclave Gateway. For example, attempting to ping or nslookup a device by its single-label hostname (e.g., printer) fails, where appending the domain suffix (e.g., printer.mydomain.local) resolves successfully.

Example 1: Failing single-label hostname resolution

When attempting to resolve printer using nslookup:

C:\>nslookup
Default Server:  wd764.id.enclave
Address:  100.111.244.29

> printer
Server:  wd764.id.enclave
Address:  100.111.244.29

*** wd764.id.enclave can't find printer: Server failed

In this case, the system fails to resolve printer because the single-label hostname does not reach the Enclave Gateway for resolution.

Example 2: Successful FQDN resolution

However, when the user tries printer.mydomain.local (a Fully Qualified Domain Name):

C:\>nslookup
Default Server:  wd764.id.enclave
Address:  100.111.244.29

> printer.mydomain.local
Server:  wd764.id.enclave
Address:  100.111.244.29

Name:    printer.mydomain.local
Address: 192.168.1.16

The query succeeds, and the correct IP address 192.168.1.16 is returned, demonstrating FQDN resolution when the proper suffix is used.

Cause¶

Most DNS resolvers, including the Enclave Gateway, expect Fully Qualified Domain Names (FQDNs) to resolve hostnames accurately. An FQDN consists of multiple labels separated by dots (e.g., printer.mydomain.example.com), allowing for clear and unambiguous resolution across networks. However, single-label hostnames (e.g., printer) do not follow this structure, leading to the following challenges:

Operating system behavior:

When a single-label hostname is used, the operating system typically attempts to resolve it using local resolution methods such as NetBIOS, LLMNR, or mDNS. If these methods do not succeed, the OS then attempts to append any locally configured DNS search suffixes to convert the single-label hostname into an FQDN.
If no DNS suffix is configured, or if the local methods resolve the hostname, the OS doesn’t forward the single-label query to external DNS resolvers like the Enclave stub resolver.

Interaction with the Enclave Gateway:

Because single-label hostname queries often don’t reach the Enclave Gateway due to the default behavior of the operating system’s DNS resolution process, the Enclave Gateway remains unaware of these queries and, therefore, cannot resolve them.
For the Enclave Gateway to handle the resolution, the hostname must be an FQDN or converted into one via a correctly applied DNS search suffix. This ensures that the query reaches the Enclave stub resolver for processing.

Resolution¶

To ensure that single-label hostnames are resolvable via the Enclave Gateway, administrators should configure appropriate DNS search suffixes on the client machines. This configuration forces the operating system to append the specified DNS suffix to single-label hostnames, transforming them into FQDNs, which are then passed to the Enclave stub resolver for resolution.

The process of setting up DNS search suffixes differs across operating systems. Here’s how you can configure these suffixes on Windows, Linux, and macOS:

Windows¶

Manual configuration:

Open the Control Panel and navigate to Network and Sharing Center.
Click Change adapter settings.
Right-click the active network interface and select Properties.
Select Internet Protocol Version 4 (TCP/IPv4) and click Properties.
Click Advanced and navigate to the DNS tab.
In the DNS suffix for this connection field, enter your desired DNS suffix (e.g., mydomain.local).
Click OK to save the settings.

Using group policy:

Open the Group Policy Editor (gpedit.msc).
Navigate to Computer Configuration > Administrative Templates > Network > DNS Client.
Configure the Primary DNS Suffix and DNS Search List policies as needed.

Linux¶

Using systemd-resolved:

Edit /etc/systemd/resolved.conf:
```
sudo nano /etc/systemd/resolved.conf
```
Set your desired DNS suffix in the Domains= field (e.g., Domains=mydomain.local).

Restart the systemd-resolved service:

sudo systemctl restart systemd-resolved

Using /etc/resolv.conf:

Warning

If /etc/resolv.conf is managed by NetworkManager or DHCP on your system, do not follow these steps. Instead configure DNS suffixes using the relevant linux tooling.

Edit /etc/resolv.conf:
```
sudo nano /etc/resolv.conf
```
Add the line:
```
search mydomain.local
```

macOS¶

Using System Preferences:

Open System Preferences and go to Network.
Select your active network interface and click Advanced.
Go to the DNS tab and add your desired search domain in the Search Domains section.
Click OK and Apply.

Using the Command Line:

Use this command to set the search domain:
```
sudo networksetup -setsearchdomains Wi-Fi mydomain.local
```
Note

(Replace "Wi-Fi" with your network interface name if different)

Notes¶

Applying a DNS suffix allows the operating system to transform single-label hostname queries into fully qualified domain names, which can then be passed to the Enclave stub resolver, an forwarded on to available Enclave Gateways to be correctly resolved.

Having problems? Contact us at support@enclave.io or get help and advice in our community support channels.

Last updated September 26, 2024