What it is

A dnsmasq being populated by aliases / name overrides made in a UniFi controller.

But why?

To make up for the fact that UniFi USG doesn't have hostname alias/override for clients.

How it works

It polls a UniFi controller and writes client names and IP addresses to a file being picked up by dnsmasq.

Configuration

unifi-dns

Example docker-compose.yml:

version: "3.6"
services:
  unifi-dns:
    image: unifi-dns
    build: .
    container_name: unifi-dns
    restart: always
    cap_add:
      - NET_ADMIN
    ports:
      - 53:53/tcp
      - 53:53/udp
    dns:
      # Some upstream DNS servers for this one
      - 192.168.0.1
      - 8.8.8.8
    #volumes:
    #  # Hosts-files live here
    #  - ./dnsmasq.hosts:/etc/dnsmasq.hosts
    #  # Additional config-files live here
    #  - ./dnsmasq.d:/etc/dnsmasq.d
    environment:
      # Commented out = default values
      # UNIFI_BASEURL: https://unifi:8443
      UNIFI_USERNAME: "ubnt"
      UNIFI_PASSWORD: "ubnt"
      # UNIFI_POLL_INTERVAL: 60
      # DNSMASQ_OPTS: ""
      # Tip: use this to get rid of https-warnings in the logs
      # PYTHONWARNINGS: "ignore:Unverified HTTPS request"
      # LOG_LEVEL: INFO
      # FIXED_ONLY: "False"
      # SLUG_NAMES: "False"

• Set the relevant values for these environment variables:

Name	Description	Default value
UNIFI_BASEURL	URL to UniFi controller	https://unifi:8443
UNIFI_USERNAME	Username to UniFi controller	-
UNIFI_PASSWORD	Password to UniFi controller	-
UNIFI_POLL_INTERVAL	Seconds between API calls to UniFi Controller	60
UNIFI_SITE	UniFi "site" name	default
FIXED_ONLY	Flag for only handling clients with reserved IP	False
SLUG_NAMES	Generate DNS-friendly names for incompatible ones	False
LOG_LEVEL	Set logging level (e.g DEBUG, INFO etc)	INFO

If FIXED_ONLY is True only clients with fixed IP-addresses are included - otherwise all active clients are included.

If SLUG_NAMES is True clients with DNS-incompatible names are slugged into compatible ones - you'll have to check the unifi.hosts file generated to see the final hostnames.

• docker-compose up
• UniFi client names and IPs will be written to /etc/dnsmasq.d/unifi.hosts.
• dnsmasq will look in /etc/dnsmasq.d and read *.conf files as additional config files and *.hosts files as additional host files, so feel free to put any additional stuff there.

UniFi USG

• Go to Settings -> Networks -> LAN
• Set "DHCP Name Server" to manual and enter the IP of the machine running unifi-dns (and some fallback servers)