Cú pháp viết lại AdGuard Home DNS

Giới thiệu

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.

Có ba cách viết danh sách chặn (blocklist) hosts:

• Cú pháp kiểu Adblock: Cách hiện đại, dựa trên một tập hợp con của cú pháp quy tắc Adblock. Các danh sách chặn kiểu này tương thích với trình chặn quảng cáo trên trình duyệt.
• Cú pháp /etc/hosts: Cách tiếp cận cũ, sử dụng cú pháp giống như tệp hosts của hệ điều hành.
• Cú pháp chỉ tên miền: Một danh sách đơn giản chỉ chứa tên miền.

Nếu bạn đang tạo một danh sách chặn, chúng tôi khuyên dùng cú pháp kiểu Adblock vì những ưu điểm sau:

• Kích thước nhỏ hơn: Dùng ký tự đại diện (pattern matching) cho phép một quy tắc thay thế cho hàng trăm mục trong /etc/hosts.
• Tính tương thích: Danh sách của bạn sẽ tương thích với trình chặn quảng cáo trình duyệt, dễ dàng chia sẻ quy tắc.
• Khả năng mở rộng: Cú pháp Adblock đã phát triển nhiều và chúng tôi có thể mở rộng thêm để cung cấp tính năng mới cho bộ lọc cấp mạng.

Nếu bạn đang duy trì danh sách chặn kiểu /etc/hosts hoặc nhiều danh sách lọc, chúng tôi cung cấp công cụ Hostlist compiler để biên dịch chúng. Chính chúng tôi cũng dùng nó để tạo Bộ lọc AdGuard DNS.

Ví dụ cơ bản

• ||example.org^: Chặn truy cập tên miền example.org và tất cả tên miền phụ của nó (như www.example.org).
• @@||example.org^: Bỏ chặn (loại trừ) truy cập tên miền example.org và tất cả tên miền phụ của nó.
• 1.2.3.4 example.org: (Chú ý: cú pháp /etc/hosts cũ)
  • Trong AdGuard Home: Trả lời bằng IP 1.2.3.4 cho các truy vấn đến example.org (không áp dụng cho tên miền phụ).
  • Trong Private AdGuard DNS: Chặn truy cập example.org. www.example.org vẫn được phép.
  • Dùng IP 0.0.0.0 hoặc IP local (127.0.0.1) trong AdGuard Home cũng tương đương với việc chặn 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: Quy tắc tên miền đơn giản. Chặn example.org nhưng không chặn các tên miền phụ. www.example.org vẫn được phép.
• ! Đây là bình luận và # Cũng là bình luận: Dòng bình luận.
• /REGEX/: Chặn các tên miền khớp với biểu thức chính quy (regex) được chỉ định.

Cú pháp kiểu Adblock

Đây là tập hợp con của cú pháp Adblock truyền thống dùng trong trình chặn quảng cáo trình duyệt.

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

• pattern: Mặt nạ tên máy chủ. Mọi tên máy chủ sẽ được so khớp với mặt nạ này. Pattern có thể chứa các ký tự đặc biệt.
• @@: Dấu hiệu cho quy tắc loại trừ (exception). Dùng ở đầu quy tắc để tắt bộ lọc cho các hostname khớp.
• modifiers: Các tham số làm rõ quy tắc, có thể giới hạn phạm vi hoặc thay đổi cách hoạt động của quy tắc.

Ký tự đặc biệt

• *: Ký tự đại diện, đại diện cho bất kỳ chuỗi ký tự nào (có thể rỗng hoặc dài bất kỳ).
• ||: Khớp phần đầu của hostname, bao gồm mọi tên miền phụ. Ví dụ: ||example.org khớp example.org và test.example.org nhưng không khớp testexample.org.
• ^: Ký tự phân cách. Trong DNS filtering, nó chỉ dùng để đánh dấu kết thúc hostname.
• |: Con trỏ đến đầu hoặc cuối hostname.
  • ample.org| khớp example.org nhưng không khớp example.org.com.
  • |example khớp example.org nhưng không khớp test.example.

Biểu thức chính quy (Regex)

Để linh hoạt hơn, bạn có thể dùng regex. Pattern phải có dạng:

pattern = "/" regexp "/"

Ví dụ:

• /example.*/ sẽ chặn các host khớp regex example.*.
• @@/example.*/$important sẽ bỏ chặn các host khớp regex example.*. Quy tắc này có kèm modifier important.

Bình luận

Dòng bắt đầu bằng ! hoặc # là bình luận và bị bộ lọc bỏ qua.
Ví dụ:

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

Các Modifier (Bổ sung quy tắc)

Bạn có thể thay đổi hành vi quy tắc bằng các modifier. Chúng đặt cuối quy tắc, sau ký tự $ và phân cách bằng dấu phẩy.
Ví dụ:

• ||example.org^$important
  • ||example.org^ là pattern khớp.
  • $ là dấu phân cách.
  • important là modifier.
• Dùng nhiều modifier: ||example.org^$client=127.0.0.1,dnstype=A
  • client=127.0.0.1 là modifier client với giá trị 127.0.0.1.
  • dnstype=A là modifier dnstype với giá trị A.

Lưu ý: Nếu một quy tắc chứa modifier không có trong tài liệu này, toàn bộ quy tắc sẽ bị bỏ qua. Điều này tránh false-positives khi dùng danh sách bộ lọc trình duyệt (như EasyList) chưa sửa đổi.

client

Modifier client chỉ định máy khách nào áp dụng quy tắc. Có 2 cách xác định client:

1. Theo địa chỉ IP hoặc CIDR (hoạt động với mọi client).
2. Theo tên (chỉ hoạt động với client thường trực trong AdGuard Home hoặc thiết bị đã thêm thủ công trong Private AdGuard DNS). Lưu ý (AdGuard Home): Chỉ hỗ trợ tên client, không hỗ trợ ClientID. Nếu client tên “My Client” có ID my-client, hãy dùng $client='My Client' thay vì $client=my-client.

Cú pháp:

$client=value1|value2|...

Để loại trừ client, thêm ~ trước giá trị:

$client=~value1

Tên client có thể chứa khoảng trắng/ký tự đặc biệt, nên đặt trong dấu ngoặc kép (" hoặc '). Dùng \ để escape các ký tự ", ', ,, |.

Lưu ý: Khi loại trừ, đặt ~ bên ngoài dấu ngoặc kép.

Ví dụ:

• @@||*^$client=127.0.0.1: Bỏ chặn mọi thứ cho localhost.
• ||example.org^$client='Frank\'s laptop': Chặn example.org chỉ cho client tên Frank's laptop. (Escape dấu ').
• ||example.org^$client=~'Mary\'s\, John\'s\, and Boris\'s laptops': Chặn example.org cho tất cả, trừ client tên Mary's, John's, and Boris's laptops. (Escape dấu , và ').
• ||example.org^$client=~Mom|~Dad|Kids: Chặn example.org cho Kids, nhưng không chặn cho Mom và Dad.
• ||example.org^$client=192.168.0.0/24: Chặn example.org cho mọi client có IP trong dải 192.168.0.0 đến 192.168.0.255.

denyallow

Modifier denyallow loại trừ các tên miền khỏi quy tắc chặn. Dùng | để phân cách nhiều tên miền.
Cú pháp:

$denyallow=domain1|domain2|...

Modifier này giúp tránh tạo quá nhiều quy tắc loại trừ khi một quy tắc chặn bao phủ quá rộng.

Ví dụ:

• *$denyallow=com|net: Chặn mọi thứ, trừ *.com và *.net.
• @@*$denyallow=com|net: Bỏ chặn mọi thứ, trừ *.com và *.net.
• ||example.org^$denyallow=sub.example.org: Chặn example.org và *.example.org, nhưng không chặn sub.example.org.

dnstype

Modifier dnstype chỉ định loại yêu cầu hoặc phản hồi DNS mà quy tắc sẽ kích hoạt.
Cú pháp:

$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

Tên loại (A, AAAA, CNAME…) không phân biệt chữ hoa/thường. Không kết hợp cả hai kiểu bao gồm và loại trừ trong cùng một modifier.

Ví dụ:

• ||example.org^$dnstype=AAAA: Chỉ chặn truy vấn DNS lấy địa chỉ IPv6 (AAAA) của example.org.
• ||example.org^$dnstype=~A|~CNAME: Chỉ cho phép truy vấn A và CNAME cho example.org, chặn tất cả loại khác.

Lưu ý (từ v0.108.0): Trước đây, AdGuard Home lọc bản ghi phản hồi dựa trên loại yêu cầu. Từ v0.108.0, nó lọc dựa trên loại bản ghi phản hồi. Ví dụ, quy tắc ||canon.example.com^$dnstype=~CNAME sẽ cho phép bản ghi CNAME trong phản hồi, ngay cả khi yêu cầu là loại A hoặc AAAA.

dnsrewrite

Bổ sung dnsrewrite cho phép thay thế nội dung phản hồi DNS cho các máy chủ khớp với quy tắc. Lưu ý rằng bổ sung này trong AdGuard Home hoạt động với mọi quy tắc, nhưng trong Private AdGuard DNS — chỉ hoạt động với các quy tắc tùy chỉnh.

Các quy tắc có bổ sung dnsrewrite có độ ưu tiên cao hơn các quy tắc khác trong AdGuard Home và AdGuard DNS.

Phản hồi cho mọi yêu cầu đến một máy chủ khớp với quy tắc dnsrewrite sẽ bị thay thế. Phần trả lời của phản hồi thay thế sẽ chỉ chứa các bản ghi tài nguyên (RR) khớp với loại truy vấn của yêu cầu và có thể có thêm các bản ghi CNAME. Điều này có nghĩa là phản hồi cho một số yêu cầu có thể trở nên trống rỗng (NODATA) nếu máy chủ khớp với một quy tắc dnsrewrite.

Cú pháp viết tắt:

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

Các từ khóa PHẢI viết hoa toàn bộ (ví dụ: NOERROR). Các quy tắc viết lại bằng từ khóa có ưu tiên cao hơn và sẽ dẫn đến một phản hồi trống với mã phản hồi thích hợp.

Cú pháp đầy đủ có dạng MÃ_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;;

Bổ sung $dnsrewrite với mã phản hồi NOERROR cũng có thể có các trường LOẠI_BẢN_GHI và GIÁ_TRỊ để trống.

Bản ghi CNAME là đặc biệt vì AdGuard Home sẽ phân giải máy chủ đó và thêm thông tin của nó vào phản hồi. Nghĩa là, nếu example.net có IP 1.2.3.4 và người dùng có quy tắc bộ lọc sau:

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

thì phản hồi sẽ giống như:

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

Tiếp theo, viết lại CNAME. Sau đó, tất cả các giá trị bản ghi khác được tổng hợp thành một phản hồi, vì vậy điều này:

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

sẽ dẫn đến một phản hồi có hai bản ghi A.

Các loại bản ghi RR hiện được hỗ trợ cùng với ví dụ:

• ||4.3.2.1.in-addr.arpa^$dnsrewrite=NOERROR;PTR;example.net. thêm một bản ghi PTR cho DNS ngược. Các yêu cầu DNS ngược cho 1.2.3.4 đến máy chủ DNS sẽ trả về example.net. Lưu ý: IP PHẢI được viết theo thứ tự ngược lại. Xem RFC 1035.
• ||example.com^$dnsrewrite=NOERROR;A;1.2.3.4 thêm một bản ghi A với giá trị 1.2.3.4.
• ||example.com^$dnsrewrite=NOERROR;AAAA;abcd::1234 thêm một bản ghi AAAA với giá trị abcd::1234.
• ||example.com^$dnsrewrite=NOERROR;CNAME;example.org thêm một bản ghi CNAME. Xem giải thích ở trên.
• ||example.com^$dnsrewrite=NOERROR;HTTPS;32 example.com alpn=h3 thêm một bản ghi HTTPS. Chỉ một tập hợp con các giá trị tham số được hỗ trợ: các giá trị phải liền mạch và, nơi một danh sách giá trị được mong đợi, hiện chỉ hỗ trợ một giá trị: 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ợ. Điều này sẽ được thay đổi trong tương lai.
• ||example.com^$dnsrewrite=NOERROR;MX;32 example.mail thêm một bản ghi MX với giá trị ưu tiên 32 và giá trị trao đổi example.mail.
• ||example.com^$dnsrewrite=NOERROR;SVCB;32 example.com alpn=h3 thêm một giá trị SVCB. Xem ví dụ HTTPS ở trên.
• ||example.com^$dnsrewrite=NOERROR;TXT;hello_world thêm một bản ghi TXT với giá trị hello_world.
• ||_svctype._tcp.example.com^$dnsrewrite=NOERROR;SRV;10 60 8080 example.com thêm một bản ghi SRV với giá trị ưu tiên 10, giá trị trọng số 60, cổng 8080 và giá trị đích example.com.
• ||example.com^$dnsrewrite=NXDOMAIN;; phản hồi với mã NXDOMAIN.
• $dnstype=AAAA,denyallow=example.org,dnsrewrite=NOERROR;; phản hồi với câu trả lời NOERROR trống cho tất cả các yêu cầu AAAA ngoại trừ các yêu cầu cho example.org.

Các quy tắc loại trừ bỏ chặn một hoặc tất cả các quy tắc:

• @@||example.com^$dnsrewrite bỏ chặn tất cả các quy tắc viết lại DNS.
• @@||example.com^$dnsrewrite=1.2.3.4 bỏ chặn quy tắc viết lại DNS thêm bản ghi A với giá trị 1.2.3.4.

Thông tin: Nếu bạn đang duy trì một danh sách chặn được bao gồm trong AdGuard DNS và AdGuard Home (tức là được đưa vào HostlistsRegistry), các quy tắc $dnsrewrite sẽ tự động bị lọc ra. Nếu các quy tắc này là cần thiết cho danh sách chặn của bạn, vui lòng yêu cầu quyền bằng cách mở một vấn đề mới trong kho lưu trữ HostlistsRegistry.

important

Bổ sung important được áp dụng cho một quy tắc làm tăng mức độ ưu tiên của nó so với bất kỳ quy tắc nào khác không có bổ sung này. Ngay cả trên các quy tắc loại trừ cơ bản.

Ví dụ:

• Trong ví dụ này: ||example.org^$important @@||example.org^ ||example.org^$important sẽ chặn tất cả các yêu cầu đến *.example.org bất chấp quy tắc loại trừ.
• Trong ví dụ này:
  ||example.org^$important @@||example.org^$important
  quy tắc loại trừ cũng có bổ sung important, vì vậy nó sẽ hoạt động.

badfilter

Các quy tắc có bổ sung badfilter vô hiệu hóa các quy tắc cơ bản khác mà chúng tham chiếu đến. Điều này có nghĩa là văn bản của quy tắc bị vô hiệu hóa phải khớp với văn bản của quy tắc badfilter (không có bổ sung badfilter).

Ví dụ:

• ||example.com$badfilter vô hiệu hóa ||example.com.
• @@||example.org^$badfilter vô hiệu hóa @@||example.org^. Lưu ý: Bổ sung badfilter hiện không hoạt động với các quy tắc kiểu /etc/hosts. 127.0.0.1 example.org$badfilter sẽ không vô hiệu hóa quy tắc gốc 127.0.0.1 example.org.

ctag

Bổ sung ctag chỉ có thể được sử dụng trong AdGuard Home.

Nó cho phép chặn các tên miền chỉ cho các loại thẻ máy khách DNS cụ thể. Bạn có thể gán thẻ cho máy khách trong giao diện người dùng AdGuard Home. Trong tương lai, chúng tôi dự định gán thẻ tự động bằng cách phân tích hành vi của từng máy khách.

Cú pháp:

$ctag=value1|value2|...

Nếu một trong các thẻ của máy khách khớp với các giá trị ctag, quy tắc này áp dụng cho máy khách đó. Cú pháp cho loại trừ là:

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

Nếu một trong các thẻ của máy khách khớp với các giá trị loại trừ ctag, quy tắc này không áp dụng cho máy khách đó.

Ví dụ:

• ||example.org^$ctag=device_pc|device_phone: chặn example.org cho các máy khách được gắn thẻ là device_pc hoặc device_phone.
• ||example.org^$ctag=~device_phone: chặn example.org cho tất cả các máy khách ngoại trừ những máy được gắn thẻ là device_phone.

Danh sách các thẻ được phép:

• Theo loại thiết bị:
  • device_audio: thiết bị âm thanh.
  • device_camera: máy ảnh.
  • device_gameconsole: máy chơi game.
  • device_laptop: máy tính xách tay.
  • device_nas: NAS (Bộ lưu trữ gắn mạng).
  • device_pc: máy tính cá nhân.
  • device_phone: điện thoại.
  • device_printer: máy in.
  • device_securityalarm: báo động an ninh.
  • device_tablet: máy tính bảng.
  • device_tv: TV.
  • device_other: thiết bị khác.
• Theo hệ điều hành:
  • os_android: Android.
  • os_ios: iOS.
  • os_linux: Linux.
  • os_macos: macOS.
  • os_windows: Windows.
  • os_other: hệ điều hành khác.
• Theo nhóm người dùng:
  • user_admin: quản trị viên.
  • user_regular: người dùng thông thường.
  • user_child: trẻ em.

Cú pháp kiểu /etc/hosts

Đối với mỗi máy chủ, một dòng duy nhất phải có mặt với thông tin sau:

IP_address canonical_hostname [aliases...]

Các trường của mục nhập được phân tách bằng bất kỳ số lượng ký tự khoảng trắng hoặc tab nào. Văn bản từ ký tự # cho đến cuối dòng là một bình luận và bị bỏ qua.

Tên máy chủ chỉ có thể chứa các ký tự chữ và số, dấu gạch ngang (-) và dấu chấm (.). Chúng phải bắt đầu bằng một ký tự chữ cái và kết thúc bằng một ký tự chữ số. Các bí danh tùy chọn cung cấp cho việc thay đổi tên, cách viết tắt, tên máy chủ ngắn hơn hoặc tên máy chủ chung (ví dụ: localhost).

Ví dụ:

# Đâ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

Trong AdGuard Home, các địa chỉ IP được sử dụng để trả lời các truy vấn DNS cho các tên miền này. Trong Private AdGuard DNS, các địa chỉ này chỉ đơn giản bị chặn.

Cú pháp chỉ tên miền

Một danh sách đơn giản các tên miền, mỗi dòng một tên.

Ví dụ:

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

Nếu một chuỗi không phải là tên miền hợp lệ (ví dụ: *.example.org), AdGuard Home sẽ coi nó là một quy tắc cú pháp kiểu Adblock.

Trình biên dịch Danh sách Máy chủ (Hostlist compiler)

Nếu bạn đang duy trì một danh sách chặn và sử dụng các nguồn khác nhau trong đó, Trình biên dịch Danh sách Máy chủ có thể hữu ích cho bạn. Đây là một công cụ đơn giản giúp dễ dàng biên dịch một danh sách chặn máy chủ tương thích với AdGuard Home, Private AdGuard DNS hoặc bất kỳ sản phẩm AdGuard nào khác có tính năng lọc DNS.

Những gì nó có thể làm:

1. Biên dịch một danh sách chặn duy nhất từ nhiều nguồn.
2. Loại trừ các quy tắc bạn không cần.
3. Dọn dẹp danh sách kết quả: loại bỏ trùng lặp, xóa các quy tắc không hợp lệ và nén danh sách.

Dịch bởi DeepSeek V3.2 – Nguồn: https://adguard-dns.io/kb/general/dns-filtering-syntax/