AdGuard Home : de l'interface web au filtrage des clients

E2Reproduit dans une VM de laboratoire

Environnement concernéTesté

Firmware

OpenWrt

Version

25.12.6

Paquets

apk

Appareil

VM PVE 201 / 1 Go

Dernier essai en laboratoire 2026-10-20Journal de test

Résultat attendu

• AdGuard Home gère le port 53 d’OpenWrt ; l’interface web est sur 3000.
• dnsmasq passe sur 5353 et continue d’assurer le DHCP.
• Les clients DHCP reçoivent 192.168.2.1 comme DNS.
• Une règle de filtrage personnalisée bloque un domaine de test, tandis que les noms normaux sont toujours résolus.
• Le disque de données, la configuration d’AGH et le filtre survivent à un redémarrage.

Environnement concerné et topologie

• PVE 9.2.2 avec une seule carte réseau ; VM 201 OpenWrt 25.12.6 x86_64 (1 Go de RAM, disque de données de 2 Go).
• WAN net0 sur vmbr0 (DHCP) ; LAN net1 sur un vmbr2 isolé (192.168.2.0/24).
• AGH 0.107.79 issu du dépôt apk d’OpenWrt.
• Ne partagez pas un même pont entre deux VM OpenWrt qui exécutent toutes deux du DHCP : dans ce laboratoire, la VM 200 est sur vmbr1 (192.168.1.0/24), donc la VM 201 doit utiliser vmbr2 (192.168.2.0/24). Sinon, un client peut recevoir un bail du mauvais sous-réseau.

Port physique	Bridge PVE	Carte réseau virtuelle	Interface OpenWrt	Rôle
nic0	vmbr0	net0	wan DHCP	amont 192.168.50.1
—	vmbr2	net1	lan 192.168.2.1	AGH + clients DHCP

Ports et responsabilités

Port	Composant	Rôle
53	AdGuard Home	DNS des clients, filtrage, transfert vers l’amont
3000	AdGuard Home	interface web
5353	dnsmasq	DHCP et DNS local ; n’est plus sur le 53

Ne liez pas AGH et dnsmasq au port 53 en même temps. Ne pointez pas l’option 6 du DHCP vers une adresse qui n’écoute pas sur le 53.

Avant de modifier quoi que ce soit

Shell du routeurSauvegardez la configuration et préparez le disque de données

cp /etc/config/dhcp /etc/config/dhcp.bak.$(date +%F)
cp /etc/config/adguardhome /etc/config/adguardhome.bak.$(date +%F) 2>/dev/null || true
cat /etc/config/dhcp

Gardez un accès console ou LAN à OpenWrt. Ne faites pas dépendre votre seul chemin de gestion du DNS que vous modifiez.

AttenduVous pouvez restaurer la configuration de dnsmasq et d'AGH.

Étapes minimales

La page d'accueil du premier lancement d'AGH 0.107.79. Cliquez sur Get Started pour ouvrir l'assistant de configuration. Capture réalisée dans un laboratoire temporaire ; la langue chinoise est sélectionnée.

Shell du routeurInstallez AGH, les outils du disque de données et la prise en charge de fstab

apk update
apk add adguardhome block-mount e2fsprogs

e2fsprogs fournit mkfs.ext4 ; block-mount fournit le service fstab. Un miroir OpenWrt local convient, mais les paquets doivent tout de même passer la vérification des signatures.

Attenduadguardhome, block-mount et e2fsprogs sont installés.

Shell du routeurFormatez et rendez persistant le disque de données

N’exécutez ceci que sur un disque de données de laboratoire dont vous avez confirmé qu’il est vide :

mkfs.ext4 -F /dev/sdb
mkdir -p /opt/agh
mount /dev/sdb /opt/agh
block info /dev/sdb

Utilisez l’UUID affiché par block info. Dans LuCI (Mount Points), définissez la cible de ce disque sur /opt/agh et activez-le ; ou repérez le @mount[n] correspondant en ligne de commande :

uci show fstab
# find the @mount[n] whose uuid is <your-UUID>
uci set fstab.@mount[n].target='/opt/agh'
uci set fstab.@mount[n].enabled='1'
uci commit fstab
/etc/init.d/fstab enable
block mount
mount | grep /opt/agh

Ce laboratoire a utilisé le fstab.@mount[2] détecté automatiquement pour le disque de données de 2 Go ; changer sa cible en /opt/agh et l’activer a fonctionné. Ne copiez pas [2] ; faites la correspondance avec votre UUID.

Attendu/opt/agh se trouve sur un disque séparé et survit au redémarrage.

Shell du routeurDéplacez dnsmasq sur le port 5353

uci set dhcp.@dnsmasq[0].port='5353'
uci commit dhcp
/etc/init.d/dnsmasq restart
netstat -lnp | grep -E ':53|:5353'

Les clients ne peuvent pas résoudre sur le 53 tant qu’AGH n’a pas démarré.

AttenduLe port 53 est libre et le DHCP fonctionne toujours.

Shell du routeurDémarrez AGH et terminez la configuration du premier lancement

uci set adguardhome.config.work_dir='/opt/agh/work'
uci commit adguardhome
mkdir -p /opt/agh/work
chown -R adguardhome:adguardhome /opt/agh /etc/adguardhome
/etc/init.d/adguardhome enable
/etc/init.d/adguardhome start
sleep 3
netstat -lnp | grep -E ':3000|:53'

Ouvrez http://192.168.2.1:3000/ et définissez :

• le port web 3000 ;
• le port DNS 53 ;
• un nom d’utilisateur et un mot de passe d’administration ;
• le DNS amont 192.168.50.1 pour ce laboratoire ;
• désactivez DNSSEC si l’amont ne le valide pas.

Si vous n’avez pas de navigateur, utilisez l’API de configuration d’AGH ; ne versionnez jamais le mot de passe d’administration.

AttenduL'interface web est accessible sur le port 3000.

Shell du routeurAnnoncez AGH via le DHCP

uci add_list dhcp.lan.dhcp_option='6,192.168.2.1'
uci commit dhcp
/etc/init.d/dnsmasq restart
uci show dhcp.lan | grep dhcp_option

Changer seulement le port de dnsmasq peut empêcher certains clients de recevoir un DNS ; définissez explicitement l’option 6.

AttenduLes clients reçoivent 192.168.2.1 comme DNS.

LuCIAjoutez une règle de filtrage déterministe

Dans Filtres → Règles de filtrage personnalisées, ajoutez :

||blocked.example^

Il s’agit d’un domaine de test réservé. Ajoutez des listes de filtres maintenues plus tard pour un usage réel. Vérifiez avec nslookup, et non en jugeant que « la page semble cassée ».

Attendublocked.example renvoie 0.0.0.0 ; les noms normaux sont toujours résolus.

Vérification

Le tableau de bord après la configuration. Zéro requête juste après la configuration est normal ; vérifiez d'abord le port DNS et l'amont.

Shell du routeurVérifiez les ports et la résolution locale

netstat -lnp | grep -E ':53|:3000|:5353'
nslookup blocked.example 192.168.2.1
nslookup openwrt.org 192.168.2.1

Attendu : blocked.example renvoie 0.0.0.0 (IPv6 peut aussi afficher ::) ; openwrt.org renvoie une véritable adresse.

AttenduAGH écoute sur 53/3000 ; dnsmasq sur 5353.

OrdinateurVérifiez depuis un client DHCP

ip addr show
ip route
cat /etc/resolv.conf
nslookup blocked.example
nslookup openwrt.org

Si le DNS du client n’est pas 192.168.2.1, revenez à l’option 6 du DHCP et au port de dnsmasq.

AttenduLe client obtient 192.168.2.x et le DNS 192.168.2.1.

Shell du routeurRevérifiez après le redémarrage

reboot

Après le redémarrage :

mount | grep /opt/agh
netstat -lnp | grep -E ':53|:3000'
nslookup blocked.example 192.168.2.1
nslookup openwrt.org 192.168.2.1

AttenduLe disque de données se monte, AGH démarre et la règle survit.

Branches d’échec et récupération

AGH ne démarre pas / le port 53 est occupé

logread | grep -i adguard | tail -50
netstat -lnp | grep ':53'
/usr/bin/AdGuardHome --check-config -c /etc/adguardhome/adguardhome.yaml

Si dnsmasq occupe encore le 53, confirmez dhcp.@dnsmasq[0].port='5353'. Pour une configuration défectueuse, restaurez la sauvegarde :

cp /etc/adguardhome/adguardhome.bak.YYYY-MM-DD /etc/adguardhome/adguardhome.yaml
/etc/init.d/adguardhome restart

Les clients ne résolvent plus rien

Rendez temporairement le DNS à dnsmasq :

uci set dhcp.@dnsmasq[0].port='53'
uci -q delete dhcp.lan.dhcp_option
uci commit dhcp
/etc/init.d/dnsmasq restart
/etc/init.d/adguardhome stop

Rétablissez d’abord la résolution de base, puis diagnostiquez AGH couche par couche.

Le disque de données n’est pas monté

mount | grep /opt/agh
block info /dev/sdb
logread | grep -i fstab

Vérifiez l’UUID, la cible et l’indicateur d’activation dans fstab ; montez manuellement, puis redémarrez AGH.

Le filtrage ne fonctionne pas

La page des filtres liste les listes de blocage activées. Cette capture ne montre que celles par défaut, sans abonnement tiers ; ajoutez séparément une règle de test.

• Vérifiez que le client utilise réellement AGH comme DNS.
• Vérifiez que la règle se trouve sous Règles de filtrage personnalisées, et non dans un abonnement.
• Interrogez AGH directement : nslookup blocked.example 192.168.2.1.
• Le DoH du navigateur ou du système peut contourner AGH.

Essai en laboratoire E2 (2026-10-20)

• Environnement : PVE 9.2.2 avec une seule carte réseau ; VM 201 sous OpenWrt 25.12.6 (1 Go / disque de données de 2 Go) ; AGH 0.107.79.
• Ports : AGH 53 + web 3000 ; dnsmasq 5353 ; option 6 du DHCP 192.168.2.1.
• Client : DHCP 192.168.2.166/24, DNS 192.168.2.1 ; blocked.example → 0.0.0.0, openwrt.org → 64.226.122.113.
• Redémarrage : /opt/agh monté via fstab ; AGH, dnsmasq et les règles de filtrage rétablis ; le web a renvoyé 302.
• Non testé : interaction réelle avec l’interface dans un navigateur, listes d’abonnement externes, clients LAN physiques, IPv6, stabilité sur la durée.

Sources et relecture

• Il s’agit d’un relevé de laboratoire E2 ; il n’a pas fait l’objet d’une relecture indépendante ni d’un test sur un LAN physique.
• Recette : tests/recipes/agh-25.12-vm201.md ; notes d’environnement : docs/agh-e2-run.md.
• Mettez à jour testedVersions quand le paquet ou la version change ; ne copiez pas les scripts d’initialisation d’une version de firmware à l’autre.

Journal de testStatut: Reproduit en laboratoire (E2)

Environnement

PVE 9.2.2 avec une seule carte réseau ; VM 201 sous OpenWrt 25.12.6 ; AGH 0.107.79 ; vmbr2 192.168.2.0/24

Recette

tests/recipes/agh-25.12-vm201.md

Date

2026-10-20

Résultat

AGH 53 + web 3000 ; dnsmasq 5353 ; option 6 du DHCP → 192.168.2.1 ; le client obtient blocked.example=0.0.0.0 et openwrt.org est résolu ; fstab, règles et service ont survécu au redémarrage

Reproduit en laboratoire (E2) ; sans relecture indépendante ni test sur un réseau physique. Le niveau E3 exige toujours du matériel réel.

Sources

• Paquet adguardhome d'OpenWrt
• Documentation d'AdGuard Home
• dnsmasq et DHCP sous OpenWrt
• fstab / block-mount sous OpenWrt