mirror of https://github.com/vitallan/dnsao.git synced 2026-04-26 12:25:55 +03:00

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

Find a file

github-actions[bot] e5ddfa7fa7 chore(release): bump revision to 0.1.31-SNAPSHOT [skip ci]		2026-02-28 15:05:20 +00:00
.github/workflows	adding pat on release	2025-11-08 15:06:01 -03:00
config-samples	- added client group mechanism	2025-11-15 10:15:32 -03:00
docker	fixing docker entrypoint file	2025-11-10 06:55:36 -03:00
docs	fixing docs identation on http listeners config page	2025-11-23 19:12:20 -03:00
scripts	pointing script files to main	2025-11-08 14:12:40 -03:00
src	- added paging to the queries endpoint, so that a single request does	2026-02-28 12:04:26 -03:00
.gitignore	- setup udp server	2025-10-11 11:21:37 -03:00
LICENSE	- setup udp server	2025-10-11 11:21:37 -03:00
pom.xml	chore(release): bump revision to 0.1.31-SNAPSHOT [skip ci]	2026-02-28 15:05:20 +00:00
README.md	- added paging to the queries endpoint, so that a single request does	2026-02-28 12:04:26 -03:00
README.pt.md	- added paging to the queries endpoint, so that a single request does	2026-02-28 12:04:26 -03:00

README.md

DNSao

DNSao is a multi-upstream DNS forwarder written in Java, featuring caching, privacy-oriented DNS querying support (DoT and DoH), and a built-in dashboard for real-time metrics.

DNSao is currently under active development

Overview

DNSao is designed to serve as a lightweight, configurable, and privacy-oriented DNS forwarder.

It handles UDP, TCP and HTTP queries, and supports modern encrypted upstreams (DoT/DoH), while maintaining a robust caching system and a simple web interface for live metrics.

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 logging (optional)
Real-time metrics dashboard built with Bulma + Chart.js
Pluggable blocklists and local mappings/overrides
Configuration via a single application.yml
Systemd-ready installation and lightweight footprint

More info can be found at the documentation.

Building from Source

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

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:

java -jar target/dnsao-<version>.jar \
  -Dconfig=/etc/dnsao/application.yml \
  -Dlogback.configurationFile=/etc/dnsao/logback.xml

or, using maven itself:

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.

Dashboard

DNSao provides a built-in metrics dashboard that displays:

Query volume
Searchable queries resolved
Cache hit/miss rate
Average response time
Upstream distribution

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.

Credits

DNSao makes use of open-source libraries, including:

dnsjava — DNS protocol implementation
Javalin — lightweight web server
SnakeYAML — YAML configuration
Minimal-json - JSON manipulation
Logback — logging framework