Spring til hovedindhold

Syntaks for DNS-filtreringsregler

info

I denne artikel forklares, hvordan man skriver tilpassede filtreringsregler til brug i AdGuard-produkter

Hurtige links: Download AdGuard Ad Blocker, Hent AdGuard Home, Prøv AdGuard DNS

Introduktion​

AdGuard DNS-filtreringsregelsyntaks kan bruges til at gøre regler mere fleksible, så de kan blokere indhold iht. personlige præferencer. AdGuard DNS-filtreringsregelsyntaks kan bruges i forskellige AdGuard-produkter, såsom AdGuard Home, AdGuard DNS, AdGuard til Windows/Mac/Android.

Der er tre forskellige tilgange til at skrive værtsblokeringslister:

  • Adblock-syntakstype: Den moderne tilgang til at skrive filtreringsregler baseret på brug af en delmænge af Adblock-regelsyntaksen. På denne måde er blokeringslister kompatible med browser-adblockere.

  • /etc/hosts syntaks: Den gamle, gennemprøvede tilgang, der bruger samme værtsfilsyntakser som operativsystemerne.

  • Syntaks kun til domæner: En simpel liste over domænenavne.

Opretter man en sortliste, anbefales brug af Adblock-syntakstypen. Den har et par vigtige fordele ift. den gamle syntakstype:

  • Blokeringslistestørrelse. Ved at bruge mønstertilpasning kan man have én enkelt regel i stedet for hundredvis af /etc/hosts-poster.

  • Kompatibilitet. Blokeringslisten vil være kompatibel med browser-adblockere, og regler kan nemmere deles med en browser-filtreringsliste.

  • Udvidelsesmuligheder. I det seneste årti har Adblock-syntakstypen udviklet sig meget, og vi ser ingen grund til ikke at udvide den yderligere og tilbyde flere funktioner til netværksniveau-blockere.

Vedligeholder man enten en sortliste af typen /etc/hosts eller flere filtreringslister (uanset type), tilbyder vi et værktøj til kompilering af sortlister. Vi har kaldt den Hostlist-kompiler og bruger den selv til at oprette AdGuard DNS-filtre.

Basiseksempler​

  • ||eksempel.org^: blokér domæneadgang for eksempel.org og alle dets underdomæner, f.eks. www.eksempel.org.

  • ||eksempel.org^: Afblokér domæneadgang til eksempel.org og alle dets underdomæner.

  • 1.2.3.4 eksempel.org: (Bemærk, gammel /etc/hosts-syntakstype) i AdGuard Home, svar med 1.2.3.4 på forespørgsler for eksempel.org-domænet, men ikke dets underdomæner. Blokér i Private AdGuard DNS adgangen til eksempel.org. www.eksempel.org forbliver tilladt.

    I AdGuard Home er brug af den uspecificerede IP-adresse (0.0.0.0) eller en lokal adresse (127.0.0.1 o.lign.) for en vært essentielt det samme som at blokere denne vært.

    # Returnerer IP-adressen 1.2.3.4 for eksempel.org.
    1.2.3.4 eksempel.org
    # Blokerer eksempel.org ved at svare med 0.0.0.0.
    0.0.0.0 eksempel.org

  • eksempel.org: En simpel domæneregel. Blokerer eksempel.org-domænet, men ikke dets underdomæner. www.eksempel.org forbliver tilladt.

  • ! Her angives en kommentar og # Også en kommentar: Kommentarer.

  • /REGEX/: Blokér adgang til domæner matchende det angivne regulære udtryk.

Adblock-syntakstype​

Dette er en delmængde af den traditionelle Adblock-syntakstype brugt af webbrowser-adblockere.

     regel = ["@@"] mønster [ "$" modifikatorer ]
modifikatorer = [modifikator0, modifikator1[, ...[, modifikatorN]]]

  • mønster: Værtsnavnmasken. Alle værtsnavne matches mod denne maske. Mønsteret kan også indeholde specialtegn, som beskrevet nedenfor.

  • @@: den markør, der bruges i undtagelsesreglerne. Ønskes filtrering for de matchende værtsnavne deaktiveret, så start reglen med denne markør.

  • modifikatorer: Parametre, som tydeliggør reglen. De kan begrænse reglens udstrækning eller endda helt ændre måden, den fungerer på.

Specialtegn​

  • *: jokertegnet. Det bruges til at repræsentere et hvilket som helst tegn. Dette kan også være en tom streng eller en streng af enhver længde.

  • ||: Matcher begyndelsen af et værtsnavn, inkl. ethvert underdomæne. F.eks. så matcher ||eksempel.org eksempel.org og test.eksempel.org, men ikke testeksempel.org.

  • ^: separatortegnet. Ulig browser-adblocking, er der intet at adskille/opdele i et værtsnavn, så det eneste formål med dette tegn er at markere slutningen på værtsnavnet.

  • |: En markør for begyndelsen eller slutningen på værtsnavnet. Værdien afhænger af tegnplaceringen i masken. F.eks. svarer reglen emple.org| til eksempel.org, men ikke til eksempel.org.com. |eksempe korresponderer med eksempel.org, men ikke med test.eksempel.

Regulære udtryk​

Ønskes endnu mere fleksibilitet ved regeludarbejdelse, kan regulære udtryk bruges i stedet for standarden, den forenklede matchningssyntaks. Ønskes et regulært udtryk anvendt, skal mønsteret se således ud:

mønster = "/" regexp "/"

Eksempler:

  • /eksempel.*/ blokerer værter matchende eksempel.*-regexp'et.

  • @@/eksempel.*/$important afblokerer værter matchende eksempel.*-regexp'et. Bemærk, at denne regel også forudsætter important-modifikatoren.

Kommentarer​

Enhver linje startende med et udråbs- eller et hash-tegn udgør en kommentar og ignoreres derfor af filtreringsmotoren. En kommentarer beskriver, hvad en regel gør, og den placeres normalt over reglen.

Eksempel:

! Dette er en kommentar.
# Dette er også en kommentar.

Regelmodifikatorer​

Adfærden for en regel kan ændres ved at tilføje modifikatorer. Modifikatorer skal placeres i slutningen af reglen efter $-tegnet og adskilles med kommaer.

Eksempler:


  • ||eksempel.org^ er det matchende mønster. $ er afgrænsningstegnet, der signalerer, at resten af reglen er modifikatorer. "important" er modifikationen.

  • Man ønsker måske at bruge flere modifikatorer i en regel. Adskil dem i så fald med kommaer:

    ||eksempel.org^$client=127.0.0.1,dnstype=A

    ||eksempel.org^ er det matchende mønster. $ er afgrænsningstegnet, der signalerer, at resten af reglen er modifikatorer. client=127.0.0.1 er klient-modifikatoren med dens værdi, 127.0.0.1. , er afgrænsningen mellem modifikatorer. Til sidst, er dnstype=A dnstype-modifikatoren med sin værdi A.

BEMÆRK: Indeholder en regel en modifikator, der ikke er angivet i dette dokument, skal hele regel ignoreres. På denne måde undgås falske positiver, når folk forsøger at bruge umodificerede browser-adblockingfilterlister, såsom EasyList eller EasyPrivacy.

client​

Modifikatoren client muliggør at angive de klienter, for hvilke reglen anvendes. Der er to hovedmåder, en klient kan identificere på:

  • Via deres IP-adresse eller CIDR-præfiks. Denne måde fungerer for alle slags klienter.

  • Via deres navn. Denne måde fungerer kun for vedvarende klienter (i AdGuard Home) og enheder (i Private AdGuard DNS), som man manuelt har tilføjet.

    BEMÆRK: I AdGuard Home understøttes ClientID'er ikke pt., kun navne. Har man tilføjet en klient med navnet "Min Klient" og klient-id min-klient, så bogstavér modifikatoren $client='Min Klient' i modsætning til $client=min-klient.

Syntaksen er:

$client=værdi1|værdi2|...

Klienter kan også undtages ved at tilføje et ~-tegn før værdien. Reglen anvendes så ikke på DNS-forespørgsler fra denne klient.

$client=~værdi1

Klientnavne indeholder normalt mellemrum eller andre specialtegn, hvorfor navnet bør sætte i anførselstegn. Både enkelte og dobbelte ASCII-anførselstegn understøttes. Brug omvendt skråstreg (\) til at escape anførselstegnene (" og '), kommaer (,) samt pipes (|).

BEMÆRK: Når en klient undtages, skal man placere ~ udenfor anførselstegnene.

Eksempler:

  • @@||*^$client=127.0.0.1: Afblokér alt for localhost.

  • ||eksempel.org^$client='Frank\'s bærbare': Blokér kun eksempel.org for klienten med navnet Frank's bærbare. Bemærk, at anførselstegnet (') i navnet skal escapes.

  • ||eksmpel.org^$client=~'Mary\'s\, John\'s\ og Boris\'s bærbarer': Blokér eksmpel.org for alle undtagen for klientnavnene Mary's, John's og Boris' bærbarer. Bemærk, at komma (,) også skal escapes.

  • ||eksempel.org^$client=~Mor|~Far|Børn: Blokér eksempel.org for Børn, men ikke for Mor og Far. Dette eksempel viser, hvordan man angiver flere klienter i én regel.

  • ||eksempel.org^$client=192.168.0.0/24: Blokér eksempel.org for alle klienter med IP-adresser i området fra 192.168.0.0 til 192.168.0.255.

denyallow​

Modifikatoren denyallow kan bruges til at undtage domæner fra blokeringsreglen. Benyt |-tegnet som separator, når flere domæner føjes til én regel.

Syntaksen er:

$denyallow=domæne1|domæne2|...

Denne modifikator muliggør at undgå at oprette unødvendige undtagelsesregler, når vores blokeringsregel dækker for mange domæner. Man ønsker måske at blokere alt undtagen nogle få TLD-domæner. Man kan bruge standardmetoden, dvs. regler såsom denne:

! Blokér alt.
/.*/

! Afblokér et par TLD'er.
@@||com^
@@||net^

Problemet med denne tilgang er, at man på denne måde også afblokerer sporingsdomæner, som findes på disse TLD'er (f.eks. google-analytics.com). Sådan løses dette med denyallow:

*$denyallow=com|net

Eksempler:

  • *$denyallow=com|net: Blokér alt, undtagen *.com og *.net.

  • @@*$denyallow=com|net: Afblokér alt, undtagen *.com og *.net.

  • ||eksempel.org^$denyallow=under.eksempel.org. blokér eksempel.org og *.eksempel.org, men blokér ikke under.eksempel.org.

dnstype​

Modifikatoren dnstype muliggør angivelse af DNS-forespørgsel eller svartype, for hvilken reglen udløses.

Syntaksen er:

$dnstype=værdi1|værdi2|...
$dnstype=~værdi1|~værdi2|~...

Typenavnene er minuskel/majuskel ufølsomme, men valideres mod et sæt reelle DNS-ressourceposttyper (RR).

Kombinér ikke undtagelsesregler med inklusionsregler. Dette:

$dnstype=~værdi1|~værdi2

svarer til dette:

$dnstype=værdi2

Eksempler:

  • ||eksemple.org^$dnstype=AAAA: Blokér DNS-forespørgsler for IPv6-adresserne på eksemple.org.

  • ||eksemple.org^$dnstype=~A|~CNAME: Tillad kun A og CNAME DNS-forespørgsler for eksemple.org, blokér resten.

BEMÆRK: Før version v0.108.0, brugte AdGuard Home forespørgselstypen til at filtrere svarposterne, i modsætning til selve svarposttypen. Det gav problemer, da det betød, at der ikke kunne skrives regler, som ville tillade visse CNAME-poster i svar i A- og AAAA-forespørgsler. I v0.108.0 blev denne adfærd ændret, så den nu er:

||canon.eksempel.com^$dnstype=~CNAME

giver mulighed for at undgå filtrering af det flg. svar:

SVAR:
->  eksempel.com
    kanonisk navn = canon.eksempel.com.
    ttl = 60
->  canon.eksempel.com
    internetadresse = 1.2.3.4
    ttl = 60

dnsrewrite​

Svarmodifikatoren dnsrewrite muliggør at erstatte indholdet af svaret på DNS-forespørgslen for de matchende værter. Bemærk, at denne modifikator i AdGuard Home fungerer i alle regler, men kun i tilpassede regler i Private AdGuard DNS.

Regler med svarmodifikatoren dnsrewrite har højere prioritet end øvrige regler i AdGuard Home og AdGuard DNS.

Svar på alle forespørgsler om en vært matchende en dnsrewrite-regel bliver erstattet. Svarsafsnittet i erstatningssvaret vil kun indeholde RR'er matchende forespørgslens forespørgselstype og muligvis CNAME RR'er. Bemærk, at dette betyder, at svar på nogle forespørgsler kan blive tomme (NODATA), hvis værten matcher en dnsrewrite-regel.

Stenografisyntaksen er:

$dnsrewrite=1.2.3.4
$dnsrewrite=abcd::1234
$dnsrewrite=eksempel.net
$dnsrewrite=REFUSED

Nøgleordene SKAL være majuskler (f.eks. NOERROR). Nøgleordsomskrivninger har forrang over de øvrige og vil resultere i et tomt svar med en passende svarkode.

Den fulde syntaksform er RCODE;RRTYPE;VALUE:

$dnsrewrite=NOERROR;A;1.2.3.4
$dnsrewrite=NOERROR;AAAA;abcd::1234
$dnsrewrite=NOERROR;CNAME;eksempel.net
$dnsrewrite=REFUSED;;

Modifikatoren $dnsrewrite med NOERROR-svarkoden kan også have tomme RRTYPE- og VALUE-felter.

CNAME er speciel, idet AdGuard Home vil opløse værten og føje dens oplysninger til svaret. Dvs., hvis eksempel.net har IP 1.2.3.4, og brugeren har dette i sine filterregler:

||eksempel.com^$dnsrewrite=eksempel.net
! Eller:
||eksempel.com^$dnsrewrite=FEJL;CNAME;eksempel.net

så vil svaret være noget i retning af:

nslookup eksempel.com my.adguard.local
Server: my.adguard.local
Adresse: 127.0.0.1#53

Ikke-autoritativt svar:
eksempel.com kanonisk navn = eksempel.net.
Navn: eksempel.net
Adresse: 1.2.3.4

Dernæst CNAME-omskrivningen. Derefter opsummeres alle andre posters værdier til ét svar, så dette:

||eksempel.com^$dnsrewrite=NOERROR;A;1.2.3.4
||eksempel.dk^$dnsrewrite=NOERROR;A;1.2.3.5

vil resultere i et svar med to A-poster.

Aktuelt understøttede RR-typer med eksempler:

  • ||4.3.2.1.in-addr.arpa^$dnsrewrite=NOERROR;PTR;eksempel.net. tilføjer en PTR-post for reverse DNS. Reverse DNS-forespørgsler for 1.2.3.4 til DNS-serveren vil resultere i eksempel.net.

    BEMÆRK: IP'en SKAL være i omvendt rækkefølge. Se RFC 1035.

  • ||eksempel.com^$dnsrewrite=NOERROR;A;1.2.3.4 tilføjer en A-post med værdien 1.2.3.4.

  • ||eksempel.com^$dnsrewrite=NOERROR;AAAA;abcd::1234 tilføjer en AAAA-post med værdien abcd::1234.

  • ||eksempel.com^$dnsrewrite=NOERROR;CNAME;eksempel.org tilføjer en CNAME-post. Se forklaring ovenfor.

  • ||eksempel.com^$dnsrewrite=NOERROR;HTTPS;32 eksempel.com alpn=h3 tilføjer en HTTPS-post. Kun et undersæt af parameterværdier understøttes: Værdier skal være sammenhængende, og hvor en værdiliste forventes, understøttes pt. kun én værdi:

    ipv4hint=127.0.0.1             // Understøttet.
    ipv4hint="127.0.0.1"           // Uunderstøttet.
    ipv4hint=127.0.0.1,127.0.0.2   // Uunderstøttet.
    ipv4hint="127.0.0.1,127.0.0.2" // Uunderstøttet.

    Dette vil blive ændret fremtiden.

  • ||eksempel.com^$dnsrewrite=NOERROR;MX;32 eksempel.mail tilføjer en MX-post med forrangsværdien 32 og udvekslingsværdien eksempel.mail.

  • ||eksempel.com^$dnsrewrite=NOERROR;SVCB;32 eksempel.com alpn=h3 tilføjer en SVCB-value. Se HTTPS-eksemplet ovenfor.

  • ||eksempel.com^$dnsrewrite=NOERROR;TXT;hallo_verden tilføjer en TXT-post med værdien hallo_verden.

  • ||_svctype._tcp.eksempel.com^$dnsrewrite=NOERROR;SRV;10 60 8080 eksempel.com tilføjer en SRV-post med prioritetsværdien 10, vægtværdien 60, porten8080 og målværdien eksempel.com.

  • ||eksempel.com^$dnsrewrite=NXDOMAIN;; svarer med en NXDOMAIN-kode.

  • $dnstype=AAAA,denyallow=eksempel.org,dnsrewrite=NOERROR;; besvares med tomme NOERROR-svar for alle AAAA-forespørgsler, undtagen for dem indeholdende eksempel.org.

Undtagelsesregler afblokerer én eller alle regler:

  • @@||eksempel.com^$dnsrewrite fjerner alle DNS rewrite-regler.

  • @@||eksempel.com^$dnsrewrite=1.2.3.4 fjerner DNS rewrite-reglen, der tilføjer en A-post med værdien 1.2.3.4.

info

Vedligeholder man en blokeringsliste inkluderet i AdGuard DNS og AdGuard Home (dvs. inkluderet i HostlistsRegistry), vil $dnsrewrite-regler automatisk blive filtreret ud. Er disse regler nødvendige for blokeringslisten, bedes man anmode om tilladelse ved at åbn en ny problematik i HostlistsRegistry-repo'et.

important​

Modifikatoren important, anvendt på en regel, øger dennes prioritet over alle øvrige regler uden modifikatoren. Selv over basisundtagelsesregler.

Eksempler:

  • I dette eksempel:

    ||eksempel.org^$important
    @@||eksempel.org^

    ||eksempel.org^$important blokerer alle forespørgsler til *.eksempel.org på trods af undtagelsesreglen.

  • I dette eksempel:

    ||eksempel.org^$important
    @@||eksempel.org^$important

    undtagelsesreglen har også vigtige-modifikator, så den vil virke.

badfilter​

Reglerne med modifikatoren badfilter deaktiverer andre basisregler, til hvilke de henviser. Det betyder, at teksten i den deaktiverede regel bør matche teksten i reglen badfilter (uden modifikatoren badfilter).

Eksempler:

  • ||eksempel.com$badfilter dealtiverer ||eksempel.com.

  • @@||eksempel.org^$badfilter deaktiverer @@||eksempel.org^.

    BEMÆRK: badfilter-modifikatoren fungerer ikke pt. med /etc/hosts-regeltyper. 127.0.0.1 eksempel.org$badfilter deaktiverer ikke den oprindelige 127.0.0.1 eksempel.org-regel.

ctag​

Modifikatoren ctag kan kun bruges i AdGuard Home.

Det muliggør blokering kun af domæner til bestemte typer af DNS-klienttags. Tags kan tildeles klienter via AdGuard Home-UI'en. Fremadrettet er det planen at tildele tags automatisk ved at analysere hver klients adfærd.

Syntaksen er:

$ctag=værdi1|værdi2|...

Matcher en af klienternes tags ctag-værdierne, gælder denne regel for klienten. Syntaksen for undtagelse er:

$ctag=~value1|~value2|...

Matcher en af klienternes tags undtagelses ctag-værdierne, gælder denne regel ikke for klienten.

Eksempler:

  • ||eksempel.org^$ctag=device_pc|device_phone: Blokerer eksempel.org for klienter tagget som device_pc eller device_phone.

  • ||eksempel.org^$ctag=~device_phone: Blokerer eksempel.org for alle klienter, undtagen for den tagget som device_phone.

Oversigt over gyldige tags:

  • Efter enhedstype:

    • device_audio: Lydenheder.
    • device_camera: Kameraer.
    • device_gameconsole: Spillekonsoller.
    • device_laptop: Bærbare.
    • device_nas: NAS (netværkstilsluttede lagerenheder).
    • device_pc: PC'er.
    • device_phone: Mobiler.
    • device_printer: Printere.
    • device_securityalarm: Sikkerhedsalarmer.
    • device_tablet: Tablets.
    • device_tv: TV.
    • device_other: Øvrige enhedstyper.

  • Efter styresystem:

    • os_android: Android.
    • os_ios: iOS.
    • os_linux: Linux.
    • os_macos: macOS.
    • os_windows: Windows.
    • os_other: Øvrige OS'er.

  • Efter brugergruppe:

    • user_admin: Administratorer.
    • user_regular: Almindelige brugere.
    • user_child: Børn.

/etc/hosts-syntakstype​

For hver vært skal én enkelt linje fremgå med flg. oplysninger:

IP_adresse kanonisk_værtsnavn [aliases...]

Indtastningsfelter adskilles med et vilkårligt antal mellemrum eller tabulatortegn. Tekst efter #-tegnet og indtil slutningen af linjen udgør kommentartekst og ignoreres.

Værtsnavne må kun indeholde alfanumeriske tegn, bindestreg-/minus-tegn (-) samt punktummer (.). De skal både starte og slutte med et alfabetisk tegn. Valgfrie aliaser muliggør navneændringer, alternative stavemåder og kortere eller generiske værtsnavne (f.eks. localhost).

Eksempel:

# Dette er en kommentar
127.0.0.1 eksempel.org eksempel.info
127.0.0.1 eksempel.com
127.0.0.1 eksempel.net # dette er også en kommentar

I AdGuard Home bruges IP-adresserne til at besvare DNS-forespørgsler for disse domæner. I Private AdGuard DNS blokeres disse adresser simpelthen.

Domænespecifik syntaks​

En simpel liste over domænenavne, ét navn pr. linje.

Eksempel:

# Dette er en kommentar
eksempel.com
eksempel.org
eksempel.net # dette er også en kommentar

Er en streng ikke er et gyldigt domæne (f.eks. *.eksempel.org), betragter AdGuard Home den som en Adblock-syntakstype regel.

Hostliste-kompiler​

Vedligeholder man en blokeringsliste og bruger forskellige kilder heri, kan Hostlist-kompileren være nyttig. Det er et simpelt værktøj, der gør det nemmere at kompilere en værtsblokeringsliste, der er kompatibel med AdGuard Home, Private AdGuard DNS eller ethvert andet AdGuard-produkt med DNS-filtrering.

Hvad den er i stand til:

  1. Kompiler én enkelt blokeringsliste fra flere kilder.

  2. Udelukke de regler, man ikke behøver.

  3. Oprense den resulterende liste: Fjerne dubletter og ugyldige regler, samt komprimere listen.