Skip to content

Quick Start

This page gets DNSao running and verifies that clients can use it as a DNS server. Use Docker if you want the shortest path. Use the systemd script or manual JAR if you prefer a host-level service.

Before You Start

You need:

  • A Linux host, VM, container host, or small server that will stay online
  • Port 53/udp and 53/tcp available on the host if DNSao will serve your network directly
  • Port 8044/tcp available if you want to access the dashboard from another machine
  • Java 17 or newer only when not using Docker

Check whether something is already using port 53:

sudo ss -tulpn | grep :53

If this returns a process, fix that conflict before binding DNSao to port 53.

Run With Docker Compose

Create a directory for DNSao config and data:

sudo mkdir -p /opt/dnsao

Create docker-compose.yml:

services:
  dnsao:
    image: ghcr.io/vitallan/dnsao:latest
    container_name: dnsao
    restart: unless-stopped
    ports:
      - "53:8053/udp"
      - "53:8053/tcp"
      - "8044:8044"
    volumes:
      - /opt/dnsao:/etc/dnsao

Start it:

docker compose up -d

The Docker image listens on port 8053 inside the container so it can run without binding to privileged port 53 internally. The Compose file maps host port 53 to container port 8053.

If /opt/dnsao is empty, DNSao downloads a default Docker-oriented application.yml there on first start.

Verify DNS Resolution

From the DNSao host:

dig example.com @127.0.0.1

From another machine on the same network, replace DNSAO_IP with the server address:

dig example.com @DNSAO_IP

You should get a normal DNS answer with status: NOERROR.

Open The Dashboard

Open:

http://DNSAO_IP:8044

The dashboard shows query summary, query history, cache behavior, upstream usage, upstream latency, and JVM health.

If you expose the dashboard beyond a trusted LAN, configure server.authPass and put DNSao behind an HTTPS reverse proxy. Dashboard auth is HTTP unless you add TLS at the proxy layer.

Point Clients To DNSao

For a whole network, configure your router or DHCP server to advertise the DNSao server IP as the DNS server.

For testing, configure one device manually to use DNSao as its DNS server. After changing DNS settings, run a query from that device and confirm it appears in the dashboard query log.

What To Configure Next

  • Set server.authPass if the dashboard is reachable by other users.
  • Set server.statsDbPath to a persistent SQLite path if you want query history and metrics to survive restarts.
  • Choose upstreams under resolver.upstreams: UDP for simplicity, DoT/DoH for encrypted upstream queries.
  • Tune resolver.multiplier: 1 sends each query to one upstream; higher values race multiple upstreams for lower latency but expose each query to more resolvers.
  • Add lists.blockLists and lists.allowLists for DNS sinkhole behavior.
  • Add resolver.localMappings for local services and homelab names.

For the full reference, see Configuration.