Sintaxis de las reglas de filtrado DNS
Aquí te mostramos cómo escribir reglas de filtrado DNS personalizadas para uso en productos AdGuard
Enlaces rápidos: Descargar el Bloqueador de Anuncios AdGuard, Obtener AdGuard Home, Probar AdGuard DNS
Introducción
Puedes usar la sintaxis de las reglas de filtrado DNS de AdGuard para hacer que las reglas sean más flexibles, de esa manera pueden bloquear contenidos según tus preferencias. La sintaxis de las reglas de filtrado DNS de AdGuard puede ser usada en diferentes productos de AdGuard como AdGuard Home, AdGuard DNS y AdGuard para Windows/Mac/Android.
Hay tres diferentes enfoques para escribir listas de bloqueo de hosts:
-
Adblock-style syntax: the modern approach to writing filtering rules based on using a subset of the Adblock-style rule syntax. De esta manera, las listas de bloqueo creadas son compatibles con las de los bloqueadores de anuncios para navegador.
-
/etc/hostsSintaxis: el enfoque antiguo y probado, que usa la misma sintaxis que los sistemas operativos usan para sus archivos de hosts. -
Sintaxis de dominios: una simple lista de nombres de dominio.
If you are creating a blocklist, we recommend using the Adblock-style syntax. Esta sintaxis posee algunas ventajas importantes respecto a la sintaxis antigua:
-
Tamaño de las listas de bloqueo. El uso de comparación de patrones le permite tener una sola regla en lugar de cientos de entradas
/etc/hosts. -
Compatibilidad. Su lista de bloqueo será compatible con los bloqueadores de anuncios para navegador, y será más fácil compartir reglas con una lista de filtros de navegador.
-
Extensibilidad. Durante la última década, la sintaxis de estilo Adblock ha evolucionado enormemente, y no vemos por qué no extenderla aún más y proporcionar funciones adicionales para los bloqueadores de toda la red.
If you’re maintaining either a /etc/hosts-style blocklist or multiple filtering lists (regardless of type), we provide a tool for blocklist compilation. We named it Hostlist compiler and we use it ourselves to create AdGuard DNS filter.
Basic examples
-
||example.org^: bloquea el acceso al dominioexample.orgy todos sus subdominios, comowww.example.org. -
@@||example.org^: desbloquea el acceso al dominioexample.orgy todos sus subdominios. -
1.2.3.4 example.org: (atención, sintaxis estilo/etc/hostsantiguo) en AdGuard Home, el programa responde con1.2.3.4a las consultas para el dominioexample.org, pero no a sus subdominios. En el DNS privado de AdGuard, bloquea el acceso aexample.org.www.example.orgsigue estando permitido.En AdGuard Home, usar la dirección IP no especificada (
0.0.0.0) o una dirección local (127.0.0.1y similares) para un host es básicamente lo mismo que bloquear ese host.# Devuelve la dirección IP 1.2.3.4 para example.org.1.2.3.4 example.org# Bloquea example.org respondiendo con 0.0.0.0.0.0.0.0 example.org -
example.org: una regla de dominio simple. Bloquea el dominioexample.orgpero no sus subdominios.www.example.orgsigue estando permitido. -
! Es un comentarioy# También un comentario: comentarios. -
/REGEX/: bloquea el acceso a los dominios que coincidan con la expresión regular especificada.
Adblock-style syntax
This is a subset of the traditional Adblock-style syntax which is used by browser ad blockers.
rule = ["@@"] pattern [ "$" modifiers ]
modifiers = [modifier0, modifier1[, ...[, modifierN]]]
-
pattern(patrón): la máscara del nombre de host. Cada nombre de host se compara con esta máscara. El patrón también puede contener caracteres especiales, que se describen a continuación. -
@@: el marcador que se utiliza en las reglas de excepción. Inicie su regla con este marcador si desea desactivar el filtrado para los nombres de host que coincidan. -
modifiers(modificadores): parámetros que aclaran la regla. Pueden limitar el alcance de la norma o incluso cambiar por completo su funcionamiento.
Special characters
-
*: el carácter comodín. Se utiliza para representar cualquier conjunto de caracteres. Esto también puede ser una cadena de texto vacía o una cadena de texto de cualquier longitud. -
||: coincide con el comienzo de un nombre de host, incluido cualquier subdominio. Por ejemplo,||example.orgcoincide conexample.orgytest.example.orgpero no contestexample.org. -
^: el carácter de separador. Unlike browser ad blocking, there’s nothing to separate in a hostname, so the only purpose of this character is to mark the end of the hostname. -
|: un puntero al principio o al final del nombre de host. El valor depende de la ubicación del carácter. Por ejemplo, la reglaample.org|corresponde aexample.orgpero no aexample.org.com.|examplecorresponde aexample.orgpero no atest.example.
Regular expressions
If you want even more flexibility in making rules, you can use regular expressions instead of the default simplified matching syntax. Si desea utilizar una expresión regular, el patrón debe verse así:
pattern = "/" regexp "/"
Ejemplos:
-
/example.*/bloqueará los hosts que coincidan con la regexpexample.*. -
@@/example.*/$importantdesbloqueará los hosts que coincidan con la regexpexample.*. Tenga en cuenta que esta regla también implica el modificadorimportant(importante).
Comments
Cualquier línea que comience con un signo de exclamación o de almohadilla es un comentario y será ignorado por el motor de filtrado. Los comentarios suelen colocarse encima de las reglas y se utilizan para describir lo que hace una regla.
Ejemplo:
! Esto es un comentario.
# Esto también es un comentario.
Rule modifiers
Puedes cambiar el comportamiento de una regla agregando modificadores. Los modificadores deben situarse al final de la regla después del carácter $ y estar separados por comas.
Ejemplos:
-
||example.org^es el patrón de coincidencia.$es el delimitador, que señala que el resto de la regla son modificadores. El modificador es "importante". -
You may want to use multiple modifiers in a rule. En ese caso, sepáralos con comas:
||example.org^$client=127.0.0.1,dnstype=A||example.org^es el patrón de coincidencia.$es el delimitador, que señala que el resto de la regla son modificadores.client=127.0.0.1is theclientmodifier with its value,127.0.0.1.,is the delimiter between modifiers. And finally,dnstype=Ais thednstypemodifier with its value,A.
If a rule contains a modifier not listed in this document, the whole rule must be ignored. This way we avoid false-positives when people are trying to use unmodified browser ad blockers’ filter lists like EasyList or EasyPrivacy.
client
The client modifier can only be used in AdGuard Home and AdGuard DNS.
The client modifier allows specifying clients this rule is applied to. There are two main ways to identify a client:
-
Por su dirección IP o prefijo CIDR. Esta forma funciona para todo tipo de clientes.
-
Por su nombre. Este modo sólo funciona para los clientes persistentes (en AdGuard Home) y los dispositivos (en Private AdGuard DNS), que usted ha añadido manualmente.
noteIn AdGuard Home, ClientIDs are not currently supported, only names are. If you have added a client with the name “My Client” and ClientID
my-clientspell your modifier as$client='My Client'as opposed to$client=my-client.
The syntax is:
$client=valor1|valor2|...
You can also exclude clients by adding a ~ character before the value. In this case, the rule is not be applied to this client’s DNS requests.
$client=~valor1
Client names usually contain spaces or other special characters, which is why you should enclose the name in quotes. Both single and double ASCII quotes are supported. Use the backslash (\) to escape quotes (" and '), commas (,), and pipes (|).
When excluding a client, you must place ~ outside the quotes.
Ejemplos:
-
@@||*^$client=127.0.0.1: desbloquea todo para localhost. -
||example.org^$client="Frank\'s laptop": bloqueaexample.orgsólo para el cliente llamado"Frank\'s laptop". Ten en cuenta que las comillas (") en el nombre deben escaparse. -
||example.org^$client=~'Mary\'s\, John\'s\, and Boris\'s laptops': blockexample.orgpara todos excepto para el cliente llamadoMary's, John's, and Boris's laptops. Ten en cuenta que la coma (,) también debe escaparse. -
||example.org^$client=~Mom|~Dad|Kids: bloqueexample.orgparaKids, pero no paraMomyDad. Este ejemplo demuestra cómo especificar varios clientes en una regla. -
||example.org^$client=192.168.0.0/24: blockexample.orgpara todos los clientes con direcciones IP en el rango de192.168.0.0a192.168.0.255.
denyallow
You can use the denyallow modifier to exclude domains from the blocking rule. To add multiple domains to one rule, use the | character as a separator.
The syntax is:
$denyallow=domain1|domain2|...
This modifier allows avoiding creating unnecessary exception rules when our blocking rule covers too many domains. You may want to block everything except for a couple of TLD domains. You could use the standard approach, i.e. rules like this:
! Bloquear todo.
/.*/
! Desbloquee un par de TLD.
@@||com^
@@||net^
The problem with this approach is that this way you will also unblock tracking domains that are located on those TLDs (i.e. google-analytics.com). Here’s how to solve this with denyallow:
*$denyallow=com|net
Ejemplos:
-
*$denyallow=com|net: bloquea todo excepto*.comy*.net. -
@@*$denyallow=com|net: desbloquea todo excepto*.comy*.net. -
||example.org^$denyallow=sub.example.org: blockexample.organd*.example.org, but notsub.example.org.
dnstype
The dnstype modifier allows specifying DNS request or response type on which this rule will be triggered.
The syntax is:
$dnstype=value1|value2|...
$dnstype=~value1|~value2|~...
The names of the types are case-insensitive, but are validated against a set of actual DNS resource record (RR) types.
Do not combine exclusion rules with inclusion ones. This:
$dnstype=~value1|value2
is equivalent to this:
$dnstype=value2
Ejemplos:
-
||example.org^$dnstype=AAAA: bloquea las consultas de DNS para las direcciones IPv6 deexample.org. -
||example.org^$dnstype=~A|~CNAME: solo permite consultas DNSAyCNAMEparaexample.org, bloquea el resto.
Before version v0.108.0, AdGuard Home would use the type of the request to filter the response records, as opposed to the type of the response record itself. That caused issues, since that meant that you could not write rules that would allow certain CNAME records in responses in A and AAAA requests. In v0.108.0 that behaviour was changed, so now this:
||canon.example.com^$dnstype=~CNAME
allows you to avoid filtering of the following response:
RESPUESTAS:
-> ejemplo.com
nombre canónico = canon.ejemplo.com.
ttl = 60
-> canon.example.com
dirección de Internet = 1.2.3.4
ttl = 60
dnsrewrite
The dnsrewrite response modifier allows replacing the content of the response to the DNS request for the matching hosts. Note that this modifier in AdGuard Home works in all rules, but in Private AdGuard DNS — only in custom ones.
Rules with the dnsrewrite response modifier have higher priority than other rules in AdGuard Home and AdGuard DNS.
Responses to all requests for a host matching a dnsrewrite rule will be replaced. The answer section of the replacement response will only contain RRs that match the request’s query type and, possibly, CNAME RRs. Note that this means that responses to some requests may become empty (NODATA) if the host matches a dnsrewrite rule.
The shorthand syntax is:
$dnsrewrite=1.2.3.4
$dnsrewrite=abcd::1234
$dnsrewrite=example.net
$dnsrewrite=REFUSED
The keywords MUST be in all caps (e.g. NOERROR). Keyword rewrites take precedence over the other and will result in an empty response with an appropriate response code.
The full syntax is of the form RCODE;RRTYPE;VALUE:
$dnsrewrite=NOERROR;A;1.2.3.4
$dnsrewrite=NOERROR;AAAA;abcd::1234
$dnsrewrite=NOERROR;CNAME;example.net
$dnsrewrite=REFUSED;;
The $dnsrewrite modifier with the NOERROR response code may also has empty RRTYPE and VALUE fields.
The CNAME one is special because AdGuard Home will resolve the host and add its info to the response. That is, if example.net has IP 1.2.3.4, and the user has this in their filter rules:
||ejemplo.com^$dnsrewrite=ejemplo.net
! O:
||ejemplo.com^$dnsrewrite=NOERROR;CNAME;ejemplo.net
then the response will be something like:
nslookup example.com my.adguard.local
Server: my.adguard.local
Address: 127.0.0.1#53
Non-authoritative answer:
example.com canonical name = example.net.
Name: example.net
Address: 1.2.3.4
Next, the CNAME rewrite. After that, all other records’ values are summed as one response, so this:
||ejample.com^$dnsrewrite=NOERROR;A;1.2.3.4
||ejample.com^$dnsrewrite=NOERROR;A;1.2.3.5
will result in a response with two A records.
Currently supported RR types with examples:
-
||4.3.2.1.in-addr.arpa^$dnsrewrite=NOERROR;PTR;example.net.adds aPTRrecord for reverse DNS. Invertir solicitudes DNS para1.2.3.4al servidor DNS dará como resultadoexample.net.noteThe IP MUST be in reverse order. See RFC 1035.
-
||example.com^$dnsrewrite=NOERROR;A;1.2.3.4agrega un registroAcon el valor1.2.3.4. -
||ejample.com^$dnsrewrite=NOERROR;AAAA;abcd::1234añade un registroAAAAcon el valorabcd::1234. -
||example.com^$dnsrewrite=NOERROR;CNAME;example.orgagrega un registroCNAME. Consulta la explicación anterior. -
||example.com^$dnsrewrite=NOERROR;HTTPS;32 example.com alpn=h3agrega un registroHTTPS. Sólo se admite un subconjunto de valores de parámetros: los valores deben sercontiguosy, cuando `` seesperauna lista de valores, actualmente sólo se admite un valor:ipv4hint=127.0.0.1 // Compatible.ipv4hint="127.0.0.1" // No compatible.ipv4hint=127.0.0.1,127.0.0.2 // No compatible.ipv4hint="127.0.0.1,127.0.0.2" // No compatible.Esto cambiará en el futuro.
-
||ejample.com^$dnsrewrite=NOERROR;MX;32 example.mailañade un registroMXcon valor de precedencia32y valor de intercambioexample.mail. -
||ejemplo.com^$dnsrewrite=NOERROR;SVCB;32 ejemplo.com alpn=h3añade un valorSVCB. Consulta el ejemplo anterior deHTTPS. -
||ejample.com^$dnsrewrite=NOERROR;TXT;hello_worldañade un registroTXTcon el valorhello_world. -
||_svctype._tcp.example.com^$dnsrewrite=NOERROR;SRV;10 60 8080 example.comagrega un registroSRVcon valor de prioridad10, valor de peso60, puerto8080y destino valorejemplo.com. -
||ejemplo.com^$dnsrewrite=DOMINIONX;;responde con un códigoNXDOMAIN. -
$dnstype=AAAA,denyallow=example.org,dnsrewrite=NOERROR;;responde con un vacíoNOERRORresponde para todas las solicitudesAAAAexcepto las deexample.org.
Exception rules unblock one or all rules:
-
@@||example.com^$dnsrewriteunblocks all DNS rewrite rules. -
@@||example.com^$dnsrewrite=1.2.3.4unblocks the DNS rewrite rule that adds anArecord with the value1.2.3.4.
If you are maintaining a blocklist that is included in AdGuard DNS and AdGuard Home (i.e. included into HostlistsRegistry), $dnsrewrite rules will be automatically filtered out. If these rules are required for your blocklist, please request permission by opening a new issue in the HostlistsRegistry repo.
important
The important modifier applied to a rule increases its priority over any other rule without the modifier. Even over basic exception rules.
Ejemplos:
-
En este ejemplo:
||example.org^$important@@||example.org^||example.org^$importantbloqueará todas las solicitudes a*.example.orga pesar de la regla de excepción. -
En este ejemplo:
||example.org^$important@@||example.org^$importantla regla de excepción también tiene el modificador
importante, por lo que funcionará.
badfilter
The rules with the badfilter modifier disable other basic rules to which they refer. It means that the text of the disabled rule should match the text of the badfilter rule (without the badfilter modifier).
Ejemplos:
-
||ejemplo.com$badfilterdeshabilita||ejemplo.com. -
@@||example.org^$badfilterdeshabilita@@||example.org^.noteThe
badfiltermodifier currently doesn’t work with/etc/hosts-style rules.127.0.0.1 example.org$badfilterwill not disable the original127.0.0.1 example.orgrule.
ctag
The ctag modifier can only be used in AdGuard Home.
It allows to block domains only for specific types of DNS client tags. You can assign tags to clients in the AdGuard Home UI. In the future, we plan to assign tags automatically by analyzing the behavior of each client.
The syntax is:
$ctag=valor1|valor2|...
If one of client’s tags matches the ctag values, this rule applies to the client. The syntax for exclusion is:
$ctag=~valor1|~valor2|...
If one of client’s tags matches the exclusion ctag values, this rule doesn’t apply to the client.
Ejemplos:
-
||example.org^$ctag=device_pc|device_phone: bloqueaexample.orgpara clientes taggeados comodevice_pcodevice_phone. -
||example.org^$ctag=~device_phone:Bloquearexample.orgpara todos los clientes excepto aquellos etiquetados comodevice_phone.
The list of allowed tags:
-
Por tipo de dispositivo:
device_audio: dispositivos de audio.device_camera: cámaras.device_gameconsole: consolas de juegos.device_laptop: laptops.device_nas: NAS (Network-attached Storages).device_pc: PCs.device_phone: celulares.device_printer: impresoras.device_securityalarm: alarmas de seguridad.device_tablet: tabletas.device_tv: televisores.device_other: otros dispositivos.
-
Por sistema operativo:
os_android: Android.os_ios: iOS.os_linux: Linux.os_macos: macOS.os_windows: Windows.os_other: otros sistemas operativos.
-
Por grupo de usuarios:
user_admin: administradores.user_regular: usuarios regulares.user_child: niños.
respgeo
El modificador respgeo solo se puede usar en AdGuard DNS.
El modificador respgeo permite aplicar reglas según el país o el ASN de la dirección IP devuelta en la respuesta DNS. Comprueba la dirección IP de destino — la dirección IP a la que se resuelve el dominio. No verifica la dirección IP, el país ni el ASN del usuario, dispositivo o cliente DNS.
Bloqueo por país de respuesta
El valor del modificador debe ser un código de país de dos letras en formato ISO 3166-1 alpha-2. También puedes usar -- para coincidir con respuestas donde no se pudo determinar el país.
Ejemplos:
-
||*^$respgeo=US: bloquea dominios si la dirección IP en la respuesta DNS está asociada con Estados Unidos. -
||*^$respgeo=FR|DE: bloquear dominios si la dirección IP en la respuesta DNS está asociada con Francia o Alemania. -
||*^$respgeo=--: bloquear dominios si el país de la dirección IP en la respuesta DNS es desconocido. -
||*^$respgeo=~--: bloquea dominios si se conoce el país de la dirección IP en la respuesta DNS. -
@@||whitehouse.gov^: permitirwhitehouse.gov, incluso si está bloqueado por una regla comodín con el modificadorrespgeo. -
@@||example.org^$respgeo=US: permitirexample.orgsi la dirección IP en la respuesta DNS está asociada con Estados Unidos. -
||whitehouse.gov^$respgeo=US: bloqueawhitehouse.govsolo si la dirección IP en la respuesta DNS está asociada con los Estados Unidos. -
En este ejemplo:
||whitehouse.gov^@@||whitehouse.gov^$respgeo=US@@||whitehouse.gov^$respgeo=USno permitiráwhitehouse.gov, porque la primera regla bloquea la consulta al inspeccionar los datos de la solicitud, mientras que la segunda intenta permitirla inspeccionando la respuesta.
Puede usar ~ para invertir la condición:
||*^$respgeo=~DE: bloquear dominios si la dirección IP en la respuesta DNS no está asociada con Alemania.
Limitaciones
El modificador respgeo utiliza una única dirección IP calculada y el país según la lógica actual del Registro de consultas. Si un dominio se resuelve en múltiples direcciones IP o países, AdGuard DNS no analiza todas las direcciones IP devueltas.
Debido a que muchos dominios utilizan CDNs, equilibrio de carga o infraestructura distribuida geográficamente, el país detectado puede cambiar con el paso de la hora.
Si no se puede determinar el país, la condición GeoIP no coincidirá. Use respgeo=-- para hacer coincidir respuestas con un país desconocido.
Las reglas con el modificador respgeo se muestran en el Registro de consultas como reglas normales.
Bloqueo por ASN
El modificador respgeo también se puede usar para aplicar reglas basadas en el ASN de la dirección IP devuelta en la respuesta DNS.
ASN significa Número de Sistema Autónomo. Identifica un sistema autónomo — una red operada por un ISP, proveedor de alojamiento, proveedor de nube, empresa u otra organización.
Este modificador verifica el ASN de destino — el ASN asociado con la dirección IP a la que se resuelve el dominio. No comprueba el ASN del usuario, dispositivo o cliente DNS.
El valor del modificador debe ser un ASN en el formato AS<number>, por ejemplo AS15169.
Ejemplos:
-
||*^$respgeo=AS15169: bloquear dominios si la dirección IP en la respuesta DNS pertenece al ASN AS15169. -
||*^$respgeo=AS15169|AS8075: bloquear dominios si la dirección IP en la respuesta DNS pertenece al ASN AS15169 o AS8075. -
||*^$respgeo=AS--: bloquear dominios si el ASN de la dirección IP en la respuesta DNS es desconocido. -
||*^$respgeo=~AS--: bloquear dominios si se conoce el ASN de la dirección IP en la respuesta DNS. -
@@||google.com^$respgeo=AS15169: permitirgoogle.comsi la dirección IP en la respuesta DNS pertenece al ASN AS15169. -
||google.com^$respgeo=AS15169: bloqueagoogle.comsolo si la dirección IP en la respuesta DNS pertenece al ASN AS15169. -
En este ejemplo:
||google.com^@@||google.com^$respgeo=AS15169@@||google.com^$respgeo=AS15169no permitirágoogle.com, porque la primera regla bloquea la consulta inspeccionando los datos de la solicitud, mientras que la segunda intenta permitirla inspeccionando la respuesta.
Puede usar ~ para invertir la condición:
||*^$respgeo=~AS15169: bloquear dominios si la dirección IP en la respuesta DNS no pertenece al ASN AS15169.
Limitaciones
El modificador respgeo utiliza una única dirección IP y un ASN calculados según la lógica actual del registro de consultas. Si un dominio se resuelve en múltiples direcciones IP o ASN, AdGuard DNS no analiza todos los ASN devueltos.
Los ASN de CDN, nube o alojamiento de gran tamaño pueden contener muchos sitios web no relacionados. Por lo tanto, bloquear un ASN puede afectar a más dominios de lo esperado.
Si no se puede determinar el ASN, la condición de ASN no coincidirá. Utilice respgeo=AS-- para hacer coincidir respuestas con un ASN desconocido.
El ASN no siempre corresponde a una empresa, producto o servicio específico. Solo identifica la red asociada con la dirección IP resuelta.
Las reglas con el modificador respgeo se muestran en el Registro de consultas como reglas normales.
/etc/hosts-sintaxis de estilo
Para cada host debe estar presente una sola línea con la siguiente información:
IP_address canonical_hostname [aliases...]
Los campos de las entradas están separados por cualquier número de espacios o caracteres de tabulación. El texto desde el carácter # hasta el final de la línea es un comentario y se ignora.
Los nombres de host pueden contener solo caracteres alfanuméricos, guiones menos (-) y puntos (``). Deben comenzar con un carácter alfabético y terminar con un carácter alfanumérico. Los alias opcionales proporcionan cambios de nombre, ortografía alternativa, nombres de host más cortos o nombres de host genéricos (por ejemplo, localhost).
Ejemplo:
# Esto es un comentario
127.0.0.1 example.org ejemplo.info
127.0.0.1 example.org
127.0.0.1 example.org # esto también es un comentario
En AdGuard Home, las direcciones IP se utilizan para responder a consultas de DNS para estos dominios. En Private AdGuard DNS, estas direcciones simplemente se bloquean.
Sintaxis sólo para dominios
Una lista simple de nombres de dominio, un nombre por línea.
Ejemplo:
# Este es un comentario
example.org
example.org
example.org # esto también es un comentario
If a string is not a valid domain (e.g. *.example.org), AdGuard Home will consider it to be an Adblock-style syntax rule.
Hostlist compiler
If you are maintaining a blocklist and use different sources in it, Hostlist compiler may be useful to you. It is a simple tool that makes it easier to compile a hosts blocklist compatible with AdGuard Home, Private AdGuard DNS or any other AdGuard product with DNS filtering.
What it’s capable of:
-
Compila una lista de bloqueo única de varias fuentes.
-
Exclude the rules you don’t need.
-
Limpia la lista resultante: deduplica, borra reglas no válidas y comprime la lista.