Otimizar DNS AdGuard Home para navegação no Alpine 3.22

Otimizar DNS AdGuard Home para navegação no Alpine 3.22 é colocar o AdGuard Home como resolver local com cache em memória e upstreams DoH/DoT, para que o Alpine resolva nomes sem ida desnecessária à internet a cada clique. O ganho vem do cache e de upstreams estáveis — não de “acelerar” o conteúdo das páginas. Para aplicar no Alpine Linux 3.22, siga estes passos:

1. Instale certificados, curl, libcap e o binário oficial em /opt/AdGuardHome.
2. Registre o serviço OpenRC e inicie o daemon na porta 53 do loopback.
3. Aponte /etc/resolv.conf para 127.0.0.1 e impeça o DHCP de sobrescrever o arquivo.
4. Configure cache, prefetch e upstreams em paralelo (DoH/DoT) no painel.
5. Restrinja o painel web, evite blocklists excessivas e valide com dig.

Pré-requisitos

• Alpine Linux 3.22 (ou mais nova da linha 3.22) com acesso root via SSH.
• Arquitetura amd64 ou arm64; repositórios main e community habilitados em /etc/apk/repositories.
• OpenRC como init (padrão do Alpine); não use unidades systemd neste sistema.
• Porta UDP/TCP 53 livre no host, ou permissão para parar o processo que a ocupa.
• Painel administrativo acessível só via loopback ou túnel SSH; não exponha DNS recursivo na internet pública.
• Pacotes de apoio: ca-certificates, curl, libcap, iproute2 e bind-tools (para ss e dig).

O AdGuard Home não substitui um servidor autoritativo de zona. Se o objetivo for publicar registros do domínio, use a zona no registrador ou um autoritativo dedicado; o papel aqui é resolver nomes com cache e filtragem para a navegação do próprio Alpine e, se quiser, da LAN. Quem precisa só de DNS de domínio na hospedagem pode seguir o artigo Como Configurar DNS Personalizado para Seu Domínio na AviraHost em paralelo, sem misturar os dois papéis no mesmo processo.

Instalar o binário e o serviço OpenRC

O serviço OpenRC é o caminho correto no Alpine Linux 3.22: o instalador oficial do AdGuard Home detecta OpenRC e grava o script em /etc/init.d. Não há pacote apk obrigatório para o daemon; o binário Go da release linux_amd64 (ou linux_arm64) costuma ser estático e sobe direto. Se o kernel recusar a execução com “No such file or directory”, instale gcompat depois — isso indica loader glibc, não falha de DNS.

Atualize o índice e instale o mínimo para HTTPS, bind na porta privilegiada e diagnóstico:

apk update
apk add --no-cache ca-certificates curl libcap iproute2 bind-tools
update-ca-certificates

Baixe a release estável atual para amd64 (troque o sufixo para linux_arm64 em placas ARM):

cd /tmp
curl -sSL -o AdGuardHome.tar.gz \
  https://github.com/AdguardTeam/AdGuardHome/releases/latest/download/AdGuardHome_linux_amd64.tar.gz
tar -tzf AdGuardHome.tar.gz | head
mkdir -p /opt/AdGuardHome
tar -xzf AdGuardHome.tar.gz -C /tmp
cp -a /tmp/AdGuardHome/. /opt/AdGuardHome/
/opt/AdGuardHome/AdGuardHome --version

Ao rodar --version, a primeira linha traz o nome do binário e a versão compilada. Confirme que o arquivo é executável e que /opt/AdGuardHome permanece o diretório de trabalho (-w). Em seguida instale o serviço e habilite no runlevel default:

/opt/AdGuardHome/AdGuardHome -s install -w /opt/AdGuardHome
rc-update add AdGuardHome default
rc-service AdGuardHome start
rc-service AdGuardHome status

O status OpenRC deve indicar started. Na primeira subida o assistente escuta em TCP 3000. Não deixe essa porta aberta para 0.0.0.0 em host exposto: faça o assistente via túnel e, no final, fixe o HTTP em 127.0.0.1.

ssh -L 3000:127.0.0.1:3000 [email protected]

No navegador local abra http://127.0.0.1:3000, defina usuário e senha fortes, escolha interface de escuta DNS em 127.0.0.1 (e o IPv4 da LAN só se houver clientes na rede) e conclua o assistente. Só depois disso o processo passa a servir a porta 53. Confira com:

ss -ulnp | grep ':53'

Saída típica (PID genérico):

UNCONN 0 0 127.0.0.1:53 0.0.0.0:* users:(("AdGuardHome",pid=1234,fd=8))

Se o Alpine for um servidor VPS com vários serviços, trate o AdGuard Home como resolver da máquina, não como DNS público. Amplificação e abuso começam quando 0.0.0.0:53 fica visível na internet. Em Debian o fluxo de pacotes e systemd é outro; o texto Solucionar DNS com AdGuard Home no Debian 12 e bloquear anúncios cobre essa família, não o OpenRC do Alpine 3.22.

Apontar o nameserver local sem o DHCP apagar

O nameserver 127.0.0.1 é o que faz o sistema operacional usar o cache do AdGuard Home em vez do resolver do provedor. No Alpine Linux 3.22 o arquivo /etc/resolv.conf é simples, mas o udhcpc (DHCP do busybox) reescreve esse arquivo a cada lease. Sem travar isso, o reboot devolve o DNS da WAN e a navegação ignora o daemon local.

Grave o resolver local:

printf 'nameserver 127.0.0.1\noptions ndots:1 timeout:2 attempts:2\n' > /etc/resolv.conf
cat /etc/resolv.conf

Saída esperada:

nameserver 127.0.0.1
options ndots:1 timeout:2 attempts:2

Impedir o DHCP de devolver o arquivo depende de como a interface sobe. Com udhcpc, crie /etc/udhcpc/udhcpc.conf para não tocar no resolv.conf:

mkdir -p /etc/udhcpc
printf 'RESOLV_CONF=no\n' > /etc/udhcpc/udhcpc.conf

Se a interface for estática em /etc/network/interfaces, não declare DNS remoto. Exemplo com IPs de documentação:

auto eth0
iface eth0 inet static
    address 203.0.113.10
    netmask 255.255.255.0
    gateway 203.0.113.1

Reinicie a rede só depois de o AdGuard Home já estar escutando em 53. Caso contrário o próprio apk e o curl perdem resolução no intervalo. Teste o resolver local sem sair do host:

dig @127.0.0.1 seudominio.com.br A +norecurse
dig @127.0.0.1 seudominio.com.br A

A segunda consulta deve vir com SERVER 127.0.0.1#53 e seção ANSWER preenchida quando o nome existir. Não use o domínio da AviraHost nesses testes: o valor de ANSWER muda no seu ambiente e não serve de gabarito. IPv6 é opcional; se a LAN tiver clientes em IPv6, inclua ::1 em bind_hosts para o filtro e o cache não serem ignorados pelo sistema operacional do telefone ou do desktop.

TTL alto no cache local não é o mesmo que otimizar a propagação de DNS: por que demora e como acelerar. Propagação fala de registros autoritativos na internet; aqui o TTL só controla quanto tempo o Alpine reaproveita a resposta já obtida. Deixe cache_ttl_min e cache_ttl_max em 0 para respeitar o TTL original, salvo se você tiver um motivo explícito para forçar piso ou teto.

Cache, DoH e modo paralelo dos upstreams

DNS over HTTPS (DoH) e DNS over TLS (DoT) protegem a consulta até o upstream e, com bootstrap_dns em IP puro, evitam o ovo-e-galinha de resolver o próprio hostname do DoH. Para navegação no Alpine, o que reduz espera é responder do cache e disparar vários upstreams em paralelo — não empilhar dezenas de listas de anúncio.

Edite /opt/AdGuardHome/AdGuardHome.yaml com o serviço parado, ou altere as mesmas opções em Configurações → DNS no painel. Trecho mínimo alinhado ao esquema atual do arquivo (ajuste bind_hosts se a LAN precisar do resolver):

dns:
  bind_hosts:
    - 127.0.0.1
  port: 53
  bootstrap_dns:
    - 1.1.1.1
    - 8.8.8.8
  upstream_dns:
    - https://dns.cloudflare.com/dns-query
    - https://dns.google/dns-query
  upstream_mode: parallel
  cache_size: 4194304
  cache_ttl_min: 0
  cache_ttl_max: 0
  cache_optimistic: true
  ratelimit: 0

cache_size está em bytes de estrutura de cache, não em “número de sites”. cache_optimistic devolve uma resposta ainda válida no cache enquanto busca atualização; isso corta a espera em nomes já vistos, sem alterar HTML nem imagens. upstream_mode: parallel consulta os upstreams ao mesmo tempo e usa a primeira resposta válida. ratelimit: 0 evita o daemon recusar clientes locais em rajada (útil em navegador com muitas abas); em resolver aberto para a internet isso seria irresponsável — por isso o bind permanece em 127.0.0.1.

Atenção: depois de editar o YAML, recarregue de forma limpa. Não mate o processo com kill -9 em produção: o OpenRC deve parar e subir de novo para reler o arquivo.

rc-service AdGuardHome restart
rc-service AdGuardHome status
dig @127.0.0.1 example.com A
dig @127.0.0.1 example.com A

A segunda query ao mesmo nome deve ser servida pelo cache (o painel em “Consulta DNS” mostra cache hit). Prefetch, quando habilitado na interface (DNS → prefetch), antecipa nomes perto de expirar; use com cache já ligado. Upstreams instáveis geram timeout em cascata: se um DoH falhar, o bootstrap_dns em 1.1.1.1/8.8.8.8 ainda precisa alcançar a rede. Firewall de saída deve permitir 443/tcp (DoH) e, se usar DoT, 853/tcp.

Não exponha 53/udp na WAN. Se algum cliente da LAN precisar do cache, faça bind no IPv4 privado (por exemplo 198.51.100.10) e filtre origem com nftables, em vez de 0.0.0.0 sem restrição. Quem compara com Bind9 recursivo puro encontra outro perfil de ajuste no texto Entenda o Bind9: 7 ajustes que evitam falhas de DNS; no Alpine 3.22 deste artigo o AdGuard Home já entrega cache, paralelismo e filtragem no mesmo processo.

Filtros leves e painel restrito

Blocklists grandes aumentam RAM e o tempo de matching por consulta. No Alpine Linux 3.22, especialmente em VPS com pouca memória, comece com as listas padrão do assistente. Ative o cache antes de adicionar listas extras. Meça com dig @127.0.0.1 depois de cada lista nova: se o host começar a paginar ou o load subir sem tráfego web, remova a lista — o gargalo é o matching, não a “velocidade da internet”.

No painel, em Filtros, mantenha poucas fontes bem cuidadas. Desative listas duplicadas. Regras de usuário (desbloquear um domínio de CDN que quebrou o site) vão em filtros personalizados, não em mais uma lista inteira. Isso preserva a navegação: o DNS continua rápido e só deixa de resolver nomes que você realmente quer bloquear.

O HTTP de administração não precisa estar na LAN. Em Configurações → Configurações gerais, limite o endereço de escuta a 127.0.0.1 e uma porta alta. Acesso remoto fica no túnel SSH já usado no assistente. Não use chmod 777 em /opt/AdGuardHome; o diretório deve pertencer ao usuário com que o serviço roda após o drop de privilégio, com permissão de escrita só no working dir (estatísticas, filtro atualizado e o YAML).

Clientes Windows, Android e o próprio Alpine devem apontar DNS para o IPv4 em que o AdGuard escuta. Se o telefone “pula” para DNS64/DoT do operador, o cache local não entra no caminho — nesse caso o ganho fica só no servidor. Relógio certo (chrony ou openntpd via apk) evita TLS de DoH falhar por data errada; isso parece “DNS lento” e na verdade é handshake recusado.

Problemas comuns e como resolver

Sintoma: AdGuard Home não sobe e a porta 53 já está em uso

Causa: outro processo (dnsmasq, unbound, stub ou container) já fez bind em 0.0.0.0:53 ou 127.0.0.1:53. O OpenRC marca o serviço como crashed e o resolv.conf aponta para um daemon morto.
Solução: rode ss -ulnp | grep ':53', identifique o binário e pare o serviço correspondente com rc-service. Só então rc-service AdGuardHome start. Se precisar manter os dois, não compartilhe a mesma porta: o FAQ descreve o redirecionamento com nft, mas o caminho simples no Alpine 3.22 é a 53 no loopback exclusiva do AdGuard Home.

Sintoma: depois do reboot o DNS volta a ser o do provedor

Causa: udhcpc reescreveu /etc/resolv.conf no lease; RESOLV_CONF não estava em no, ou a interface foi recriada sem o arquivo de config.
Solução: recrie /etc/udhcpc/udhcpc.conf com RESOLV_CONF=no, grave nameserver 127.0.0.1 de novo e confirme com cat /etc/resolv.conf após rc-service networking restart. Garanta que AdGuard Home está em rc-update default para subir antes da carga de trabalho web.

Sintoma: o binário falha com “No such file or directory”

Causa: release ligada a glibc em userland musl, sem loader compatível.
Solução: apk add --no-cache gcompat (repositório community) e execute de novo /opt/AdGuardHome/AdGuardHome --version. Se ainda falhar, baixe a variante linux_arm64 ou linux_amd64 correta para a CPU (uname -m) em vez de emular o arquivo errado.

Sintoma: sites abrem, mas o painel mostra muitas falhas de upstream

Causa: DoH bloqueado (443 de saída), relógio errado ou bootstrap_dns inacessível.
Solução: teste curl -I https://dns.cloudflare.com/dns-query a partir do Alpine, sincronize a hora e mantenha bootstrap em IPs literais. Troque upstream_mode para parallel somente com pelo menos dois upstreams saudáveis.

Perguntas frequentes

O AdGuard Home substitui o resolv.conf no Alpine Linux 3.22?

Sim, o AdGuard Home passa a escutar na porta 53 e o sistema deve apontar nameserver 127.0.0.1. No Alpine, ajuste /etc/resolv.conf ou o gerenciador de rede para não sobrescrever o resolver local após o reboot.

Qual porta usar se a 53 já estiver ocupada no Alpine?

Se outro serviço já usa a 53, pare o stub resolver ou o dnsmasq local antes de iniciar o AdGuard Home. Alternativamente, faça o AdGuard escutar em outra porta e redirecione com nft, mas a porta 53 no loopback é o caminho mais simples para clientes da LAN.

Como o cache do AdGuard Home acelera a navegação?

Consultas repetidas são respondidas a partir do cache em memória, sem ir ao upstream. TTL razoável, prefetch e upstreams rápidos (DoH/DoT) reduzem o tempo até o primeiro byte em sites já visitados, sem alterar o conteúdo das páginas.

Preciso de IPv6 para o AdGuard Home no Alpine 3.22?

Não é obrigatório. Você pode escutar só em IPv4. Se a LAN usa IPv6, habilite a escuta em ::1 e no endereço da interface para que smartphones e desktops não ignorem o filtro e o cache.

Filtros de anúncio deixam a navegação mais lenta?

Listas enormes aumentam o uso de RAM e o tempo de matching. Comece com poucas listas bem mantidas, ative o cache e meça com dig. Se a CPU do Alpine for limitada, priorize cache e upstreams estáveis em vez de dezenas de blocklists.

Conclusão

• Deixe o AdGuard Home como único listener em 127.0.0.1:53 no Alpine Linux 3.22 e trave o resolv.conf contra o udhcpc.
• Use cache_optimistic, cache_size adequado e upstreams DoH em parallel; meça com dig no loopback, não com “feeling” do browser.
• Restrinja o painel a localhost, não publique DNS recursivo na WAN e mantenha poucas blocklists para não gastar RAM no matching.

Leia também

• Guia Alpine Linux 3.22: instalar Node-RED para automação DevOps
• Como configurar webhook Stripe com PHP 8.4 no Alpine Linux 3.22
• Entenda Docker Compose no Alpine Linux 3.22: instalação

Precisa de ajuda com DNS AdGuard Home?

Um VPS com Alpine Linux 3.22 estável, IPv4 dedicado e porta 53 livre no loopback simplifica cache local, DoH de saída e túnel do painel sem brigar com resolver de provedor.

Contratar Servidor VPS