KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

dnsao

★ 25 Open GitHub ↗

A lightweight, fast, configurable, and privacy-oriented DNS forwarder/server written in Java

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Deploy with Docker](https://img.shields.io/badge/Deploy%20with-Docker-2496ED?logo=docker&logoColor=white)](https://vitallan.github.io/dnsao/installation/#installation-via-docker)
[![Deploy with systemd](https://img.shields.io/badge/Deploy%20with-systemd-000000?logo=systemd&logoColor=white)](https://vitallan.github.io/dnsao/installation/#installation-via-script)

[![Tests](https://github.com/vitallan/dnsao/actions/workflows/ci.yml/badge.svg)](https://github.com/vitallan/dnsao/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/vitallan/dnsao)](https://github.com/vitallan/dnsao/releases)

<h1 align="center">DNSao</h1>

**DNSao** is a multi-upstream DNS forwarder written in Java. It runs as the DNS server for your network, forwards queries to upstream resolvers, caches responses, optionally blocks domains, supports encrypted upstreams (DoT/DoH), and exposes a built-in dashboard for live metrics.

---

## What It Is

DNSao is designed for technical users who want a lightweight DNS resolver for a LAN, homelab, or small server.

Typical request flow:

```text
client device -> DNSao -> local mappings / blocklists / cache -> upstream DNS resolvers
```

Use it when you want:

- A local DNS forwarder/cache for your network
- Encrypted upstream queries using DNS-over-TLS or DNS-over-HTTPS
- Blocklists and allowlists similar to a DNS sinkhole
- Local DNS overrides for homelab services
- A dashboard showing query volume, cache behavior, upstream usage, and JVM health

## Who It's For

DNSao is aimed at technical users who want more control over DNS on a LAN or homelab without assembling several separate services.

- Users who want network-wide ad, tracker, or malware-domain blocking
- Users who want DNS queries forwarded upstream over private protocols such as DoT or DoH
- Users who want faster DNS resolution through local caching, rewarm, and upstream racing
- Users who want robust LAN DNS rules with local mappings, blocklists, allowlists, and client groups
- Users who want simple high availability by running more than one DNSao instance with the same config file
- Homelab and self-hosting users who want names for internal services
- Users who want DNS observability through a built-in dashboard

### Current Features

- Answers UDP, TCP and HTTP for local DNS queries
- Multiple upstream DNS resolvers (UDP/DoT/DoH)
- TTL-aware caching system with asynchronous rewarm
- DNSSEC aware with configurable policies
- Query history and metrics 
- Real-time metrics dashboard with query log, upstream stats, and VM stats
- Pluggable blocklists and local mappings/overrides
- Configuration via a single `application.yml`
- Systemd-ready installation and lightweight footprint

---

## Quick Start

The fastest way to try DNSao is Docker Compose:

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

Then validate DNS resolution:

```bash
dig example.com @127.0.0.1
```

Open the dashboard at `http://localhost:8044`.

More info can be found in the [documentation](https://vitallan.github.io/dnsao/) and the [Quick Start](https://vitallan.github.io/dnsao/quick-start/).

## Building from Source

You can build DNSao using **Maven** and **Java 17 or later**.

```bash
git clone https://github.com/vitallan/dnsao.git
cd dnsao
mvn clean package -DskipTests
````

The resulting JAR will be located in:

```
target/dnsao-<version>.jar
```

To run it manually:

```bash
java -Dconfig=/etc/dnsao/application.yml \
  -jar target/dnsao-<version>.jar
```

or, using maven itself:

```bash
mvn exec:java
```
---

The main branch should be stable.

New releases and docker images are generated based on commit/push on main.

## Configuration

All app configuration options are defined in a single `application.yml`.

More detailed info can be found at the [documentation](https://vitallan.github.io/dnsao/configuration/).

---

## Dashboard

DNSao provides a built-in **metrics dashboard** that displays:

* Query volume
* Searchable query history
* Cache hit/miss rate
* Average response time
* Upstream distribution and latency
* JVM memory, GC, and thread stats

Access it via the admin port configured in your `application.yml` (e.g. `http://localhost:8044`).

---

## Contributing

Contributions are welcome, but mostly for bug reporting, suggest improvements and general feedback. The server is fairly stable now, but some code is still being created, and a lot of inner interfaces might change without notice.

Issues are the recommended form of contact [GitHub](https://github.com/vitallan/dnsao/issues).

---

## Credits

DNSao makes use of open-source libraries, including:

* [dnsjava](https://github.com/dnsjava/dnsjava) — DNS protocol implementation
* [Javalin](https://javalin.io) — lightweight web server
* [SnakeYAML](https://bitbucket.org/asomov/snakeyaml) — YAML configuration
* [Minimal-json](https://github.com/ralfstx/minimal-json) - JSON manipulation
* [sqlite-jdbc](https://github.com/xerial/sqlite-jdbc) — embedded SQLite JDBC driver

---

## Links

* [Official Documentation](https://vitallan.github.io/dnsao/)
* [My personal site](https://allanvital.com)

---

dnsao

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README