The Definitive Guide to Clean Hostname Resolution Across UniFi VLANs (2026 Edition)

VLANs should stay segmented without forcing administrators to memorize which IP address belongs to which machine.

Once a network grows past one flat subnet, IP addresses become a bad user interface.

Consider a UniFi environment with separate networks for management, normal clients, IoT, guests, and lab systems. The segmentation is useful, but it can create a small operational annoyance: remembering where everything lives.

The goal is to avoid this:

ssh admin@10.50.0.25

and make this work instead:

ssh admin@lab-server

The short name should work even when the client and server are on different VLANs.

The design becomes simple once two different DNS concepts are separated:

1. Give each VLAN its own DNS suffix.
2. Give clients a search list containing all of the suffixes they should try.

On a tested UniFi Network 10.6.101 deployment, that was enough to get clean, short-name resolution across a segmented network without maintaining a pile of manual DNS records.

Revision provenance: this guide is based on a working UniFi deployment and was rechecked against Ubiquiti’s current DHCP and local-DNS documentation plus RFC 3397 before publication. UniFi officially documents per-network Domain Name and Custom Options. The automatic DHCP-hostname behavior described below was verified on Network 10.6.101, so it should be treated as observed platform behavior rather than a promise that every historical release behaves identically.

What this guide builds

The finished design gives each VLAN a distinct DNS namespace while letting supported clients use short hostnames across those namespaces. A request for lab-server can resolve to lab-server.lab.example.com; a request for workstation can resolve to workstation.management.example.com; and the VLANs remain separate routing and firewall boundaries.

The path looks like this:

client requests: lab-server
        |
        v
DHCP search list
management.example.com
lab.example.com
default.example.com
iot.example.com
        |
        v
client tries qualified DNS names
        |
        v
UniFi gateway DNS
        |
        v
lab-server.lab.example.com -> current DHCP address

This is not mDNS, it does not flatten VLANs, and it does not bypass firewall policy. It is ordinary DNS resolution made easier for humans.

Before you begin

This guide assumes:

• a UniFi gateway is providing DHCP and DNS to the client VLANs;
• the clients you want to test are actually using the gateway as their DNS server;
• each VLAN has a stable role and a name you are comfortable putting into a DNS suffix;
• inter-VLAN routing and firewall policy already exist independently of this naming project;
• you control the parent domain you plan to use, or you substitute a private namespace you understand and can manage consistently.

Do not start by adding manual A records for every client. First prove whether your current UniFi release already registers DHCP hostnames under the configured network Domain Name. If it does, you can let DHCP and DNS stay synchronized automatically.

The target design

Use a subdomain per network role.

For example:

Network	VLAN	DNS suffix
Management	110	management.example.com
Default	120	default.example.com
IoT	130	iot.example.com
Guest	140	guest.example.com
Lab	150	lab.example.com

Replace example.com with a domain you control.

A host named lab-server on the Lab VLAN then gets a useful fully qualified name:

lab-server.lab.example.com

A workstation named workstation on Management becomes:

workstation.management.example.com

The important part is that the VLAN remains visible in the namespace. The name communicates both what the device is and where it belongs.

Why this guide avoids .local

This design intentionally avoids building around .local names.

.local is strongly associated with multicast DNS and Bonjour-style discovery. That is useful for zero-configuration discovery on a local segment, but it is not the naming model used here for routed VLANs.

Using a real subdomain under a controlled parent domain gives a cleaner split-DNS design:

lab.example.com
management.example.com
iot.example.com

The names can exist only inside the private network while the public parent domain continues to work normally on the Internet.

What UniFi is doing

There are three pieces involved.

DHCP assigns the client configuration

UniFi’s DHCP server gives clients their normal network settings such as the address, gateway, and DNS server. UniFi also supports an optional Domain Name and custom DHCP options.

UniFi’s DNS resolver answers the local names

In testing, setting the Domain Name on a UniFi network caused DHCP client hostnames to resolve beneath that network’s suffix.

For example, after setting the Lab network’s Domain Name to:

lab.example.com

this worked without a manually created Host record:

getent hosts lab-server.lab.example.com

and returned the current DHCP address for lab-server.

The same behavior was verified on another VLAN with a different client.

This is worth testing in your own environment before assuming it works exactly the same on every UniFi release or gateway model. The behavior described here was verified on UniFi Network 10.6.101.

DHCP Option 119 gives clients the search list

The missing piece is short-name lookup.

A DNS server can know that this exists:

lab-server.lab.example.com

but a client that asks only for:

lab-server

still needs to know which suffixes it should try.

That is the job of DHCP Option 119, formally the Domain Search option.

RFC 3397 defines Option 119 specifically for distributing a DNS search list to DHCP clients.

Step 1: configure the Domain Name on each VLAN

In UniFi Network, open each virtual network and find its DHCP settings.

The exact menu wording moves around between UniFi releases, but on current releases it is under the network’s DHCP service configuration.

Set the Domain Name for each network.

For example:

Management: management.example.com
Default:    default.example.com
IoT:        iot.example.com
Guest:      guest.example.com
Lab:        lab.example.com

Save the network configuration.

Do this before touching Option 119.

Step 2: verify full DNS names first

Before trying short hostnames, prove that the underlying DNS records work.

From a Linux client using the UniFi gateway for DNS:

getent hosts lab-server.lab.example.com

A successful result should look something like:

10.50.0.25    lab-server.lab.example.com

Test more than one VLAN if possible.

For example:

getent hosts workstation.management.example.com
getent hosts printer.default.example.com

If the fully qualified names do not resolve, stop here. Option 119 will not fix missing DNS records.

Step 3: add DHCP Option 119

Now add the shared search list.

Open a network in UniFi and choose Add Custom DHCP Option.

Use:

DHCP Option Name: Domain_Search
Type:             Text
Code:             119

For the value, enter the domains in the order clients should search them.

For example:

management.example.com,lab.example.com,default.example.com,iot.example.com

That comma-separated value is UniFi UI syntax, not the literal RFC 3397 wire format. RFC 3397 defines a compact DNS-label encoding for Option 119. On Network 10.6.101, UniFi accepts the text list in the custom-option field and delivers a working search list to tested clients. If a future UniFi release changes that input behavior, validate what the client actually receives instead of assuming the UI representation equals the packet encoding.

Guest is intentionally omitted from the normal search list unless there is a reason to resolve guest devices by short name.

Save the option.

Then add the same Option 119 search list to every VLAN where you want clients to receive it.

The per-network Domain Name stays different.

The Option 119 search list can be the same everywhere.

That distinction is the entire design.

Step 4: renew the client’s DHCP configuration

Existing clients may keep their previous DHCP options until they renew their lease.

The simplest test on a phone is usually:

1. Turn Wi-Fi off.
2. Turn Wi-Fi back on.
3. Reconnect to the network.

On a Linux workstation managed by NetworkManager, reconnecting the profile is enough:

sudo nmcli connection up "<connection-name>"

If the client has a manually configured DNS search list, remove that before testing DHCP-provided search domains. Otherwise you can accidentally prove that your manual configuration works instead of proving that Option 119 works.

For example:

sudo nmcli connection modify "<connection-name>" ipv4.dns-search ""

Then reconnect the profile.

Step 5: verify the search list on Linux

On a system using systemd-resolved, run:

resolvectl status

Or inspect only the active interface:

resolvectl status <interface>

A successful result should show the UniFi gateway as the DNS server and multiple search domains, for example:

DNS Servers: 10.10.0.1
DNS Domain: management.example.com lab.example.com default.example.com iot.example.com

At that point the client has everything it needs.

Step 6: test short hostnames

Now try a host that lives on another VLAN.

getent hosts lab-server

A successful answer should look similar to:

10.50.0.25    lab-server.lab.example.com

Then use the short name normally:

ssh admin@lab-server

The application does not need to know that the full record is really:

lab-server.lab.example.com

The resolver works through the search list for it.

This was also verified from an Android client. After renewing Wi-Fi, the client could connect to a Lab host using only the short hostname even though the client itself was not on the Lab VLAN.

At that point, the end-to-end behavior was proven.

How the lookup actually works

Suppose the client receives this search order:

management.example.com
lab.example.com
default.example.com
iot.example.com

And the client requests:

lab-server

Conceptually, the resolver can try:

lab-server.management.example.com
lab-server.lab.example.com
lab-server.default.example.com
lab-server.iot.example.com

The first valid answer wins.

That creates an important rule:

Do not casually reuse the same hostname on multiple VLANs.

If two networks both contain a device named server, short-name lookup becomes dependent on search order.

The fully qualified names remain unambiguous:

server.management.example.com
server.lab.example.com

But server alone may not mean what you think it means.

DNS resolution is not firewall access

This is one of the easiest mistakes to make after getting the names working.

If this resolves:

getent hosts lab-server

that proves DNS worked.

It does not prove the client is allowed to reach the service.

A client may correctly resolve:

lab-server -> 10.50.0.25

while the firewall correctly blocks TCP/22, HTTP, SMB, or every routed connection to that VLAN.

DNS naming and inter-VLAN policy solve different problems.

Keep the VLAN boundaries and firewall rules intact. The names simply make allowed paths easier to use.

This reduces the need for static IPs, but does not eliminate them

Once clients can reliably find systems by hostname, a changing DHCP address matters much less.

For a normal workstation, phone, printer, or lab endpoint, the literal address matters much less once name resolution is reliable.

If this keeps working:

ssh admin@lab-server

then it matters much less whether lab-server has one DHCP address today and a different address later.

Keep DHCP reservations or stable addresses for infrastructure where the IP itself is referenced somewhere else.

Examples include:

• firewall rules built around a specific address;
• NFS mounts using a literal IP;
• reverse proxies with hard-coded upstream IPs;
• monitoring targets configured by address;
• storage nodes;
• DNS, DHCP, or gateway infrastructure;
• anything another system cannot locate by DNS.

The goal is not to abolish stable addressing.

The goal is to stop using an IP address as the human-readable name for everything on the network.

Client compatibility matters

Option 119 is a DHCP standard, but clients still decide how to consume DHCP-provided search domains. This design was verified on Fedora Linux and on an Android client in the tested environment. That does not mean every operating system, VPN client, container runtime, or manually configured resolver will behave identically.

A VPN is a particularly easy place to get confused. VPN software can install its own DNS servers and search domains, change resolver priority, or intentionally route only selected DNS zones. If short-name resolution works before the VPN connects and fails afterward, inspect the client’s effective resolver state before changing UniFi.

The same rule applies to devices with hard-coded public DNS, encrypted DNS profiles, or manual resolver settings: if they are not querying the UniFi gateway for the internal name, the gateway cannot answer it.

Troubleshooting matrix

This design is easy to troubleshoot if the layers are tested separately.

Symptom	Most likely layer to inspect
FQDN resolves, short name does not	Search list / DHCP Option 119
Neither FQDN nor short name resolves	DNS registration, gateway DNS, client hostname, stale DHCP lease
Name resolves to the correct IP but connection fails	Firewall, routing, service listener, host firewall
Short name resolves to the wrong VLAN	Duplicate hostname or search-order collision
One device works and another does not	Client support for Option 119, cached DHCP state, manual DNS configuration
Public DNS works but internal names do not	Client may not be using the UniFi gateway as DNS

On Linux, these commands cover most of the useful checks:

resolvectl status
getent hosts lab-server
getent hosts lab-server.lab.example.com
resolvectl query lab-server

One subtle failure mode: manual search domains

A common testing trap is a pre-existing manual search domain.

For example, a Linux workstation may already have this manually configured:

lab.example.com

That made lab-server work before the network-wide Option 119 configuration was complete.

That is useful operationally, but it means the client is not a clean test of DHCP.

When validating centralized configuration, remove local overrides first.

Otherwise you can spend twenty minutes celebrating a DHCP configuration that the client never actually used.

Another subtle failure mode: the client does not send a hostname

Automatic local DNS depends on the gateway knowing a useful hostname for the client.

Some devices provide one cleanly through DHCP. Others use odd names, generic names, or no useful hostname at all.

If UniFi does not know the hostname you expect, inspect the client entry before assuming DNS is broken.

For infrastructure that needs a guaranteed name, a deliberate local DNS record may still be the better choice.

Version notes

This guide was verified on:

UniFi Network: 10.6.101
Gateway:       UniFi Cloud Gateway class device
Client tests:  Fedora Linux and Android

Older UniFi releases had reported problems with DHCP Option 119 handling. Community reports indicate the plain-text workflow was fixed in the 10.1.x generation, so anyone on an older release should verify the behavior before copying the configuration blindly.

The broader standards piece is not UniFi-specific. DHCP Option 119 is defined by RFC 3397 as the mechanism for distributing a DNS domain search list to clients.

What this changes operationally

Before this setup, VLAN segmentation often means mentally carrying both a hostname and an address map.

Afterward, the network behaves more like one coherent environment without becoming one flat broadcast domain.

You can keep:

Management
Default
IoT
Guest
Lab

as separate policy boundaries while still using names like:

lab-server
workstation
printer
gpu-node

from devices that are supposed to reach them.

That is the important part.

The network stays segmented.

The human interface gets simpler.

Final configuration pattern

Per VLAN:

Domain Name = <vlan-role>.example.com

On every client-facing VLAN that should share short-name lookup:

DHCP Option Name: Domain_Search
Type:             Text
Code:             119
Value:            management.example.com,lab.example.com,default.example.com,iot.example.com

Then renew DHCP and verify:

resolvectl status
getent hosts <hostname>

If the FQDN works and the short name works, the system is doing exactly what it should.

The result is a segmented network where RFC1918 addresses no longer have to serve as the human naming convention.

References

• Ubiquiti, “UniFi DHCP Server”: https://help.ui.com/hc/en-us/articles/360012097513-UniFi-DHCP-Server
• Ubiquiti, “UniFi DNS Records and Local Hostnames”: https://help.ui.com/hc/en-us/articles/15179064940439-UniFi-DNS-Records-and-Local-Hostnames
• RFC 3397, “Dynamic Host Configuration Protocol (DHCP) Domain Search Option”: https://www.rfc-editor.org/rfc/rfc3397.html
• Ubiquiti Community thread documenting Option 119 issues in older Network releases and reports of the fix in 10.1.78: https://community.ui.com/questions/b108747a-2241-4111-b555-dff4cbf8148b