Aller au contenu principal

FAQ

Pourquoi AdGuard Home ne bloque-t-il pas les publicités ou les menaces ?​

Supposons que vous souhaitiez qu'AdGuard Home bloque somebadsite.com mais que, pour une raison quelconque, il ne le fasse pas. Essayons de résoudre ce problème.

Il est fort probable que vous n'ayez pas configuré votre appareil pour qu'il utilise AdGuard Home comme serveur DNS par défaut. Pour vérifier si vous utilisez AdGuard Home comme serveur DNS par défaut :

  1. Sous Windows, ouvrez une fenêtre de terminal (Démarrer → Exécuter → cmd.exe). Sur d'autres systèmes, ouvrez l'application Terminal.

  2. Exécutez nslookup example.org. Il affichera quelque chose comme ceci :

    Server: 192.168.0.1
    Address: 192.168.0.1#53

    Non-authoritative answer:
    Name: example.org
    Address: <IPv4>
    Name: example.org
    Address: <IPv6>

  3. Vérifiez que l'adresse IP du Server est celle où AdGuard Home est exécuté. Si ce n'est pas le cas, vous devez configurer votre appareil en conséquence. Voir ci-dessous pour savoir comment procéder.

  4. Assurez-vous que votre requête vers example.org apparaît dans l'interface utilisateur d'AdGuard sur la page Journal des requêtes. Si ce n'est pas le cas, vous devez configurer AdGuard Home pour qu'il écoute sur l'interface réseau spécifiée. La façon la plus simple de le faire est de réinstaller AdGuard Home avec les paramètres par défaut.

Si vous êtes sûr que votre appareil utilise AdGuard Home comme serveur DNS par défaut, mais que le problème persiste, cela peut être dû à une mauvaise configuration d'AdGuard Home. Veuillez vérifier et vous assurer que :

  1. Vous avez activé le paramètre Bloquer les domaines à l'aide des filtres et des fichiers hosts sur la page Paramètres → Paramètres généraux.

  2. Vous avez activé les mécanismes de sécurité appropriés, tels que le Contrôle parental, sur la même page.

  3. Vous avez activé les filtres appropriés sur la page Filtres → Listes de blocage DNS.

  4. Vous n'avez pas de listes de règles d'exception susceptibles d'autoriser les requêtes activées sur la page Filtres → Listes d'autorisation DNS.

  5. Vous n'avez pas de réécritures DNS qui pourraient interférer sur la page Filtres → Réécritures DNS.

  6. Vous n'avez pas de règles de filtrage personnalisées qui peuvent interférer sur la page Filtres → Règles de filtrage personnalisées.

Que signifie « Bloqué par CNAME ou IP » dans le journal de requêtes ?​

AdGuard Home vérifie à la fois les requêtes DNS et les réponses DNS pour prévenir une technique d'évasion des annonces connue sous le nom de CNAME cloaking. Autrement dit, si vos règles de filtrage contiennent un domaine, par exemple tracker.example, et qu'une réponse DNS pour un autre nom de domaine, par exemple blogs.example, contient ce nom de domaine parmi ses enregistrements CNAME, cette réponse est bloquée, car elle mène en fait au service de suivi bloqué.

Où puis-je consulter les journaux ?​

L'emplacement par défaut des journaux en texte brut (à ne pas confondre avec les journaux de requête) dépend du système d'exploitation et du mode d'installation :

  • OpenWrt Linux: utilisez la commande logread -e AdGuardHome.

  • Systèmes Linux avec systemd et autres systèmes Unix avec init de style SysV : /var/log/AdGuardHome.err.

  • macOS : /var/log/AdGuardHome.stderr.log.

  • Systèmes Linux avec Snapcraft utilisez la commande snap logs adguard-home.

  • FreeBSD : /var/log/daemon.log.

  • OpenBSD : /var/log/daemon.

  • Windows : le journal des événements Windows est utilisé.

Comment configurer AdGuard Home pour écrire des journaux de niveau détaillé ?​

Pour résoudre un problème complexe, il est parfois nécessaire d'utiliser la journalisation de niveau détaillé. Voici comment l'activer :

  1. Arrêtez AdGuard Home :

    ./AdGuardHome -s stop

  2. Configurez AdGuard Home pour écrire des journaux de niveau détaillé :

    1. Ouvrez AdGuardHome.yaml dans votre éditeur.

    2. Définissez log.file sur le chemin souhaité du fichier journal, par exemple /tmp/aghlog.txt. Notez que le répertoire doit déjà exister.

    3. Définissez log.verbose sur true.

  3. Redémarrez AdGuard Home et reproduisez le problème :

    ./AdGuardHome -s start

  4. Une fois que vous avez terminé le débogage, remettez log.verbose à false.

Comment afficher une page de blocage personnalisée ?​

note

Avant de faire tout cela, veuillez noter que les navigateurs modernes sont configurés pour utiliser HTTPS, donc ils valident l'authenticité du certificat du serveur Web. Cela signifie que l'utilisation de l'un de ces éléments entraînera des écrans d'avertissement.

Il existe un certain nombre d'extensions proposées qui, si elles sont raisonnablement bien prises en charge par les clients, offriraient une meilleure expérience utilisateur, y compris les codes d'erreur DNS étendus RFC 8914 et le projet de page d'erreur d'accès DNS RFC. Nous les mettrons en œuvre lorsque les navigateurs commenceront réellement à les prendre en charge.

Prérequis​

Pour utiliser l'une de ces méthodes pour afficher une page de blocage personnalisée, vous aurez besoin d'un serveur HTTP en cours d'exécution sur une adresse IP et servant la page en question sur tous les itinéraires. Quelque chose comme pixelserv-tls.

Page de blocage personnalisée pour le Contrôle parental et les filtres de navigation sécurisée​

Il n'existe actuellement aucun moyen de définir ces paramètres depuis l'interface utilisateur, vous devrez donc modifier manuellement le fichier de configuration :

  1. Arrêtez AdGuard Home :

    ./AdGuardHome -s stop

  2. Ouvrez AdGuardHome.yaml dans votre éditeur.

  3. Définissez les paramètres dns.parental_block_host ou dns.safebrowsing_block_host sur l'adresse IP du serveur (dans cet exemple, 192.168.123.45) :

    # …
    dns:
      # …

      # NOTE : Changez à l'adresse IP réelle de votre serveur.
      parental_block_host: 192.168.123.45
      safebrowsing_block_host: 192.168.123.45

  4. Redémarrez AdGuard Home :

    ./AdGuardHome -s start

Page de blocage personnalisée pour d'autres filtres​

  1. Ouvrez l'interface Web.

  2. Accédez à Paramètres → Paramètres DNS.

  3. Dans la section Configuration du serveur DNS, sélectionnez le bouton radio IP personnalisée dans le sélecteur Mode de blocage et saisissez les adresses IPv4 et IPv6 du serveur.

  4. Cliquez sur Enregistrer.

Comment changer l'adresse de l'interface du tableau de bord ?​

  1. Arrêtez AdGuard Home :

    ./AdGuardHome -s stop

  2. Ouvrez AdGuardHome.yaml dans votre éditeur.

  3. Définissez le paramètre http.address sur une nouvelle interface réseau. Par exemple :

    • 0.0.0.0:0 pour écouter sur toutes les interfaces réseau ;
    • 0.0.0.0:8080 pour écouter sur toutes les interfaces réseau avec le port 8080 ;
    • 127.0.0.1:0 pour écouter uniquement sur l'interface de boucle locale.

  4. Redémarrez AdGuard Home :

    ./AdGuardHome -s start

Comment configurer AdGuard Home en tant que serveur DNS par défaut ?​

Consultez la section Configuration des appareils sur la page Premiers pas.

Existe-t-il des limitations connues ?​

Voici quelques exemples de ce qui ne peut pas être bloqué par un bloqueur au niveau DNS :

  • YouTube, publicités Twitch.

  • Facebook, X (anciennement Twitter), publications sponsorisées Instagram.

Fondamentalement, toute publicité qui partage un domaine de contenu ne peut pas être bloquée par un bloqueur au niveau DNS, à moins que vous ne soyez prêt à bloquer le contenu également.

Y a-t-il une possibilité de résoudre cela à l'avenir ?​

DNS ne sera jamais suffisant pour cela. Votre seule option est d'utiliser un proxy de blocage de contenu comme ce que nous faisons dans les applications AdGuard autonomes. Nous ajouterons la prise en charge de cette fonctionnalité à AdGuard Home à l'avenir. Malheureusement, même alors, il y aura encore des cas où cela ne sera pas suffisant ou nécessitera une configuration assez compliquée.

Pourquoi obtiens-je l'erreur bind: address already in use lorsque j'essaie d'installer sur Ubuntu ?​

Cela se produit parce que le port 53 sur localhost, qui est utilisé pour DNS, est déjà pris par un autre programme. Ubuntu est livré avec un DNS local appelé systemd-resolved, qui utilise l'adresse 127.0.0.53:53, empêchant donc AdGuard Home de se lier à 127.0.0.1:53. Vous pouvez voir cela en exécutant :

sudo lsof -i :53

La sortie devrait être semblable à :

COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
systemd-r 14542 systemd-resolve 13u IPv4 86178 0t0 UDP 127.0.0.53:domain
systemd-r 14542 systemd-resolve 14u IPv4 86179 0t0 TCP 127.0.0.53:domain

Pour résoudre cela, vous devez soit désactiver le démon systemd-resolved, soit choisir une autre interface réseau et lier votre AdGuard Home à une adresse IP accessible dessus, telle que l'adresse IP de votre routeur dans votre réseau. Mais si vous devez écouter sur localhost, il existe plusieurs solutions.

Tout d'abord, AdGuard Home peut détecter de telles configurations et désactiver systemd-resolved pour vous si vous appuyez sur le bouton Réparer situé à côté du message address already in use sur l'écran d'installation.

Secondly, if that doesn’t work, follow the instructions below. Note that if you’re using AdGuard Home with docker or snap, you’ll have to do this yourself.

  1. Create the /etc/systemd/resolved.conf.d directory, if necessary:

    sudo mkdir -p /etc/systemd/resolved.conf.d

  2. Deactivate DNSStubListener and update DNS server address. To do that, create a new file, /etc/systemd/resolved.conf.d/adguardhome.conf, with the following content:

    [Resolve]
    DNS=127.0.0.1
    DNSStubListener=no

Specifying 127.0.0.1 as the DNS server address is necessary. Otherwise the nameserver will be 127.0.0.53 which won’t work without DNSStubListener.

  1. Activate another resolv.conf file:

    sudo mv /etc/resolv.conf /etc/resolv.conf.backup
    sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf

  2. Restart DNSStubListener:

    sudo systemctl reload-or-restart systemd-resolved

After that, systemd-resolved shouldn’t be shown in the output of lsof, and AdGuard Home should be able to bind to 127.0.0.1:53.

How do I configure a reverse proxy server for AdGuard Home?​

If you’re already running a web server and want to access the AdGuard Home dashboard UI from a URL like http://YOUR_SERVER/aghome/, you can use this configuration for your web server:

nginx​

location /aghome/ {
 proxy_cookie_path / /aghome/;
 proxy_pass http://AGH_IP:AGH_PORT/;
 proxy_redirect / /aghome/;
 proxy_set_header Host $host;
}

caddy​

:80/aghome/* {
 route {
 uri strip_prefix /aghome
 reverse_proxy AGH_IP:AGH_PORT
 }
}

Ou, si vous souhaitez simplement servir AdGuard Home avec TLS automatique, utilisez une configuration similaire à l'exemple ci-dessous :

DOMAIN {
 encode gzip zstd
 tls YOUR_EMAIL@DOMAIN
 reverse_proxy AGH_IP:AGH_PORT
}

Apache​

<VirtualHost *:80>
  ProxyPass "/" "http://AGH_IP:AGH_PORT/"
  ProxyPassReverse "/" "http://AGH_IP:AGH_PORT/"
  PreserveHost On
</VirtualHost>
note

N’utilisez pas de sous-répertoires avec le proxy HTTP inverse Apache. C'est un problème connu (#6604) : Apache gère les redirections relatives différemment des autres serveurs web. This causes problems with the AdGuard Home web interface.

Disable DoH encryption on AdGuard Home​

If you’re using TLS on your reverse proxy server, you don’t need to use TLS on AdGuard Home. Set allow_unencrypted_doh: true in AdGuardHome.yaml to allow AdGuard Home to respond to DoH requests without TLS encryption.

Real IP addresses of clients​

You can set the parameter trusted_proxies to the IP address(es) of your HTTP proxy to make AdGuard Home consider the headers containing the real client IP address. See the configuration and encryption pages for more information.

How do I fix permission denied errors on Fedora?​

  1. Move the AdGuardHome binary to /usr/local/bin.

  2. As root, execute the following command to change the security context of the file:

    chcon -t bin_t /usr/local/bin/AdGuardHome

  3. Add the required firewall rules in order to make it reachable through the network. Par exemple :

    firewall-cmd --new-zone=adguard --permanent
    firewall-cmd --zone=adguard --add-source=192.168.0.14/24 --permanent
    firewall-cmd --zone=adguard --add-port=3000/tcp --permanent
    firewall-cmd --zone=adguard --add-port=53/udp --permanent
    firewall-cmd --zone=adguard --add-port=80/tcp --permanent
    firewall-cmd --reload

If you are still getting code=exited status=203/EXEC or similar errors from systemctl, try uninstalling AdGuard Home and installing it directly into /usr/local/bin by using the -o option of the install script:

curl -s -S -L 'https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh' | sh -s -- -o '/usr/local/bin' -v

Voir [problème 765] et [problème 3281].

How do I fix incompatible file system errors?​

You should move your AdGuard Home installation or working directory to another location. See the limitations section on the Getting Started page.

What does Error: control/version.json mean?​

This error message means that AdGuard Home was unable to reach AdGuard servers to check for updates and/or download them. This could mean that the servers are blocked by your ISP or are temporarily down. If the error does not resolve itself after some time, you can try performing a manual update or disabling the automatic update check by running the AdGuardHome executable with the --no-check-update command-line option.

How do I update AdGuard Home manually?​

If the button isn’t displayed or an automatic update has failed, you can update manually. In the examples below, we’ll use AdGuard Home versions for Linux and Windows for AMD64 CPUs.

Unix (Linux, macOS, BSD)​

  1. Download the new AdGuard Home package from the releases page. If you want to perform this step from the command line, type:

    curl -L -S -o '/tmp/AdGuardHome_linux_amd64.tar.gz' -s\
    'https://static.adguard.com/adguardhome/release/AdGuardHome_linux_amd64.tar.gz'

    Or, with wget:

    wget -O '/tmp/AdGuardHome_linux_amd64.tar.gz'\
    'https://static.adguard.com/adguardhome/release/AdGuardHome_linux_amd64.tar.gz'

  2. Navigate to the directory where AdGuard Home is installed. On most Unix systems the default directory is /opt/AdGuardHome, but on macOS it’s /Applications/AdGuardHome.

  3. Arrêtez AdGuard Home :

    sudo ./AdGuardHome -s stop
    OpenBSD

    On OpenBSD, you will probably want to use doas instead of sudo.

  4. Backup your data. That is, your configuration file and the data directory (AdGuardHome.yaml and data/ by default). For example, to backup your data to a new directory called ~/my-agh-backup:

    mkdir -p ~/my-agh-backup
    cp -r ./AdGuardHome.yaml ./data ~/my-agh-backup/

  5. Extract the AdGuard Home archive to a temporary directory. For example, if you downloaded the archive to your /tmp/ directory:

    tar -C /tmp/ -f /tmp/AdGuardHome_linux_amd64.tar.gz -x -v -z

    Sur macOS, tapez quelque chose comme :

    unzip -d /tmp/ /tmp/AdGuardHome_darwin_amd64.zip

  6. Remplacez l'ancien fichier exécutable AdGuard Home par le nouveau. On most Unix systems the command would look something like this:

    sudo cp /tmp/AdGuardHome/AdGuardHome /opt/AdGuardHome/AdGuardHome

    On macOS, something like:

    sudo cp /tmp/AdGuardHome/AdGuardHome /Applications/AdGuardHome/AdGuardHome

    You may also want to copy the documentation parts of the package, such as the change log (CHANGELOG.md), the README file (README.md), and the license (LICENSE.txt).

    You can now remove the temporary directory.

  7. Redémarrez AdGuard Home :

    sudo ./AdGuardHome -s start

Windows (Using PowerShell)​

In all examples below, the PowerShell must be run as Administrator.

  1. Download the new AdGuard Home package from the releases page. If you want to perform this step from the command line:

    $outFile = Join-Path -Path $Env:USERPROFILE -ChildPath 'Downloads\AdGuardHome_windows_amd64.zip'
    $aghUri = 'https://static.adguard.com/adguardhome/release/AdGuardHome_windows_amd64.zip'
    Invoke-WebRequest -OutFile "$outFile" -Uri "$aghUri"

  2. Navigate to the directory where AdGuard Home was installed. In the examples below, we’ll use C:\Program Files\AdGuardHome.

  3. Arrêtez AdGuard Home :

    .\AdGuardHome.exe -s stop

  4. Backup your data. That is, your configuration file and the data directory (AdGuardHome.yaml and data/ by default). For example, to backup your data to a new directory called my-agh-backup:

    $newDir = Join-Path -Path $Env:USERPROFILE -ChildPath 'my-agh-backup'
    New-Item -Path $newDir -ItemType Directory
    Copy-Item -Path .\AdGuardHome.yaml, .\data -Destination $newDir -Recurse

  5. Extract the AdGuard Home archive to a temporary directory. For example, if you downloaded the archive to your Downloads directory and want to extract it to a temporary directory:

    $outFile = Join-Path -Path $Env:USERPROFILE -ChildPath 'Downloads\AdGuardHome_windows_amd64.zip'
    Expand-Archive -Path "$outFile" -DestinationPath $Env:TEMP

  6. Remplacez l'ancien fichier exécutable AdGuard Home par le nouveau. Par exemple :

    $aghExe = Join-Path -Path $Env:TEMP -ChildPath 'AdGuardHome\AdGuardHome.exe'
    Copy-Item -Path "$aghExe" -Destination .\AdGuardHome.exe

    You may also want to copy the documentation parts of the package, such as the change log (CHANGELOG.md), the README file (README.md), and the license (LICENSE.txt).

    You can now remove the temporary directory.

  7. Redémarrez AdGuard Home :

    .\AdGuardHome.exe -s start

How do I uninstall AdGuard Home?​

Depending on how you installed AdGuard Home, there are different ways to uninstall it.

prudence

Before uninstalling AdGuard Home, don’t forget to change the configuration of your devices and point them to a different DNS server.

Regular installation​

In this case, do the following:

  • Unregister AdGuard Home service: ./AdGuardHome -s uninstall.

  • Remove the AdGuard Home directory.

Docker​

Simply stop and remove the image.

Snap Store​

snap remove adguard-home