AdGuard Home, açık çözümleyici olmadan bir sunucuya nasıl kurulur

AdGuard Home, reklamları, izleyicileri ve kötü amaçlı alan adlarını cihazlarınız onlara bağlanmadan önce filtre listeleriyle engelleyen, ağ genelinde çalışan bir DNS sunucusudur. Sorgu logu ve istatistikler içeren bir web paneli, istemci bazlı ayarlar ve şifreli DNS desteği (DNS-over-HTTPS, DNS-over-TLS ve DNS-over-QUIC) sunar. Evde genellikle yerel ağa hizmet eder. Veri merkezindeki bir sunucuda ise telefonunuzu ve dizüstü bilgisayarınızı nerede olurlarsa olsunlar koruyabilir; ancak yalnızca dikkatle kurulursa.

Bu rehber AdGuard Home'u, onu /opt/AdGuardHome içine yerleştirip bir systemd servisi kaydeden resmi kurulum betiğiyle kurar. 53 numaralı portu belgelenmiş çözümle systemd-resolved'dan kurtarır, yönetim arayüzünün internete hiç açılmaması için kurulum sihirbazını SSH tüneli üzerinden çalıştırır, DNS'i ufw ve AdGuard Home'un izin listesiyle WireGuard ağınızla sınırlar ve isteğe bağlı olarak DNS-over-HTTPS'i Caddy üzerinden yayınlarsınız. Yedekleme, güncelleme ve sorun giderme sonda yer alır. Resmi bir Docker imajı (adguard/adguardhome) da vardır, ancak Docker'ın yayınladığı portlar ufw'yi atladığı için burada ana yol olarak daha güvenli olan doğrudan kurulum kullanılır.

Adım 1 — Resmi kurulum betiğini indirin, okuyun ve çalıştırın

AdGuard'ın resmi otomatik kurulumu bir kabuk betiğidir. Betik işletim sisteminizi ve işlemcinizi algılar, sürüm arşivini AdGuard'ın indirme sunucusundan (varsayılan olarak release kanalından) indirir, /opt/AdGuardHome içine açar ve sistem servisini kaydetmek için AdGuardHome -s install çalıştırır. Root gerektiren adımlar için sudo kullanır. Betiği indirin, okuyun ve ardından çalıştırın:

cd ~
curl -fsSL https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh -o install-adguardhome.sh
less install-adguardhome.sh
sh install-adguardhome.sh -v

-v ayrıntılı çıktı verir. Betik ayrıca kanal seçmek için -c, yeniden kurmak için -r ve kaldırmak için -u seçeneklerini kabul eder. Projenin README dosyası aynı betiği curl çıktısını sh -s -- -v komutuna aktaran tek satırlık bir komut olarak gösterir; önce indirmek neyin çalışacağını görmenizi sağlar. Servisin çalıştığını ve kurulumu beklediğini kontrol edin:

sudo /opt/AdGuardHome/AdGuardHome -s status
sudo ss -tlnp | grep AdGuardHome

Durum running olur ve ss kurulum sihirbazını 0.0.0.0:3000 üzerinde gösterir. ufw bu portu internete kapalı tutar; açmayın.

Adım 2 — 53 numaralı portu systemd-resolved'dan kurtarın

Ubuntu'da systemd-resolved, 127.0.0.53:53 üzerinde yerel bir DNS stub dinleyicisi çalıştırır ve bu, AdGuard Home'un 53 numaralı portta dinlemesini engeller. Etkin olup olmadığını kontrol edin:

sudo ss -lunp | grep ':53 '

Çıktıda systemd-resolve görünüyorsa AdGuard SSS sayfasındaki çözümü uygulayın: stub dinleyicisini kapatın, sistemi 127.0.0.1 üzerindeki AdGuard Home'a yönlendirin ve /etc/resolv.conf dosyasını resolved'ın yönettiği dosyayla değiştirin:

sudo mkdir -p /etc/systemd/resolved.conf.d
sudo tee /etc/systemd/resolved.conf.d/adguardhome.conf > /dev/null <<'EOF'
[Resolve]
DNS=127.0.0.1
DNSStubListener=no
EOF
sudo mv /etc/resolv.conf /etc/resolv.conf.backup
sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf
sudo systemctl reload-or-restart systemd-resolved

ss komutunu yeniden çalıştırın; systemd-resolve artık 53 numaralı portta dinlemez. Belgeler DNS=127.0.0.1 ayarının gerekli olduğunu belirtir, çünkü stub dinleyicisi kapandığında stub adresi çalışmaz. Sunucunun kendisi artık kendi sorguları için AdGuard Home'u kullanır; bu yüzden hemen Adım 3 ile devam edin. Kontrol 53 numaralı portta hiçbir şey göstermiyorsa (varsayılan olarak systemd-resolved kullanmayan Debian'da yaygındır) bu adımı atlayın.

Adım 3 — Kurulum sihirbazını SSH tüneli üzerinden çalıştırın

Kendi bilgisayarınızda yerel 3000 numaralı portu SSH üzerinden sihirbaza yönlendirin ve komutu çalışır hâlde bırakın:

ssh -N -L 3000:127.0.0.1:3000 user@203.0.113.10

http://localhost:3000 adresini açın ve sihirbazı izleyin:

1. Admin web interface: dinleme arayüzünü 127.0.0.1 (loopback girdisi), portu 3000 yapın. Panel bundan sonra yalnızca SSH tüneli veya sunucudaki bir proxy üzerinden erişilebilir olur.
2. DNS server: All interfaces seçeneğini ve 53 numaralı portu koruyun. Kimin kullanabileceğine Adım 4'teki güvenlik duvarı ve izin listesi karar verir.
3. Authentication: bir yönetici kullanıcı adı ve parola yöneticinizden alınmış uzun bir parola seçin.
4. Sihirbazı bitirin ve paneli açın. Panel artık 127.0.0.1:3000 üzerinde dinlediği için tünel çalışmaya devam eder.

Ardından Settings, DNS settings, Upstream DNS servers altındaki üst çözümleyicileri gözden geçirin. AdGuard Home izin verilen sorguları onlara iletir; şifreli üst çözümleyiciler (https:// veya tls:// ile başlayan adresler) bu sorguları dışarı çıkarken de gizli tutar. Kaydetmeden önce Test upstreams düğmesini kullanın ve Filters, DNS blocklists altında filtre listelerini etkinleştirin.

Adım 4 — DNS'e yalnızca kendi istemcilerinizden izin verin

Birbirinden bağımsız iki katman çözümleyiciyi gizli tutar. Birincisi ufw: 53 numaralı porta yalnızca WireGuard arayüzünde izin verin ve genel arayüzde asla açmayın:

sudo ufw allow in on wg0 to any port 53
sudo ufw status verbose

İkincisi AdGuard Home'un izin listesi. Settings, DNS settings, Access settings bölümünü açın, Allowed clients altına şu satırları girin ve kaydedin:

127.0.0.1
::1
10.8.0.0/24

Bu listede girdi olduğunda AdGuard Home yalnızca listedeki istemcilere yanıt verir. Sunucunun kendisi artık adları AdGuard Home üzerinden çözümlediği için (Adım 2) iki loopback adresi gereklidir. AdGuard'ın güvenlik rehberi herkese açık kurulumlar için bu izin listesi modunu önerir. Aynı ayarlar sayfasında istemci başına saniyede 20 sorguluk varsayılan rate limit değerini koruyun.

Şimdi sunucudan ve VPN'e bağlı olmayan bir makineden test edin:

# sunucuda
sudo apt install bind9-dnsutils
dig @127.0.0.1 example.com +short
# VPN dışındaki başka bir makinede
dig @203.0.113.10 example.com +time=3 +tries=1

İlk sorgu bir IP adresi döndürür. İkincisi no servers could be reached ile zaman aşımına uğramalıdır; yanıt alırsa çözümleyiciniz açıktır, devam etmeden önce ufw kurallarını kontrol edin.

Adım 5 — AdGuard Home'u WireGuard istemcilerinizden kullanın

Her WireGuard istemcisinin [Interface] bölümündeki DNS satırını sunucunun VPN adresine çevirin ve yeniden bağlanın:

[Interface]
DNS = 10.8.0.1

10.8.0.1 VPN ağının içinde olduğu için bu hem tam tünelle hem de bölünmüş tünelle (AllowedIPs = 10.8.0.0/24) çalışır. İstemcide birkaç web sitesi açın; paneldeki Query Log, 10.8.0.2 adresinden gelen sorguları gösterir. Adresler yerine adlar görmek için her cihazı Settings, Client settings, Add client altında, VPN adresi tanımlayıcı olacak şekilde ekleyin. Bir çocuğun telefonu için farklı engelleme listeleri gibi istemci bazlı ayarlar da orada yapılır.

Adım 6 — VPN dışında DNS-over-HTTPS sunun (isteğe bağlı)

VPN kullanmaması gereken cihazlar için DNS-over-HTTPS'i (DoH) Caddy üzerinden yayınlayın. Caddy TLS'yi sonlandırır ve AdGuard Home'a yalnızca /dns-query yolunu iletir; yönetim arayüzü gizli kalır. Her cihaz kendini adresteki bir ClientID ile tanıtır; bu yöntem joker sertifika gerektirmez.

AdGuard Home'un proxy'den gelen DoH isteklerini düz HTTP üzerinden kabul etmesi gerekir. Servisi durdurun ve yapılandırma dosyasını açın:

sudo /opt/AdGuardHome/AdGuardHome -s stop
sudo nano /opt/AdGuardHome/AdGuardHome.yaml

Mevcut http: bölümünü ve onun doh: alt bölümünü bulun; yalnızca bu değeri true yapın (diğer anahtarları olduğu gibi bırakın):

http:
  doh:
    insecure_enabled: true

sudo /opt/AdGuardHome/AdGuardHome -s start

DoH sitesini /etc/caddy/Caddyfile dosyasına ekleyin. Diğer tüm yollar 404 döndürür:

dns.example.com {
    handle /dns-query* {
        reverse_proxy 127.0.0.1:3000
    }
    handle {
        respond 404
    }
}

AdGuard Home varsayılan olarak loopback adreslerindeki proxy'lere güvenir; bu yüzden Caddy'nin ilettiği gerçek istemci adresini loglar. Ardından panelde Settings, Client settings, Add client altında adı phone, tanımlayıcısı phone (bir ClientID) olan bir istemci ekleyin ve Allowed clients listesine yeni satır olarak phone yazın. Sonra Caddy'yi yeniden yükleyin ve BIND 9.18 ve sonrasında DoH'yi destekleyen dig ile kendi bilgisayarınızdan test edin:

sudo systemctl reload caddy
dig +https=/dns-query/phone @dns.example.com example.com +short

Sorgu bir adres döndürür ve sorgu logunda phone istemcisi olarak görünür. Cihazda DoH adresi olarak https://dns.example.com/dns-query/phone kullanın. İzin listesindeki bir ClientID'yi taşımayan istekler reddedilir.

Yedekleme ve geri yükleme

AdGuard Home durumunu /opt/AdGuardHome içinde tutar: AdGuardHome.yaml kullanıcılar, istemciler, filtreler ve izin listesi dahil tüm ayarları, data/ ise istatistikleri, sorgu logunu ve önbelleğe alınmış filtre listelerini tutar. Tutarlı bir kopya için servisi kısa süreliğine durdurun:

sudo mkdir -p /opt/backups
sudo /opt/AdGuardHome/AdGuardHome -s stop
sudo tar -czf /opt/backups/adguardhome-$(date +%F).tar.gz -C /opt/AdGuardHome AdGuardHome.yaml data
sudo /opt/AdGuardHome/AdGuardHome -s start

Sunucu ve istemcileriniz için DNS bu birkaç saniye boyunca durur. Sorgu logu arşivi çok büyütüyorsa yalnızca AdGuardHome.yaml dosyasını yedekleyin; kurulumu yeniden oluşturmak için yeterlidir. Arşivleri sunucunun dışına kopyalayın.

Geri yüklemek için AdGuard Home'u betikle kurun (Adım 1) ve Adım 2'yi uygulayın, ardından servisi durdurun, arşivi kurulumun üzerine açın ve yeniden başlatın. Yapılandırma zaten var olduğu için sihirbaz atlanır:

sudo /opt/AdGuardHome/AdGuardHome -s stop
sudo tar -xzf /opt/backups/adguardhome-2026-10-09.tar.gz -C /opt/AdGuardHome
sudo /opt/AdGuardHome/AdGuardHome -s start

AdGuard Home güncelleme

Önce sürüm notlarını okuyun ve yedek alın. Yeni bir sürüm çıktığında panel bir Update now düğmesi gösterir; komut satırındaki karşılığı şudur:

cd /opt/AdGuardHome
sudo ./AdGuardHome --update
sudo ./AdGuardHome -s status

AdGuard Home kendini güncellediğinde önceki çalıştırılabilir dosyayı ve yapılandırmayı kurulum klasörü içindeki bir backup klasöründe saklar. Ardından sürümü panelin alt kısmından kontrol edin.

Sorun giderme

listen udp 0.0.0.0:53: bind: address already in use

53 numaralı portu başka bir program tutuyor; bu neredeyse her zaman systemd-resolved stub dinleyicisidir. Hangisi olduğunu sudo ss -lunp | grep ':53 ' ile görün, Adım 2'yi uygulayın ve AdGuard Home'u sudo /opt/AdGuardHome/AdGuardHome -s restart ile yeniden başlatın.

Sunucunun kendisi adları çözümleyemiyor

Adım 2'den sonra sunucu AdGuard Home'a bağımlıdır. Servisin çalıştığını (sudo /opt/AdGuardHome/AdGuardHome -s status) ve 127.0.0.1 ile ::1 adreslerinin Allowed clients listesinde olduğunu kontrol edin. Geçici bir çıkış yolu olarak eski dosyayı sudo rm /etc/resolv.conf ve sudo mv /etc/resolv.conf.backup /etc/resolv.conf ile geri yükleyin.

WireGuard istemcileri DNS yanıtı alamıyor

Zincirin dört halkasını kontrol edin: istemcideki DNS = 10.8.0.1 satırı, tünelin kendisi (sudo wg show yakın tarihli bir el sıkışması gösterir), sudo ufw status çıktısındaki 53 on wg0 kuralı ve Allowed clients listesindeki 10.8.0.0/24. Sorgu logu, sorguların ulaşıp ulaşmadığını ve engellenip engellenmediğini veya reddedilip reddedilmediğini gösterir.

Caddy üzerinden DoH sorguları başarısız oluyor

Caddy'den gelen 404, yolun /dns-query ile başlamadığı anlamına gelir. AdGuard Home'dan gelen bir hata genellikle insecure_enabled değerinin hâlâ false olduğunu (dosyayı düzenlemeden önce servisi durdurun, yoksa değişikliğinizin üzerine yazılır) veya ClientID'nin Allowed clients listesinde bulunmadığını gösterir. Caddy loglarını journalctl -u caddy ile kontrol edin.

Yönetici parolasını unuttunuz

AdGuard Home parolanın bcrypt hash'ini AdGuardHome.yaml içinde saklar. Belgelerde anlatıldığı gibi apache2-utils paketindeki htpasswd ile yeni bir hash üretin:

sudo apt install apache2-utils
htpasswd -B -C 10 -n -b admin 'a-new-long-password'

Çıktı admin: ve ardından gelen hash'tir. Servisi durdurun, hash'i AdGuardHome.yaml içinde users: altındaki kullanıcınızın password: değerine yazın ve servisi yeniden başlatın. Komut parolayı içerdiği için ardından kabuk geçmişinizi temizleyin.

Sonraki adımlar

• VPN'inizi WireGuard VPN sunucusu veya wg-easy ile kurun ya da genişletin.
• Diğer servisleri Reverse proxy olarak Caddy ile HTTPS üzerinden yayınlayın.
• Sunucuyu Yeni bir Linux sunucusunu güvenli hale getirin rehberiyle daha da güçlendirin.
• Özel bir DNS çözümleyici için sunucuları AdGuard Home hosting sayfasında karşılaştırın.
• Filtreleme kuralları, DHCP ve tam yapılandırma başvurusu için AdGuard Home bilgi bankasını okuyun.