Custom DNS entries in Unifi UDM

Posted on by

Do you own a Unifi UDM and feel that the builtin DNS lacks some features?

The Ubiquiti Dream Machine (UDM) utilizes Dnsmasq, a popular lightweight DHCP and caching DNS server. Despite its compact size, Dnsmasq is surprisingly versatile and can handle many advanced functions.

This guide will demonstrate a simple hack to enable wildcard support for your internal web server using Dnsmasq. However, the possibilities for customization extend far beyond this example.

Prerequisites:

  • Familiarity with SSH access to your UDM
  • Basic understanding of Linux commands and file editing in the terminal

Creating a Persistent Bash Script

We’ll create a small Bash script within the UDM and store it in the /root directory. This location is chosen because files stored here typically persist through UDM updates, avoiding the need for frequent manual intervention. While alternative solutions exist, they might be more complex than necessary for our purposes.

UniFi releases updates a few times a year. With this frequency, any manual steps beyond a simple SSH connection and script execution could become cumbersome. This script-based approach simplifies the process.

Dnsmasq Configuration in UDM

Don’t Edit Existing Files!

The UDM stores running Dnsmasq configurations in /run/dnsmasq.conf.d. These files are automatically updated when your UDM setup changes (e.g., adding a new device), wiping away any manual modifications.

Adding Custom Configurations:

However, you can add new files to this directory for custom settings. By naming them appropriately, Dnsmasq will recognize and utilize them.

Example: Wildcard Support for Internal Web Server

This example demonstrates adding wildcard support for an internal web server named “web.home” (previously configured through UDM’s standard process). The goal is to enable domain prefixes like “www” before “web.home”.

We’ll achieve this by adding a CNAME configuration to Dnsmasq. Additionally, we need to inform Dnsmasq that it acts as the authoritative server for the “.home” top-level domain and the “web.home” zone. The following example demonstrates these configurations with explanations for each line.

#!/bin/bash

cat <<EOT >/run/dnsmasq.conf.d/my_dns_fix.conf
cname=*.web.home,web.home
auth-zone=web.home
auth-server=home,*

EOT

pkill -9 dnsmasq

So, in /root folder of my UDM a create a file (example: my_dns_fix) and add content as above.
Make file executable (chmod u+x my_dns_fix) and execute it.
So, now Dnsmasq will resolve web.home with any prefix (example www.web.home) to same address as web.home, and it would actually resolve any prefix to web.home as it now configured with wildcard support.

TIP!
If something don’t work as expected…
Remove conf file: rm /run/dnsmasq.conf.d/my_dns_fix.conf
and execute pkill -9 dnsmasq to reload configuration without your changes.
(You can also do as I have done… create script with what do what for you. It can be a bit tricky to know what you are doing if UDM write a error message every second or so)

Summary

So far my custom script have survived all unifi updates for almost two years. And only after some updates I have had to ssh UDM and re-executed script.
I have extended it work with an UDM in second setup with tunnel between, so dns lookup between sites also works… that I will describe in a later post.

Top-level domain
.home is one of the top-level domain that is define in RFC6762 that you can use for your internal network.
Other reserved top-level domain that you can use for internal networking are: intranet, internal, private, corp and lan
https://www.rfc-editor.org/rfc/rfc6762#appendix-G