AdGuard Home DNS rewrite syntax

About

Bạn có thể sử dụng cú pháp lọc DNS của AdGuard để tạo các quy tắc linh hoạt hơn, giúp chặn nội dung theo ý muốn. Cú pháp này có thể dùng trong nhiều sản phẩm AdGuard như AdGuard Home, AdGuard DNS, AdGuard cho Windows/Mac/Android.

There are three ways to write a hosts blocklist:

• Adblock-style syntax:The modern form, based on a subset of the Adblock rule syntax. Block lists of this kind are compatible with browser ad blockers.
• Syntax/etc/hosts:The older approach, using syntax like the operating system's hosts file.
• Domain-only syntax:A simple list containing only domain names.

If you are building a blocklist, we recommendAdblock-style syntaxfor the following advantages:

• Smaller size:Wildcards (pattern matching) let one rule stand in for hundreds of entries in/etc/hosts.
• Compatibility:Your list will be compatible with browser ad blockers, making rules easy to share.
• Scalability:Adblock syntax has evolved considerably, and we can extend it further to add new capabilities to network-level filtering.

If you maintain a blocklist of the type/etc/hostsor multiple filter lists, we provide a toolHostlist compilerto compile them. We use it ourselves to build the AdGuard DNS Filter.

Basic example

• ||example.org^: Block access to the domainexample.organd all its subdomains (such aswww.example.org).
• @@||example.org^: Unblocks (excludes) access to a domainexample.organd all its subdomains.
• 1.2.3.4 example.org: (Note: the syntax/etc/hostsold)
  • Trong AdGuard Home: Respond with the IP1.2.3.4for queries toexample.org(does not apply to subdomains).
  • Trong Private AdGuard DNS: Block accessexample.org. www.example.orgis still permitted.
  • Use the IP0.0.0.0or a local IP (127.0.0.1) in AdGuard Home is also equivalent to blocking that host.
    # Trả về IP 1.2.3.4 cho example.org. 1.2.3.4 example.org # Chặn example.org bằng cách trả lời 0.0.0.0. 0.0.0.0 example.org
• example.org: Simple domain rules. Blockexample.orgbutnoblocks subdomains.www.example.orgis still permitted.
• ! Đây là bình luậnand# Cũng là bình luận: Comment line.
• /REGEX/: Blocks domains matching the specified regular expression (regex).

Adblock-style syntax

This is a subset of the traditional Adblock syntax used in browser ad blockers.

     rule = ["@@"] pattern [ "$" modifiers ]
modifiers = [modifier0, modifier1[, ...[, modifierN]]]

• pattern: The hostname mask. Every hostname is matched against this mask. The pattern can contain special characters.
• @@: Marks an exception rule. Used at the start of a rule to disable filtering for matching hostnames.
• modifiers: Parameters that qualify a rule; they can narrow its scope or change how it behaves.

Special characters

• *: A wildcard, matching any string of characters (which may be empty or of any length).
• ||: Matches the start of the hostname, including all subdomains. For example:||example.orgmatchexample.organdtest.example.orgbut does not matchtestexample.org.
• ^: A separator character. In DNS filtering it is used only to mark the end of a hostname.
• |: Anchors to the start or end of the hostname.
  • ample.org|matchexample.orgbut does not matchexample.org.com.
  • |examplematchexample.orgbut does not matchtest.example.

Regular expression (Regex)

For more flexibility you can use a regex. The pattern must take the form:

pattern = "/" regexp "/"

Example:

• /example.*/will block hosts matching the regexexample.*.
• @@/example.*/$importantwill unblock hosts matching the regexexample.*. This rule includes a modifierimportant.

Comments

Lines starting with!or#is a comment and is ignored by the filter.
Example:

! Đây là bình luận.
# Cũng là bình luận.

Modifiers (Additional Rules)

You can change a rule's behavior with modifiers. They go at the end of the rule, after the character$and separated by commas.
Example:

• ||example.org^$important
  • ||example.org^is the matching pattern.
  • $is the separator.
  • importantis a modifier.
• Using multiple modifiers:||example.org^$client=127.0.0.1,dnstype=A
  • client=127.0.0.1is a modifierclientwith value127.0.0.1.
  • dnstype=Ais a modifierdnstypewith valueA.

Note:If a rule contains a modifier not documented here, the entire rulewill be ignored. This avoids false positives when using unmodified browser filter lists such as EasyList.

client

Modifier clientspecifies which clients the rule applies to. There are 2 ways to identify a client:

1. Theo IP address or CIDR(works with any client).
2. Theo name(works only with persistent clients in AdGuard Home, or devices added manually in Private AdGuard DNS).Note (AdGuard Home):Only client names are supported, not ClientIDs. If a client named “My Client” has the IDmy-client, use$client='My Client'instead of$client=my-client.

Syntax:

$client=value1|value2|...

To exclude a client, add~before the value:

$client=~value1

A client name may contain spaces or special characters, so put it in double quotes ("or'). Use\to escape the characters", ', ,, |.

Note:When excluding, place~ externaldouble quotes.

Example:

• @@||*^$client=127.0.0.1: Unblock everything for localhost.
• ||example.org^$client='Frank\'s laptop': Blockexample.orgonly for the client namedFrank's laptop. (Escape the').
• ||example.org^$client=~'Mary\'s\, John\'s\, and Boris\'s laptops': Blockexample.orgfor everyone, except the client namedMary's, John's, and Boris's laptops. (Escape the,and').
• ||example.org^$client=~Mom|~Dad|Kids: Blockexample.org cho Kids, but does not blockMomandDad.
• ||example.org^$client=192.168.0.0/24: Blockexample.orgfor any client with an IP within the range192.168.0.0to192.168.0.255.

denyallow

Modifier denyallowexcludes domains from the blocking rule. Use|to separate multiple domains.
Syntax:

$denyallow=domain1|domain2|...

This modifier avoids creating too many exception rules when a blocking rule is too broad.

Example:

• *$denyallow=com|net: Block everything,except *.comand*.net.
• @@*$denyallow=com|net: Unblock everything,except *.comand*.net.
• ||example.org^$denyallow=sub.example.org: Blockexample.organd*.example.org, butdoes not block sub.example.org.

dnstype

Modifier dnstypespecifies which DNS request or response types trigger the rule.
Syntax:

$dnstype=value1|value2|...   // Chỉ áp dụng cho các loại này
$dnstype=~value1|~value2|~... // Áp dụng cho tất cả, TRỪ các loại này

Record type names (A, AAAA, CNAME…) are case-insensitive. Do not mix inclusion and exclusion forms in the same modifier.

Example:

• ||example.org^$dnstype=AAAA: Blocks only DNS queries for the IPv6 (AAAA) address ofexample.org.
• ||example.org^$dnstype=~A|~CNAME: Allow queries onlyAandCNAME cho example.org, and block all other types.

Note (from v0.108.0):Previously, AdGuard Home filtered response records based onrequest type. Since v0.108.0, it filters based onthe response record type. For example, the rule||canon.example.com^$dnstype=~CNAMEwill allow a CNAME record in the response, even when the query is of type A or AAAA.

dnsrewrite

Additionaldnsrewriteallows the content of DNS responses to be replaced for hosts matching a rule. Note that this addition works with every rule in AdGuard Home, but in Private AdGuard DNS it works only with custom rules.

Supplementary rulesdnsrewritetake precedence over other rules in AdGuard Home and AdGuard DNS.

Respond to every request to a server matching the rulednsrewritewill be substituted. The answer section of the substituted response will contain only resource records (RRs) matching the query type of the request, and possibly additional CNAME records. This means the response to some requests may end up empty (NODATA) if the server matches a rulednsrewrite.

Shorthand syntax:

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

Keywords MUST be fully uppercase (for example:NOERROR). Rewrite rules using keywords take higher priority and will produce an empty response with the appropriate response code.

Full syntaxhas the formMÃ_PHẢN_HỒI;LOẠI_BẢN_GHI;GIÁ_TRỊ:

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

Additional$dnsrewritewith response codeNOERRORmay also have fieldsLOẠI_BẢN_GHIandGIÁ_TRỊblank.

RecordCNAMEis special because AdGuard Home will resolve that host and add its details to the response. That is, ifexample.nethas the IP1.2.3.4and users have the following filter rules:

||example.com^$dnsrewrite=example.net
! Hoặc:
||example.com^$dnsrewrite=NOERROR;CNAME;example.net

then the response will look 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, rewriteCNAME. All other record values are then combined into a single response, which means this:

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

will produce a response with two recordsA.

The RR record types currently supported, with examples:

• ||4.3.2.1.in-addr.arpa^$dnsrewrite=NOERROR;PTR;example.net.add a recordPTRfor reverse DNS. Reverse DNS requests for1.2.3.4to the DNS server, which will returnexample.net. Note:The IP MUST be written in reverse order. See RFC 1035.
• ||example.com^$dnsrewrite=NOERROR;A;1.2.3.4add a recordAwith value1.2.3.4.
• ||example.com^$dnsrewrite=NOERROR;AAAA;abcd::1234add a recordAAAAwith valueabcd::1234.
• ||example.com^$dnsrewrite=NOERROR;CNAME;example.orgadd a recordCNAME. See the explanation above.
• ||example.com^$dnsrewrite=NOERROR;HTTPS;32 example.com alpn=h3add a recordHTTPS. Only a subset of parameter values is supported: the values mustliền mạchand, where adanh sách giá trị được mong đợi, currently supports only one value:ipv4hint=127.0.0.1 // Được hỗ trợ. ipv4hint="127.0.0.1" // Không được hỗ trợ. ipv4hint=127.0.0.1,127.0.0.2 // Không được hỗ trợ. ipv4hint="127.0.0.1,127.0.0.2" // Không được hỗ trợ.This will change in the future.
• ||example.com^$dnsrewrite=NOERROR;MX;32 example.mailadd a recordMXwith a priority value32and the exchanged valueexample.mail.
• ||example.com^$dnsrewrite=NOERROR;SVCB;32 example.com alpn=h3add a valueSVCB. See the exampleHTTPSabove.
• ||example.com^$dnsrewrite=NOERROR;TXT;hello_worldadd a recordTXTwith valuehello_world.
• ||_svctype._tcp.example.com^$dnsrewrite=NOERROR;SRV;10 60 8080 example.comadd a recordSRVwith a priority value10, the weight value60, port8080and the target valueexample.com.
• ||example.com^$dnsrewrite=NXDOMAIN;;responds with codeNXDOMAIN.
• $dnstype=AAAA,denyallow=example.org,dnsrewrite=NOERROR;;responds with the answerNOERRORempty for all requestsAAAAexcept for requests toexample.org.

Exception rules unblock one or all rules:

• @@||example.com^$dnsrewriteunblocks all DNS rewrite rules.
• @@||example.com^$dnsrewrite=1.2.3.4unblock rewrite rules DNS add recordsAwith value1.2.3.4.

Information:If you maintain a blocklist that is included in AdGuard DNS and AdGuard Home (that is, added to the HostlistsRegistry), the rules$dnsrewriteare filtered out automatically. If these rules are necessary for your blocklist, please request permission by opening a new issue in the HostlistsRegistry repository.

important

Additionalimportantapplied to a rule raises its priority above any other rule without this modifier, including basic exception rules.

Example:

• In this example:||example.org^$important @@||example.org^ ||example.org^$importantwill block all requests to*.example.orgregardless of exclusion rules.
• In this example:
  ||example.org^$important @@||example.org^$important
  exclusion rules also have additionsimportant, so it will work.

badfilter

Supplementary rulesbadfilterdisables the other basic rules that they reference. This means the text of the disabled rule must match the text of the rulebadfilter(with no additionbadfilter).

Example:

• ||example.com$badfilterdisable||example.com.
• @@||example.org^$badfilterdisable@@||example.org^. Note:Additionalbadfiltercurrently does not work with rules of the type/etc/hosts. 127.0.0.1 example.org$badfilterwillnodisables the original rule127.0.0.1 example.org.

ctag

Additionalctagcan only be used in AdGuard Home.

It allows domains to be blocked only for specific DNS client tag types. You can assign tags to clients in the AdGuard Home user interface. In future we plan to assign tags automatically by analyzing each client's behavior.

Syntax:

$ctag=value1|value2|...

If one of the client's tags matches the valuesctag, the rule applies to that client. The exclusion syntax is:

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

If one of the client's tags matches the exclusion valuesctag, this rule does not apply to that client.

Example:

• ||example.org^$ctag=device_pc|device_phone: blockexample.orgfor clients tagged asdevice_pcordevice_phone.
• ||example.org^$ctag=~device_phone: blockexample.orgfor all clients except those tagged asdevice_phone.

List of allowed tags:

• By device type:
  • device_audio: audio devices.
  • device_camera: camera.
  • device_gameconsole: game console.
  • device_laptop: laptops.
  • device_nas: NAS (Network Attached Storage).
  • device_pc: personal computer.
  • device_phone: phone.
  • device_printer: printer.
  • device_securityalarm: security alarm.
  • device_tablet: tablet.
  • device_tv: TV.
  • device_other: other devices.
• By operating system:
  • os_android: Android.
  • os_ios: iOS.
  • os_linux: Linux.
  • os_macos: macOS.
  • os_windows: Windows.
  • os_other: other operating systems.
• By user group:
  • user_admin: administrator.
  • user_regular: regular users.
  • user_child: children.

Syntax of the form/etc/hosts

For each server, exactly one line must be present containing the following:

IP_address canonical_hostname [aliases...]

The fields of an entry are separated by any number of spaces or tabs. Text from the character#to the end of the line is a comment and is ignored.

A hostname may contain only alphanumeric characters, hyphens (-) and the period (.). They must begin with a letter and end with a digit. Optional aliases are provided for renaming, abbreviations, shorter hostnames or generic hostnames (for example:localhost).

Example:

# Đây là một bình luận
127.0.0.1 example.org example.info
127.0.0.1 example.com
127.0.0.1 example.net # đây cũng là một bình luận

In AdGuard Home, these IP addresses are used to answer DNS queries for those domains. In Private AdGuard DNS, the addresses are simply blocked.

Domain-only syntax

A simple list of domain names, one per line.

Example:

# Đây là một bình luận
example.com
example.org
example.net # đây cũng là một bình luận

If a string is not a valid domain name (for example:*.example.org), AdGuard Home treats it as an Adblock-style rule.

Host list compiler (Hostlist compiler)

If you maintain a blocklist built from multiple sources, the Hosts Blocklist Compiler can help. It is a simple tool that makes it easy to compile a host blocklist compatible with AdGuard Home, Private AdGuard DNS, or any other AdGuard product with DNS filtering.

What it can do:

1. Compiles a single blocklist from multiple sources.
2. Exclude the rules you don't need.
3. Clean up the resulting list: remove duplicates, delete invalid rules and compress the list.

Translated by DeepSeek V3.2 – Source: https://adguard-dns.io/kb/general/dns-filtering-syntax/