Scripts to list, add, update, and remove host records in the Ubiquiti UniFI Dream Machine DNS forwarder.
This was a brief attempt at providing local network DNS resolution. But because it's clear that the hostRecords
are overwritten by Ubiquiti-owned code in a bunch of scenarios that don't seem to warrant it, it's clear that this approach to gaining a bit of local DNS control isn't sustainable. Please consider running your own local DNS, such as PiHole instead
As of the creation of this repo, UDMs do not have a UI for administering host records. But the DNS forwarder running on the device supports them. If you don't already run your own DNS service and want to be able to resolve hosts by name in your UDM networks, you can add host records. But it's tedious.
The UDMs no longer resolve against the /etc/hosts
file. Instead they use records that must be administered via API. You can edit them via code by GET
'ting the /services
endpoint to get the json response, changing the entries in dnsForwarder
.hostRecords
, and PUT
'ting the the updated json back to the /services
endpoint. This was well documented in this community topic.
These scripts should make the process a little easier.
Once scripts are executed
/mnt/data/udm-host-records
cd /mnt/udm-host-records
chmod u+x *.sh
To see what host records are present, use
list-host-records.sh
To create or update a host record, use
./add-host-record.sh {-f} {-v 4|6} <hostname>.<domain> <ipaddress>
-f FQDN only. Sets registerNonQualified=false on the host record. Defaults to true.
-v 4 or 6. Defaults to 4. Ignored by UDM firmware < 1.9.
./add-host-record.sh coffee-machine.yourlocaldomain.com 192.168.8.43
will allow you to resolve your coffee-machine's IP address using coffee-machine.yourlocaldomain.com
or just simply coffee-machine
.
Just like in an /etc/hosts
file, you can add multiple entries for any given IP.
If you want to change the IP of an existing host entry, run the command again with the new IP address.
To remove a host record, use
./remove-host-record.sh <hostname>.<domain>
PUT /services
API to validate the updated JSON it PUTs back to the API./services
works or the structure of the json content it accepts.To simplify development while I was tweaking the jq
commands, I made a mock ubios-udapi-client script that I run locally when the TEST
env var is set to 1
. It will simply echo the testdata.json
from the same directory as the scripts whenever the scripts GET the /services
endpoint. It will also result in the changed json file being echo'ed to stdout whenever it PUTs the JSON to the '/services' endpoint.
If you want to experiment,
/services
config json by running the command ubios-udapi-client GET /services > testdata.json
on your UDM. Place this testdata.json
in the same directory as the scripts where you are going to edit and test them
TEST=1
before them, e.g.TEST=1 ./list-host-records.sh ...
TEST=1 ./add-host-record.sh ...
TEST=1 ./remove-host-record.sh ...