Installation¶
There are three ways to install DNSao:
After the instalation is complete, you can point your devices (or, ideally your router) to use it as a DNS server. Reach to the web port defined in application.yml to check the metrics dashboard and enjoy the ride.
Installation via script¶
The only dependency of DNSao is the presence of a JDK version 17 or higher.
If your server is Debian-based:
apt-get update -y
apt-get install -y openjdk-17-jre-headless
If red hat based:
dnf install -y java-17-openjdk-headless
Other options can be found on the official OpenJDK website. After installing the JDK, the machine will be ready to run DNSao.
Before installing, visit the installation script to review and confirm what will be executed. Also, confirm that nothing else is listening on port 53 to avoid conflict:
sudo ss -tulpn | grep :53
This should return nothing.
To execute the installation script, simply run the following command:
curl -sSL https://raw.githubusercontent.com/vitallan/dnsao/refs/tags/prod/scripts/install.sh | bash
On the server itself, if the dig command is available, you can validate the installation with:
dig debian.org @127.0.0.1
The result should look like this:
; <<>> DiG 9.20.11-4-Debian <<>> debian.org @127.0.0.1
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 4434
;; flags: qr rd ra ad; QUERY: 1, ANSWER: 4, AUTHORITY: 0, ADDITIONAL: 1
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
;debian.org. IN A
;; ANSWER SECTION:
debian.org. 279 IN A 151.101.2.132
debian.org. 279 IN A 151.101.130.132
debian.org. 279 IN A 151.101.194.132
debian.org. 279 IN A 151.101.66.132
;; Query time: 7 msec
;; SERVER: 192.168.150.150#53(192.168.150.150) (UDP)
;; WHEN: Wed Jan 05 17:38:05 -03 2020
;; MSG SIZE rcvd: 103
Application logs should be available at:
tail -f /var/log/dnsao/dnsao.log
You can now reach http://YOUR.SERVER.IP:8044 and check the metrics dashboard. Using this method will make DNSao run as a systemctl service, so systemctl commands should work:
sudo systemctl stop dnsao
sudo systemctl enable dnsao
sudo systemctl start dnsao
To uninstall, you can use the uninstall script.
Installation via Docker¶
You can use docker to run DNSao as well. Make sure that the host machine is not running anything on port 53:
sudo ss -tulpn | grep :53
This should return nothing. Then you can use docker compose:
version: "3.8"
services:
dnsao:
image: ghcr.io/vitallan/dnsao:latest
container_name: dnsao
restart: unless-stopped
ports:
- "53:8053/tcp"
- "53:8053/udp"
- "8044:8044"
volumes:
- /your/local/volume:/etc/dnsao
If /your/local/volume is empty, DNSao will download the default docker application.yml and logback.xml files to the volume and use then.
Manual installation¶
You can also download the latest jar and perform a manual configuration. Remember that DNSao requires both an application configuration file and a log configuration file. A standard execution example would be as follows:
java -Dconfig=/etc/dnsao/application.yml -Dlogback.configurationFile=/etc/dnsao/logback.xml -jar dnsao.jar
Keep in mind that, on Linux, ports below 1024 require root privileges to run without being managed by a service. Consider this when running the server manually.
Another important detail: since it’s a Java application, it’s recommended to limit the memory sizes used to avoid excessive consumption. In its default installation script, DNSao runs with the following flags:
- -Xms128m -Xmx128m: limits the heap size to 128 MB
- -XX:MetaspaceSize=64m -XX:MaxMetaspaceSize=128m: limits the metaspace size
- -Xss512k: limits the maximum stack size per thread
The final command is then:
java -Dconfig=/etc/dnsao/application.yml -Dlogback.configurationFile=/etc/dnsao/logback.xml -Xms128m -Xmx128m -XX:MetaspaceSize=64m -XX:MaxMetaspaceSize=128m -Xss512k -jar /etc/dnsao/dnsao.jar
Post install¶
After setting up the server with one of the above installation methods, you will need to configure your router to serve to it's DHCP clients to use DNSao as their DNS server, which will make the devices in your network use it.
Such configuration depends on the which router is used.
Another way is to set each individual device to use DNSao as it's DNS server, which might not be ideal for multiple devices, but can be done, and it is also useful to test the installation before going full on.