mantim/omada-dns repository overview

⁠ℹ️ About

omada-dns is a standalone local DNS server that connects to your TP-Link Omada Controller via the Omada OpenAPI. It periodically queries the contoller in order to obtain hostnames of the active network devices and automatically creates its own local DNS entries. The server also support reverse DNS queries for hostname resolution.

When owning the Omada Controller/ecosystem, the app can be used as a local DNS server/proxy in cases where you don't own an Omada Router/Gateway and thus don't have access to the built-in Omada local DNS functionality. Also, it is very useful as a reverse DNS server in cases where your DHCP server is separate from your local DNS server (for example Pi-hole providing DNS and Omada providing DCHP), and you want to resolve the hostnames on your DNS server using the conditional forwarding method.

⁠🚀 Key Features

• Automatic Forward DNS: Resolves hostname.domain to the client's current IP.
• Instant Reverse DNS (PTR): Resolves IPs back to Omada client names.
• API-Driven: Acts as a bridge between the Omada Controller and your clients—no manual static entry management required.
• High Compatibility: Uses NET_ADMIN capabilities for low-level network handling.

⁠📖 Instructions for use

Before setting up the omada-dns container:

In you Omada Controller, ensure that you have OpenAPI enabled and that you have created an APP-ID and APP-SECRET. You also need to obtain the CONTROLLER-ID, SITE-ID and the URL of your Omada set-up. Use the mentioned values for the relevant environment variables when creating the docker container.

⁠Environment Variables

⁠Deployment

NOTE: In the examples bellow, the external port 53 is mapped to internal port 53, which is the standard DNS port. Ensure that the port 53 on your host machine is not taken by another service.

Run the following command to pull and start the container:

docker run -d \
  --name omada-dns \
  --restart unless-stopped \
  --cap-add=NET_ADMIN \
  -p 53:53/udp -p 53:53/tcp \
  -e BASE_URL="https://your-controller-url" \
  -e OMADAC_ID="your_controller_id" \
  -e SITE_ID="your_site_id" \
  -e APP_ID="your_app_id" \
  -e APP_SECRET="your_app_secret" \
  mantim/omada-dns:latest

services:
  omada_dns:
    image: mantim/omada-dns:latest
    container_name: omada-dns
    environment:
      BASE_URL: "https://your-controller-url"
      OMADAC_ID: "your_controller_id"
      SITE_ID: "your_site_id"
      APP_ID: "your_app_id"
      APP_SECRET: "your_app_secret"
    cap_add:
      - NET_ADMIN
    ports:
      - 53:53/udp
      - 53:53/tcp
    restart: unless-stopped