Instalação¶
Há três formas comuns de instalar DNSao. Depois disso, siga os passos pós-instalação para apontar clientes para o servidor.
Depois da instalação, siga Depois De Instalar para fazer os dispositivos usarem o DNSao.
Se esta é sua primeira vez usando o DNSao, comece pelo Início Rápido. Esta página é a referência completa de instalação.
Depois de terminar a instalação, configure seus dispositivos, ou idealmente seu roteador/servidor DHCP, para usar DNSao como servidor DNS. Então acesse a porta web definida no application.yml para ter acesso ao dashboard.
Antes De Instalar¶
Confirme que:
- Nada está escutando na porta
53/udpou53/tcpdo host se o DNSao for servir DNS diretamente. - A porta do dashboard, normalmente
8044/tcp, está acessível pelas máquinas que devem usá-la. - Java 17 ou mais recente está instalado se você não estiver usando Docker.
- Qualquer diretório usado por
server.statsDbPathou logs já existe e tem permissão de escrita para o processo do DNSao.
Verifique a porta 53:
sudo ss -tulpn | grep :53
Esse comando deve retornar vazio quando o DNSao for escutar diretamente na porta 53.
Instalação via Docker¶
Docker é o caminho recomendado para a primeira instalação porque não exige Java no host e mantém o runtime isolado.
Confirme que não há nada rodando na porta 53:
sudo ss -tulpn | grep :53
Então use Docker Compose:
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
Inicie o serviço:
docker compose up -d
O container escuta na porta 8053 internamente. O Compose mapeia a porta 53 do host para a porta 8053 do container, então os clientes continuam usando a porta DNS normal 53.
Se /your/local/volume estiver vazio, DNSao irá baixar o application.yml padrão para Docker no volume e usá-lo.
O DNSao armazena métricas e histórico de queries em SQLite por padrão. Se você definir um server.statsDbPath personalizado, como /etc/dnsao/stats.db, confirme que o volume montado é gravável pelo container.
Instalação por script¶
A única dependência de DNSao é a presença de uma jdk versão 17 ou maior.
O DNSao armazena métricas e histórico de queries em um arquivo SQLite por padrão ({tmpdir}/dnsao.db). Se você definir um server.statsDbPath personalizado, confirme que o diretório pai existe e tem permissão de escrita (o DNSao não cria diretórios).
Se o seu servidor for debian based:
apt-get update -y
apt-get install -y openjdk-17-jre-headless
Se for red hat:
dnf install -y java-17-openjdk-headless
outras opções podem ser encontradas no próprio site da openjdk. Após a instalação da jdk, a máquina estará preparada para rodar DNSao.
Antes de instalar, visite o script de instalação para revisar e confirmar o que está sendo executado. Confirme também que não há nenhum processo escutando a porta 53.
sudo ss -tulpn | grep :53
Esse comando deve retornar vazio.
Para executar o script de instalação, rode como root:
curl -sSL https://raw.githubusercontent.com/vitallan/dnsao/refs/heads/main/scripts/install.sh | sudo bash
No próprio servidor, se o comando dig estiver disponível, você pode validar a instalação com:
dig debian.org @127.0.0.1
O resultado deve ser algo parecido com:
; <<>> 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
Os logs da aplicação ficam disponíveis pelo journal do systemd e, quando o log em arquivo está habilitado pela configuração de exemplo, em /var/log/dnsao:
journalctl -u dnsao -e
tail -f /var/log/dnsao/*.log
Você pode então acessar http://IP.DO.SEU.SERVIDOR:8044 e analisar o painel de métricas de DNSao. Usando esse método fará DNSao executar como um serviço systemctl, então comandos systemctl deverão ser usados para a gestão do serviço:
sudo systemctl stop dnsao
sudo systemctl enable dnsao
sudo systemctl start dnsao
Para desinstalar, voce pode usar o script de desinstalação.
Instalação manual¶
Você também pode baixar o último jar disponibilizado e realizar as configurações manualmente. Toda a configuração é feita no único arquivo application.yml. Um exemplo de execução padrão seria o abaixo:
java -Dconfig=/etc/dnsao/application.yml -jar dnsao.jar
Lembrando que, em linux, portas abaixo de 1024 precisam de permissão de root para rodar sem ser por serviço. Considere isso quando for executar manualmente o servidor.
Outro detalhe importante: por ser uma aplicação java, é recomendado limitar os tamanhos de memória usados, para evitar consumo exagerado. Em seu script de instalação padrão, DNSao é executado com as seguintes flags:
- -Xms128m -Xmx256m : inicia a heap com 128 MB e limita o máximo a 256 MB
- -XX:MetaspaceSize=64m -XX:MaxMetaspaceSize=128m : limita o tamanho usado pelo metaspace
- -Xss320k : limita o tamanho máximo da stack para cada thread
O comando final fica então:
java -Dconfig=/etc/dnsao/application.yml -Xms128m -Xmx256m -XX:MetaspaceSize=64m -XX:MaxMetaspaceSize=128m -Xss320k -jar /etc/dnsao/dnsao.jar
Atualização¶
Antes de atualizar, mantenha uma cópia de /etc/dnsao/application.yml, especialmente se você customizou upstreams, mapeamentos locais, grupos, logs ou cache.
Para instalações systemd criadas pelo script de instalação, revise o script de atualização e execute:
curl -sSL https://raw.githubusercontent.com/vitallan/dnsao/refs/heads/main/scripts/upgrade.sh | sudo bash
O script baixa o dnsao.jar da release mais recente, substitui /etc/dnsao/dnsao.jar e reinicia dnsao.service. Ele não substitui o seu /etc/dnsao/application.yml existente.
Para instalações com Docker Compose, atualize a imagem e recrie o container:
docker compose pull
docker compose up -d
Para instalações manuais, pare o DNSao, substitua o JAR pelo artefato da release e inicie novamente:
sudo systemctl stop dnsao
sudo curl -fL https://github.com/vitallan/dnsao/releases/latest/download/dnsao.jar -o /etc/dnsao/dnsao.jar
sudo chown dnsao:dnsao /etc/dnsao/dnsao.jar
sudo systemctl start dnsao
Operação¶
Para instalações systemd, os comandos mais comuns são:
sudo systemctl status dnsao
sudo systemctl restart dnsao
sudo systemctl stop dnsao
Os logs ficam disponíveis no journal do systemd e, quando log em arquivo está configurado, em /var/log/dnsao:
journalctl -u dnsao -e
tail -f /var/log/dnsao/*.log
Métricas e histórico de queries usam SQLite por padrão. Quando server.statsDbPath não está definido, o DNSao armazena o banco no diretório temporário do sistema operacional. Para instalações persistentes, configure um caminho como /etc/dnsao/stats.db e confirme que o diretório pai existe e pode ser escrito pelo processo do DNSao.
O cache rewarm atualiza entradas próximas do fim do TTL. As tentativas são limitadas por cache.maxRewarmPerMinute; o DNSao aplica esse limite como um orçamento por segundo e cada tentativa de rewarm envia uma única query ao upstream.
resolver.multiplier controla quantos upstreams recebem uma query normal de cliente. Valores maiores podem melhorar latência, mas expõem cada query a mais resolvedores upstream. O rewarm não usa o multiplier.
As listas de bloqueio e permissão são baixadas na inicialização. Quando misc.refreshLists é true, o DNSao as atualiza a cada 12 horas.
Validar Instalação¶
Valide a resolução DNS no host do DNSao:
dig example.com @127.0.0.1
Valide de outra máquina na rede:
dig example.com @DNSAO_IP
Abra o dashboard:
http://DNSAO_IP:8044
Se as queries funcionam mas o dashboard não abre, verifique regras de firewall para 8044/tcp. Se o dashboard abre mas DNS não funciona, verifique regras de firewall para 53/udp e 53/tcp.
Depois de instalar¶
Depois de configurar e iniciar o servidor com algum dos métodos acima, você precisará configurar seu roteador para servir para seus clientes DHCP para usarem DNSao como servidor de DNS, o que fará os demais dispositivos da sua rede o usarem automaticamente.
Tal configuração depende de que tipo de roteador é usado.
Outra forma de usar DNSao como servidor de DNS é configurar em cada dispositivo individualmente. Pode não ser o ideal para ambientes com muitos dispositivos, mas pode ser feito, e é especialmente útil para testar a instalação antes de apontar todos juntos.