Blocklist Formats: CSV, Hosts, DNS RPZ, AdGuard, Pi-hole and Firewall EDL
The same list of domains to block can be written in a dozen ways. This guide shows each DNS blocklist and firewall list format, where it is used and what it looks like.
All examples use placeholder domains under the reserved .test suffix, so nothing here points at a real site.
# one domain, five formats 0.0.0.0 example-gambling.test # hosts example-gambling.test # plain list ||example-gambling.test^ # AdGuard style example-gambling.test CNAME . # RPZ *.example-gambling.test # firewall EDL
Blocklist formats at a glance
Before the details, here is how the common formats compare.
Subdomain handling and exception support are the two differences that cause the most surprises.
Format Typical consumer One entry looks like Covers subdomains Allow exceptions Comment marker CSV / Parquet / JSON Databases, policy engines, analytics domain plus categories Your code decides Your code decides None (data rows) Hosts file Operating systems, routers, Pi-hole, AdGuard Home 0.0.0.0 domain No, exact name No # Plain domain list Pi-hole, AdGuard Home, many DNS filters domain Depends on the reader No # Adblock style AdGuard Home, AdGuard DNS, browser blockers ||domain^ Yes Yes, @@ ! DNS RPZ BIND, Unbound, PowerDNS Recursor, Knot Resolver domain CNAME . With a *. entry Yes, passthru ; dnsmasq Routers, small resolvers address=/domain/0.0.0.0 Yes Limited # Unbound local-zone Unbound resolvers local-zone: "domain." always_nxdomain Yes Yes, transparent # Firewall EDL Next-generation firewalls domain or *.domain Depends on firewall Via separate list Varies Squid ACL file Squid and similar proxies .domain Yes, leading dot Via allow ACL # PAC file Browsers via proxy auto-config dnsDomainIs(host, ".domain") Yes Yes, in code //
For the bigger picture of where DNS and proxy enforcement sit, read DNS filtering vs web filtering.
Source data: CSV, Parquet and JSON
Every enforcement format below is generated from a source table. In our database that table holds each domain with its categories, ranked by how much of the site they describe.
The simplest source format. One row per domain, with the categories in ranked order.
Filter on the first category for strict lists, or on any category for broad lists.
Best when you generate many lists from one file. Selecting every Gambling domain is a quick column filter, even across 120 million rows.
Keep Parquet as your master copy and write the enforcement formats from it.
Handy when a service reads a record at a time. JSON Lines, one object per line, streams well.
Hosts files and plain domain lists
The oldest DNS blocklist format, still read by operating systems, routers and home DNS tools.
Each line maps a name to an address. Pointing a name at 0.0.0.0 makes connections fail quickly.
0.0.0.0 usually fails faster than 127.0.0.1, which may wait on a local service.
Just one domain per line. It is the most portable list of domains to block, and most tools accept it.
AdGuard Home block list and Pi-hole blocklist formats
Home and small-office DNS tools are often the first place people meet blocklists. Both read several syntaxes.
The double pipe anchors the start of a domain and the caret marks its end. Exceptions begin with @@.
For an AdGuard Home block list, this syntax is the most compact choice because one line replaces many hosts entries.
A Pi-hole blocklist is added by URL as an adlist. Pi-hole downloads it on its update schedule and merges it into one block table.
Keep large category lists as adlists and use regex only for a few patterns, since many regex filters slow lookups.
Category lists, not ad lists
Ad-blocking lists cover trackers. Content categories such as Adult or Gambling need a categorized source.
Few big lists
A handful of category lists is easier to audit than dozens of overlapping community lists.
Generate, do not curate
Build every list from one categorized source so updates stay consistent across products.
DNS RPZ, dnsmasq and Unbound
Resolvers run by ISPs, schools and companies use server-side formats. These change answers for every client behind the resolver.
A response policy zone is an ordinary DNS zone with special meaning. The target of each record tells the resolver what to do.
The *. line is needed to cover subdomains. 192.0.2.10 is a documentation address; use your own block page server.
The address option answers a name and everything under it with a fixed address.
Each entry declares a zone and how to answer it. The always_nxdomain type blocks the name and its subdomains.
Building a resolver product? See DNS filtering integration and our managed DNS filter page.
Firewall EDL, proxy ACLs and PAC files
Firewalls and proxies see more than DNS: full hostnames, sometimes URLs. They read lists in their own simple formats.
A plain text file with one domain, URL or IP per line. The firewall downloads it on a schedule and uses it like any other object in a rule.
Check whether your firewall matches subdomains automatically or needs a *. entry, and check its maximum list size.
The list file holds names; the proxy config references it in an ACL.
A PAC file is a small script that picks a proxy per request. Listed domains can be sent to a filtering proxy or to an address that refuses connections.
Keep PAC lists short. Large category sets belong in the proxy or firewall, not in the browser.
Converting between blocklist formats
Conversions look trivial but each one changes meaning slightly. These rules keep a list doing what you expect after it moves to a new tool.
| From | To | What changes | Rule of thumb |
|---|---|---|---|
| Hosts | Adblock style | Exact names become domain-and-subdomain rules | Drop www. duplicates; the parent rule already covers them |
| Adblock style | Hosts | Subdomain coverage is lost | Add the hostnames you know, or pick a format with wildcards |
| Plain list | RPZ | Each name needs a record, plus a *. record for subdomains | Generate both lines per domain |
| Any list | Firewall EDL | Device limits may cut the list | Send the most visited domains first and keep the rest at the resolver |
| Exceptions | Formats without allow rules | Exceptions silently disappear | Remove allowed names from the block list before export |
Fit the device
The top 20 million domains cover 99.99% of traffic, so small devices rarely need the full set.
Reload, do not restart
Prefer formats your resolver or firewall can reload in place, so updates do not drop queries.
Keep the source
Store the CSV or Parquet row behind every exported line, so you can explain any block later.
Which format should you choose?
Pick the format your enforcement point reads natively. Converting in the device usually costs memory and update speed.
DNS RPZ
Standard, supports block pages and exceptions, and moves between server brands.
Adblock style or hosts
AdGuard Home prefers adblock style; Pi-hole reads hosts and plain lists everywhere.
dnsmasq
Covers subdomains in one line and fits small devices if the list is sized well.
EDL
Fetched on a schedule, no reboot, works as a normal rule object.
ACL file
Leading-dot entries keep the file short and cover every subdomain.
Parquet or CSV
Load the full categories and let your engine decide, instead of flattening into lists.
Building a list of domains to block by category
Most organisations block a handful of categories, not hand-picked domains. These are the categories that most often become their own lists.
Malware / Phishing
The baseline security list for every network. See phishing domains.
Adult
Standard for schools, libraries, workplaces and family networks. See adult content.
Gambling
Common in workplaces, schools and some national rules. See gambling sites.
VPN / Proxy
Stops users from routing around every other list. See VPN and proxy domains.
AI / LLM Tools
Often allowed for staff and limited for students; 16,000+ domains in 18 categories.
File Sharing/P2P
Reduces malware and licensing risk on company and campus networks.
URL Shorteners
Hide final destinations; often blocked or sent to inspection.
Parked / For-Sale
Low value pages that sometimes turn into threats later.
All 59 categories are listed on the web filtering categories page. Many lists combine categories, for example a school list built from the CIPA-relevant set.
How licensed customers get category exports
Licence holders receive the source files and can also receive exports shaped for their enforcement points.
- 1
Choose categories
Pick one or more of the 59 categories, or AI tool categories, per list.
- 2
Choose formats
Hosts, DNS RPZ, AdGuard or Pi-hole style, firewall EDL or PAC, next to CSV, Parquet and JSON.
- 3
Choose scope
Top domains only for small devices, or the full set for resolvers and cloud services.
- 4
Keep it current
About 300,000 new domains a day arrive as delta files; the rest refreshes monthly.
Good practice
- One list per category, so policies can mix them
- Host lists on your own HTTPS server for firewalls to fetch
- Test a new list on a staging resolver before rollout
- Keep an allow list for business-critical exceptions
- Watch the update job and alert if a file is late or empty
Common mistakes
- Hosts format where subdomains matter
- Loading a full 120 million line list onto a small router
- Forgetting the *. entry in RPZ zones
- Mixing many overlapping community lists with no owner
- No block page, so users think the internet is broken
Prefer per-request answers? The lookup API is included with licences, and the bulk domain lookup guide covers batch use.
DNS blocklist FAQ
What is the best format for an AdGuard Home block list?
AdGuard Home reads hosts files, plain domain lists and adblock-style rules. Adblock-style rules such as ||example.test^ are the most flexible, because one line covers a domain and all its subdomains and exceptions use the @@ prefix.
Which format does a Pi-hole blocklist use?
Pi-hole adlists are usually hosts files or plain lists with one domain per line. Recent versions also understand the simple ||domain^ style, so check the documentation for the version you run.
What is a DNS RPZ?
A response policy zone is a DNS zone that tells a recursive resolver how to change answers for listed names, for example returning NXDOMAIN or redirecting to a block page. BIND, Unbound, PowerDNS Recursor and Knot Resolver support it.
What is a firewall external dynamic list?
An external dynamic list is a plain text file on a web server that a firewall downloads on a schedule and uses in policy rules. Lists can hold IP addresses, domains or URLs, one per line.
How often should a blocklist be refreshed?
Security lists change every day, so daily updates are the norm. Content category lists change more slowly, but new domains still appear daily, which is why our new-domain deltas ship every day and the rest refreshes monthly.
Why do the examples use .test domains?
The .test suffix is reserved for testing and never resolves on the public internet. It keeps examples safe to copy.
Can I get your categories as a DNS blocklist?
Licensed customers can receive category exports as hosts files, DNS RPZ, AdGuard and Pi-hole style lists, firewall external dynamic lists and PAC files, in addition to CSV, Parquet and JSON. Vendors embedding the data should read OEM licensing.
Category lists in the format you need
License 120 million categorized domains and receive exports for your resolvers, firewalls and proxies, updated daily for new domains.
AdGuard is a trademark of AdGuard Software Ltd. Pi-hole is a registered trademark of Pi-hole LLC.
BIND is a trademark of Internet Systems Consortium. These names are used here only to identify the products discussed. Web Filtering Database is not affiliated with, sponsored or endorsed by any of these companies.