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. Without a configured DNS suffix, a single-label hostname cannot be packaged into a DNS query; so the stub resolver never sees it and therefore the query never reaches the Enclave Gateway. When no DNS search suffix is configured, single-label hostname lookups do not result in unicast DNS queries and are resolved exclusively via local name-resolution mechanisms (mDNS, LLMNR, NetBIOS, hosts).

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, whereas appending the domain suffix (e.g., printer.corp.example.com) 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.corp.example.com (a Fully Qualified Domain Name):

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

> printer.corp.example.com
Server:  wd764.id.enclave
Address:  100.111.244.29

Name:    printer.corp.example.com
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.

Name resolution order¶

When an application requests resolution of a name, the Windows DNS Client service evaluates it in sequence:

Local name check — the client checks if the queried name is its own hostname.
Hosts file — the system searches the local Hosts file for a matching entry.
DNS servers — if a Name Resolution Policy Table (NRPT) rule matches the query, it is processed according to that rule; otherwise the query is sent to configured DNS servers in priority order. This is the point at which the local Enclave stub resolver has the opportunity to answer received queries. For single-label names, Windows appends any configured DNS suffix to create an FQDN before querying.
NetBIOS fallback — if DNS does not resolve the name, Windows falls back to NetBIOS name resolution (LLMNR and NBNS). Microsoft is phasing out NetBIOS and LLMNR in favour of mDNS; starting with Windows 11, NetBIOS is only used after mDNS and LLMNR queries fail.

Additional considerations:

mDNS and .local — names ending in .local are reserved by RFC 6762 for multicast DNS (mDNS), which sends queries to the link-local multicast address 224.0.0.251. macOS, iOS, Android 12+, and Linux (systemd-resolved) resolve .local names via mDNS only and do not forward them to unicast DNS servers. Windows sends .local queries to both mDNS and configured unicast DNS servers. Using .local for an Active Directory domain can cause conflicts with mDNS resolution.
Special-use domains — .localhost resolves to loopback; .test, .invalid, and .example are reserved by RFC 6761 for testing and documentation. These names should not be expected to resolve via Enclave.

Resolution delays

For single-label names, Windows may dispatch mDNS, LLMNR, and NetBIOS queries. Even if one method returns a valid response quickly, Windows may wait for other methods to complete or timeout before using the result. NetBIOS retries (approximately 750ms × 3 attempts) can introduce delays of over 2 seconds. Disabling NetBIOS name resolution can eliminate this delay.

Implications

Without a DNS search suffix, no unicast DNS query is generated for single-label hostnames. The Enclave stub resolver never sees the request, and the query cannot reach the Enclave Gateway.
With a DNS suffix or search list, single-label names are expanded into FQDNs and forwarded to DNS servers, allowing them to reach the Enclave stub resolver.

Cause¶

An FQDN consists of multiple labels separated by dots (e.g., printer.corp.example.com), allowing for unambiguous resolution across networks. Single-label hostnames (e.g., printer) lack this structure. Without a configured DNS suffix, the operating system will not generate a DNS query for a single-label name, so it never reaches the Enclave stub resolver or Gateway.

Operating system behavior:

When a single-label hostname is used, the operating system attempts resolution using local methods. On Windows, this includes mDNS, LLMNR, and NetBIOS running in parallel. If a DNS suffix is configured, Windows also appends the suffix to create an FQDN and queries DNS servers.
If no DNS suffix is configured, no DNS query is generated. The single-label name is handled entirely by local resolution methods. The Enclave stub resolver never sees the request.

Interaction with the Enclave Gateway:

The Enclave stub resolver only receives DNS queries. Since single-label names without a suffix cannot be expressed as DNS queries, they never reach the stub resolver and cannot be forwarded to the Enclave Gateway.
For the Enclave Gateway to resolve a hostname, it must arrive as an FQDN; either because the application used an FQDN directly, or because a DNS suffix was applied to convert a single-label name.

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¶

Using PowerShell:

Open a privileged PowerShell terminal and use the Set-DnsClientGlobalSetting cmdlet to configure a global search suffix substituting corp.example.com as appropriate.
```
PS C:\> Set-DnsClientGlobalSetting -SuffixSearchList "corp.example.com"
```

Use the Get-DnsClientGlobalSetting to confirm the change.

PS C:\> Get-DnsClientGlobalSetting

UseSuffixSearchList : True
SuffixSearchList    : {corp.example.com}
UseDevolution       : True
DevolutionLevel     : 0

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=corp.example.com).

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 corp.example.com
```

macOS¶

Using System Settings:

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

Using the Command Line:

Use this command to set the search domain:
```
sudo networksetup -setsearchdomains Wi-Fi corp.example.com
```
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, and forwarded on to available Enclave Gateways to be correctly resolved.

If you are running an Enclave Gateway on Linux and need to resolve .local domains, the Gateway's host OS must also be configured to forward .local queries to DNS servers rather than mDNS. See gateway DNS and the .local domain for configuration steps.

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

Last updated December 18, 2025