Syntaxe des règles de filtrage DNS
info
Nous vous montrons ici comment écrire des règles de filtrage DNS personnalisées à utiliser dans les produits AdGuard
Quick links: Download AdGuard Ad Blocker, Get AdGuard Home, Try AdGuard DNS
Introduction
Vous pouvez utiliser la syntaxe de règles de filtrage DNS AdGuard pour rendre les règles plus flexibles, pour qu’elles puissent bloquer le contenu selon vos préférences. La syntaxe des règles de filtrage DNS AdGuard peut être utilisée dans des produits AdGuard différents, tels que AdGuard Home, AdGuard DNS, AdGuard pour Windows/Mac/Android.
Il y existe trois approches différentes pour écrire des listes de blocage d’hôtes :
Syntaxe de style Adblock: l'approche moderne de l'écriture de règles de filtrage basée sur l'utilisation d'un sous-ensemble de la syntaxe de règle de style Adblock. De cette façon, les listes de blocage sont compatibles avec les bloqueurs de publicités du navigateur.
/etc/hosts
syntaxe: la vieille approche éprouvée qui utilise la même syntaxe que les systèmes d'exploitation pour leurs fichiers hosts.Domains-only syntax: une simple liste de noms de domaine.
Si vous créez une liste de blocage, nous vous recommandons d'utiliser la syntaxe de type Adblock. Elle présente quelques avantages importants par rapport à l’ancienne syntaxe :
Taille des listes de blocage. L'utilisation de la correspondance de modèles vous permet d'avoir une seule règle au lieu de centaines d'entrées
/etc/hosts
.Compatibilité. Votre liste de blocage sera compatible avec les bloqueurs de publicité des navigateurs et il sera plus facile de partager des règles avec une liste de filtrage des navigateurs.
Extensibilité. Au cours de la dernière décennie, la syntaxe de style Adblock a beaucoup évolué, et nous ne voyons aucune raison de ne pas l’étendre encore plus loin et d’offrir des fonctionnalités supplémentaires pour les bloqueurs au niveau du réseau.
Si vous maintenez une liste de blocage de style /etc/hosts
ou plusieurs listes de filtrage (quel que soit le type), nous fournissons un outil pour la compilation de listes de blocage. Nous l'avons nommé Hostlist compiler et nous l'utilisons nous-mêmes pour créer le Filtre AdGuard DNS.
Exemples de base
||example.org^
: bloque l'accès au domaineexample.org
et à tous ses sous-domaines, commewww.example.org
.@@||example.org^
: débloque l'accès au domaineexample.org
et à tous ses sous-domaines.1.2.3.4 example.org
: (attention, ancienne/etc/hosts
-syntaxe) dans AdGuard Home, réponse avec1.2.3.4
aux requêtes pourexample.org
domaine mais pas ses sous-domaines. Dans AdGuard DNS Privé, bloque l'accès àexample.org
.www.example.org
reste autorisé.Dans AdGuard Home, utiliser l’adresse IP non spécifiée (
0.0.0.0
) ou une adresse locale (127.0.0.1
et les mêmes) pour un hôte est fondamentalement la même chose que de bloquer cet hôte.# Retourne l’adresse IP 1.2.3.4 par exemple.
1.2.3.4 example.org
Bloque example.org en répondant avec 0.0.0.0.
0.0.0.0 example.org
- `example.org`: une règle de domaine simple. Bloque le domaine `example.org` mais **pas** ses sous-domaines. `www.example.org` reste autorisé.
- `! Voici un commentaire ` et `# aussi un commentaire `: Comments.
- `/REGEX/`: bloquez l’accès aux domaines correspondant à l’expression régulière spécifiée.
## Syntaxe de style Adblock
Il s'agit d'un sous-ensemble de la [ syntaxe traditionnelle du style Adblock][adb] qui est utilisée par les bloqueurs de publicités dans les navigateurs.
```none
règle = ["@@"] modèle [" $" modificateurs]
Modificateurs = [modier0, modier1 [, … [, modifié]]]
pattern
: le masque de nom d’hôte. Chaque nom d'hôte est comparé à ce masque. Le modèle peut également contenir des caractères spéciaux, qui sont décrits ci-dessous.@@
: le marqueur utilisé dans les règles d’exception. Commencez votre règle avec ce marqueur si vous voulez arrêter le filtrage pour les noms d’hôtes correspondants.modificateurs
: paramètres qui clarifient la règle. Ils peuvent limiter la portée de la règle ou même modifier complètement son fonctionnement.
Caractères spéciaux
*
: le caractère générique. Il est utilisé pour représenter n’importe quel ensemble de caractères. Cela peut aussi être une chaîne vide ou une chaîne de n’importe quelle longueur.||
: correspond au début d’un nom d’hôte, y compris un sous-domaine. Par exemple,||example.org
correspond àexample.org
ettest.example.org
mais pastestexample.org
.^
: le caractère séparateur. Contrairement au blocage des publicités en navigateur, il n'y a rien à séparer dans un nom d'hôte, donc le seul but de ce caractère est de marquer la fin du nom d'hôte.|
: un pointeur vers le début ou la fin du nom d'hôte. La valeur dépend du placement des caractères dans le masque. Par exemple, la règleample.org|
correspond àexample.org
mais pas àexample.org.com
.|exemple
correspond àexemple.org
mais pas àtest.exemple
.
Expressions régulières
Si vous souhaitez bénéficier d'une plus grande souplesse dans l'élaboration des règles, vous pouvez utiliser les expressions régulières au lieu de la syntaxe correspondante simplifiée par défaut. Si vous souhaitez utiliser une expression régulière, le modèle doit ressembler à ceci :
modèle = "/" regexp "/"
Exemples :
/exemple.*/
bloquera les hôtes correspondant à l'exemple*
regexp.@@/exemple.*/$important
débloquera les hôtes correspondant à l'exemple*
regexp. Notez que cette règle implique également le modificateurimportant
.
Commentaires
Toute ligne commençant par un point d'exclamation ou un dièse est un commentaire et sera ignorée par le moteur de filtrage. Les commentaires sont généralement placés au-dessus des règles et utilisés pour décrire ce que fait une règle.
Exemple :
! Ceci est un commentaire.
# Ceci est aussi un commentaire.
Modificateurs de règles
Vous pouvez modifier le comportement d'une règle en ajoutant des modificateurs. Les modificateurs doivent être situés à la fin de la règle après le caractère $
et être séparés par des virgules.
Exemples :
||example.org^
est le modèle correspondant.$
est le délimiteur, qui signale que le reste de la règle sont des modificateurs.important
est le modificateur.Vous pouvez utiliser plusieurs modificateurs dans une règle. Dans ce cas, séparez-les par des virgules :
||example.org^$client=127.0.0.1,dnstype=A
||example.org^
est le modèle correspondant.$
est le délimiteur, qui signale que le reste de la règle sont des modificateurs.client=127.0.0.1
est le modificateurclient
avec sa valeur,127.0.0.1
, est le délimiteur. Et enfin,dnstype=A
est le modificateurdnstype
avec sa valeur,A
.
ATTENTION : Si une règle contient un modificateur non répertorié dans ce document, toute la règle doit être ignorée. De cette façon, nous évitons les faux positifs lorsque les gens essaient d'utiliser les listes de filtres des bloqueurs de publicités de navigateur non modifiés comme EasyList ou EasyPrivacy.
client
Le modificateur client
permet de spécifier les clients auxquels cette règle s'applique. Il existe deux façons principales d'identifier un client :
Par leur adresse IP ou leur préfixe CIDR. Cette méthode fonctionne pour tous les types de clients.
Par leur nom. Cette méthode ne fonctionne que pour les clients persistants (dans AdGuard Home) et les appareils (dans AdGuard DNS Privé), que vous avez ajoutés manuellement.
REMARQUE : Dans AdGuard Home, les ID client ne sont actuellement pas pris en charge, seuls les noms le sont. Si vous avez ajouté un client portant le nom "My client" et le numéro de client
my-client
, écrivez votre modificateur sous la forme$client='My Client'
au lieu de$client=my-client
.
La syntaxe est :
$client=value1|value2|...
Vous pouvez également exclure des clients en ajoutant un caractère ~
avant la valeur. Dans ce cas, la règle n'est pas appliquée aux requêtes DNS de ce client.
$client=~value1
Les noms de client contiennent généralement des espaces ou d'autres caractères spéciaux, c'est pourquoi vous devez placer le nom entre guillemets. Les guillemets ASCII simples et doubles sont pris en charge. Utilisez la barre oblique inverse (\
) pour échapper les guillemets ("
et '
), les virgules (,
) et les barres verticales (|
).
REMARQUE : Lorsque vous excluez un client, vous devez placer ~
en dehors des guillemets.
Exemples :
@@||*^$client=127.0.0.1
: débloquer tout pour localhost.||example.org^$client='Frank\'s laptop'
: bloqueexample.org
pour le client nomméFrank's laptop
uniquement. Notez que les guillemets ('
) dans le nom doivent être échappés.||example.org^$client=~'Mary\'s\, John\'s\, and Boris\'s laptops'
: blocexample.org
pour tout le monde sauf le client nomméMary's, John's, and Boris's laptops
. Notez que la virgule (,
) doit également être échappée.||example.org^$client=~Mom|~Dad|Kids
: bloquerexemple.org
pourKids
, mais pas pourMom
etDad
. Cet exemple montre comment spécifier plusieurs clients dans une règle.||example.org^$client=192.168.0.0/24
: bloquerexample.org
pour tous les clients dont les adresses IP sont comprises entre192.168.0.0
et192.168.0.255
.
denyallow
Vous pouvez utiliser le modificateur denyallow
pour exclure des domaines de la règle de blocage. Pour ajouter plusieurs domaines à une règle, utilisez le |
caractère comme séparateur.
La syntaxe est :
$denyallow=domain1|domain2|...
Ce modificateur permet d'éviter de créer des règles d'exception inutiles quand notre règle de blocage couvre trop de domaines. Vous voudrez peut-être tout bloquer sauf quelques domaines TLD. Vous pouvez utiliser l'approche standard, c'est-à-dire des règles comme celle-ci :
! Bloquer tout.
/.*/
! Débloquer quelques TLD.
@@||com^
@@||net^
Le problème avec cette approche est que de cette façon, vous débloquerez également les domaines de suivi situés sur ces TLD (c'est-à-dire google-analytics.com
). Voici comment résoudre ce problème avec denyallow
:
*$denyallow=com|net
Exemples :
*$denyallow=com|net
: bloque tout sauf*.com
et*.net
.@@*$denyallow=com|net
: débloque tout sauf*.com
et*.net
.||example.org^$denyallow=sub.example.org
. bloqueexample.org
et*.example.org
mais ne bloque passub.example.org
.
dnstype
Le modificateur dnstype
permet de spécifier le type de requête ou de réponse DNS sur lequel cette règle sera déclenchée.
La syntaxe est :
$dnstype=value1|value2|...
$dnstype=~value1|~value2|~...
Les noms des types ne sont pas sensibles à la casse, mais sont validés par rapport à un ensemble de types d'enregistrements de ressources DNS (RR) réels.
Ne combinez pas les règles d'exclusion avec celles d'inclusion. Ceci :
$dnstype=~value1|value2
est équivalent à ceci :
$dnstype=value2
Exemples :
||example.org^$dnstype=AAAA
: bloque les requêtes DNS pour les adresses IPv6 deexample.org
.||example.org^$dnstype=~A|~CNAME
: n'autorise que les requêtes DNS du typeA
etCNAME
pourexample.org
, et bloque le reste.
ATTENTION : Avant la version v0.108.0, AdGuard Home utilisait le type de requête pour filtrer les enregistrements de réponse, par opposition au type de l'enregistrement de réponse lui-même. Cela posait des problèmes, puisque dans ce cas-là vous ne pouviez pas écrire de règles autorisant certains enregistrements CNAME
dans les réponses aux requêtes A
et AAAA
. Dans v0.108.0 ce comportement a été modifié, alors maintenant ceci :
||canon.example.com^$dnstype=~CNAME
permet d'éviter le filtrage de la réponse suivante :
REPONSES :
-> example.com
canonical name = canon.example.com.
ttl = 60
-> canon.example.com
internet address = 1.2.3.4
ttl = 60
dnsrewrite
Le modificateur de réponse dnsrewrite
permet de remplacer le contenu de la réponse à la requête DNS pour les hôtes correspondants. Tenez compte que ce modificateur dans AdGuard Home fonctionne dans toutes les règles, mais dans AdGuard DNS Privé - uniquement dans les règles personnalisées.
Les règles avec le modificateur de réponse dnsrewrite
ont une priorité plus élevée que les autres règles dans AdGuard Home.
La syntaxe abrégée est la suivante :
$dnsrewrite=1.2.3.4
$dnsrewrite=abcd::1234
$dnsrewrite=example.net
$dnsrewrite=REFUSED
Les mots clés DOIVENT être en majuscules (par exemple NOERROR
). Les réécritures de mots-clés ont priorité sur les autres et donneront une réponse vide avec un code de réponse approprié.
La syntaxe complète est de la forme RCODE;RRTYPE;VALUE
:
$dnsrewrite=NOERROR;A;1.2.3.4
$dnsrewrite=NOERROR;AAAA;abcd::1234
$dnsrewrite=NOERROR;CNAME;example.net
$dnsrewrite=REFUSED;;
Le modificateur $dnsrewrite
avec le code de réponse NOERROR
peut également avoir des champs RRTYPE
et VALUE
vides.
Le CNAME
est spécial, car AdGuard Home résoudra l'hôte et ajoutera ses informations à la réponse. Autrement dit, si example.net
a l'IP 1.2.3.4
et l'utilisateur a ceci dans ses règles de filtrage :
||example.com^$dnsrewrite=example.net
! Soit :
||example.com^$dnsrewrite=NOERROR;CNAME;example.net
alors la réponse sera de cette sorte :
nslookup example.com my.adguard.local
Serveur : my.adguard.local
Adresse : 127.0.0.1#53
Réponse non officielle :
exemple.com canonical name = exemple.net.
Nom : example.net
Adresse : 1.2.3.4
Ensuite, la réécriture CNAME
. Après cela, les valeurs de tous les autres enregistrements sont additionnées en une seule réponse, donc ceci :
||example.com^$dnsrewrite=NOERROR;A;1.2.3.4
||example.com^$dnsrewrite=NOERROR;A;1.2.3.5
entraînera une réponse avec deux enregistrements A
.
Types de RR actuellement pris en charge avec des exemples :
||4.3.2.1.in-addr.arpa^$dnsrewrite=NOERROR;PTR;example.net.
ajoute un enregistrementPTR
pour le DNS inverse. Les requêtes DNS inversées pour1.2.3.4
au serveur DNS donnerontexample.net
.ATTENTION : l'adresse IP DOIT être dans l'ordre inverse. Voir RFC 1035.
||example.com^$dnsrewrite=NOERROR;A;1.2.3.4
ajoute un enregistrementA
avec la valeur1.2.3.4
.||example.com^$dnsrewrite=NOERROR;AAAA;abcd::1234
ajoute un enregistrementAAAA
avec la valeurabcd::1234
.||example.com^$dnsrewrite=NOERROR;CNAME;example.org
ajoute un enregistrementCNAME
. Voir l'explication ci-dessus.||example.com^$dnsrewrite=NOERROR;HTTPS;32 example.com alpn=h3
ajoute un enregistrementHTTPS
. Seul un sous-ensemble de valeurs de paramètres est pris en charge : les valeurs doivent êtrecontiguës à
et, lorsqu'uneliste de valeurs
estattendue
, une seule valeur est actuellement prise en charge :ipv4hint=127.0.0.1 // Pris en charge.
ipv4hint="127.0.0.1" // Non pris en charge.
ipv4hint=127.0.0.1,127.0.0.2 // Non pris en charge.
ipv4hint="127.0.0.1,127.0.0.2" // Non pris en charge.Cela changera à l’avenir.
||example.com^$dnsrewrite=NOERROR;MX;32 example.mail
ajoute un enregistrementMX
avec la valeur de priorité32
et la valeur d'échangeexample.mail
.||example.com^$dnsrewrite=NOERROR;SVCB;32 example.com alpn=h3
ajoute une valeurSVCB
. Voir l'exempleHTTPS
ci-dessus.||example.com^$dnsrewrite=NOERROR;TXT;hello_world
ajoute un enregistrementTXT
avec la valeurhello_world
.||_svctype._tcp.example.com^$dnsrewrite=NOERROR;SRV;10 60 8080 example.com
ajoute un enregistrementSRV
avec la valeur de priorité10
, la valeur de pondération60
, le port8080
et la valeur cibleexample.com
.||example.com^$dnsrewrite=NXDOMAIN;;
répond par un codeNXDOMAIN
.$dnstype=AAAA,denyallow=example.org,dnsrewrite=NOERROR ;;
fait retour avec des réponsesNOERROR
vides pour toutes requêtesAAA
sauf celles pourexample.org
.
Les règles d'exception suppriment une ou toutes les règles :
@@||example.com^$dnsrewrite
supprime toutes les règles de réécriture DNS.@@||example.com^$dnsrewrite=1.2.3.4
supprime la règle de réécriture DNS qui ajoute un enregistrementA
avec la valeur1.2.3.4
.
important
Le modificateur important
appliqué à une règle augmente sa priorité sur toute autre règle sans le modificateur. Même sur les règles d'exceptions de base.
Exemples :
Dans cet exemple :
||exemple.org^$important
@@||exemple.org^||example.org^$important
bloquera toutes les requêtes vers*.example.org
malgré la règle d'exception.Dans cet exemple :
||example.org^$important
@@||example.org^$importantla règle d'exception comporte également le modificateur
important
, donc ça doit marcher.
badfilter
Les règles avec le modificateur badfilter
désactivent les autres règles de base auxquelles elles se réfèrent. Cela signifie que le texte de la règle désactivée doit correspondre au texte de la règle badfilter
(sans le modificateur badfilter
).
Exemples :
||example.com$badfilter
désactive||example.com
.@@||example.org^$badfilter
désactive@@||example.org^
.REMARQUE : Le modificateur
badfilter
ne fonctionne pas actuellement avec les règles de style/etc/hosts
.127.0.0.1 example.org$badfilter
ne désactivera pas la règle d'origine127.0.0.1 example.org
.
ctag
Le modificateur ctag
ne peut être utilisé que dans AdGuard Home.
Il permet de bloquer des domaines uniquement pour des types spécifiques de balises client DNS. Vous pouvez attribuer des balises aux clients dans l'interface utilisateur AdGuard Home. À l'avenir, nous prévoyons d'attribuer automatiquement des balises en analysant le comportement de chaque client.
La syntaxe est :
$ctag=value1|value2|...
Si l'une des balises du client correspond aux valeurs ctag
, cette règle s'applique au client. La syntaxe de l'exclusion est :
$ctag=~value1|~value2|...
Si l'une des balises du client correspond aux valeurs ctag
d'exclusion, cette règle ne s'applique pas au client.
Exemples :
||example.org^$ctag=device_pc|device_phone
: bloquerexample.org
pour les clients marqués commedevice_pc
oudevice_phone
.||example.org^$ctag=~device_phone
: bloquerexample.org
pour tous les clients sauf ceux marqués commedevice_phone
.
La liste des balises autorisées :
Par type de dispositif :
device_audio
: périphériques audio.device_camera
: caméras.device_gameconsole
: consoles de jeux.device_laptop
: ordinateurs portables.device_nas
: NAS (Stockages en réseau).device_pc
: PCs.device_phone
: téléphones.device_printer
: imprimantes.device_securityalarm
: alarmes de sécurité.device_tablet
: tablettes.device_tv
: téléviseurs.device_other
: autres appareils.
Par système d'exploitation :
os_android
: Android.os_ios
: iOS.os_linux
: Linux.os_macos
: macOS.os_windows
: Windows.os_other
: autres systèmes d'exploitation.
Par groupe d'utilisateurs :
user_admin
: administrateurs.user_regular
: utilisateurs réguliers.user_child
: enfants.
/etc/hosts
-Style Syntaxe
Pour chaque hôte, une seule ligne doit être présente avec les informations suivantes :
IP_address canonical_hostname [aliases...]
Les champs des entrées sont séparés par un nombre d'espaces ou de tabulations. Le texte commençant par le caractère #
jusqu'à la fin de la ligne est un commentaire et est ignoré.
Les noms d'hôte ne peuvent contenir que des caractères alphanumériques, des signes tiret moins (-
) et des points (.
). Ils doivent commencer par un caractère alphabétique et se terminer par un caractère alphanumérique. Les alias facultatifs permettent des changements de nom, des orthographes alternatives, des noms d'hôte plus courts ou des noms d'hôte génériques (par exemple, localhost
).
Exemple :
# Ceci est un commentaire
127.0.0.1 exemple.org example.info
127.0.0.1 exemple.com
127.0.0.1 exemple.net # ceci est aussi un commentaire
Dans AdGuard Home, les adresses IP sont utilisées pour répondre aux requêtes DNS pour ces domaines. Dans AdGuard DNS Privé, ces adresses sont tout simplement bloquées.
Syntaxe pour les domaines uniquement
Une simple liste de noms de domaine, un nom par ligne.
Exemple :
# Ceci est un commentaire
exemple.com
exemple.org
exemple.net # ceci est aussi un commentaire
Si une chaîne n'est pas un domaine valide (par exemple *.example.org
), AdGuard Home la considérera comme une règle du style Adblock.
Compilateur de listes d'hôtes
Si vous maintenez une liste de blocage et vous utilisez des sources différentes, le Compilateur des listes d'hôtes peut vous être utile. C'est un outil simple qui facilite la compilation d'une liste de blocage d'hôtes compatible avec AdGuard Home, AdGuard DNS Privé ou tout autre produit AdGuard comportant le filtrage DNS.
Qu'est-ce qu'il peut faire :
Compiler une liste de blocage à partir de plusieurs sources.
Exclure les règles dont vous n'avez pas besoin.
Nettoyer la liste résultante : dédupliquer, supprimer les règles non valides et compresser la liste.