jarl/docs/blocking.md

Blocking

Jarl can make named answer "this name doesn't exist" (NXDOMAIN) for ads, trackers and malware, like Pi-hole does, for every device that uses your server to resolve names. It has two parts:

• Blocklists: lists of domains published by others, which jarld downloads and keeps up to date.
• Your rules: domains you block or allow yourself. They take precedence over every list.

It uses BIND's own mechanism for this, response policy zones (RPZ), so named does the blocking itself; jarld only prepares the lists.

• Quick start
• Where blocking applies
• Your rules
• Blocklists
• Checking a name
• Pausing
• Statistics
• Memory and performance
• How it works
• Troubleshooting

Quick start

In the web UI, open Blocking, pick one of the well-known lists, and click Add list. Or with the CLI:

jarl blocklist add hagezi-multi https://raw.githubusercontent.com/hagezi/dns-blocklists/main/adblock/multi.txt
jarl blocklist list                     # "ok" once downloaded, usually within seconds
jarl block check ads.doubleclick.net    # blocked? by what?
jarl block allow cdn.example.com        # something you need was blocked

Like every change in Jarl, adding a list or rule can be staged and reviewed first (the web UI does this by default: apply it under Changes).

Where blocking applies

Blocking changes the answers named gives when it resolves names for a client (recursion). It doesn't change what the internet sees of your own zones: other resolvers ask your server without recursion.

Views. A list or rule applies to the views you choose, or by default to every view that offers recursion. With the usual split (an internal view that resolves for your network, an external view that only answers for your zones) that is just internal. A view that doesn't offer recursion gets nothing, and naming one gives a warning. Without views, blocking applies to the whole server.

What it can't do:

• Devices that don't use your server for DNS aren't affected. That includes browsers using their own DNS over HTTPS, and devices with a hard-coded resolver (8.8.8.8). A firewall rule that sends port 53 to your server, and your network's DNS settings, are the usual answers.
• A device that validates DNSSEC itself sees a blocked name as a validation failure rather than "doesn't exist". It's still blocked.
• A list can contain names in your own zones. They are blocked like any other; allow them with a rule if that's not what you want.

Your rules

A rule blocks or allows a domain and every name below it, or with --exact (web UI: "only this exact name") just the domain itself.

jarl block add doubleclick.net                       # doubleclick.net and everything below it
jarl block add telemetry.example.com --exact         # just that name
jarl block allow cdn.example.com --view internal     # an exception, in one view
jarl block list
jarl block delete doubleclick.net                    # or: --id ID

Precedence: your rules come before every blocklist, and among your rules the most specific one wins. With these rules:

Rule
block example.com	and below
allow cdn.example.com	exact

example.com and www.example.com are blocked, cdn.example.com is allowed, and img.cdn.example.com is blocked again (the allow rule was for the exact name). An allow rule beats a blocklist entry whatever the lists say.

There is one rule per domain and view; a second one is refused. A rule takes effect as soon as the change is applied.

Blocklists

Formats. Lists are read line by line; one list may mix formats:

Line	Blocks
||ads.example^ (Adblock)	the name and every name below it
*.ads.example	the name and every name below it
0.0.0.0 ads.example (hosts file, any address)	just the name
ads.example (plain domain)	just the name

Comments (#, !), headers and blank lines are ignored. Lines that DNS can't act on are skipped and counted: Adblock exceptions (@@), cosmetic and URL rules, addresses, invalid names, and single labels (a broken list can't block com). Prefer lists in Adblock format: they say which entries cover the names below them.

Well-known lists (sizes in October 2026; they change):

List	URL	Domains	Memory per view
Hagezi Light	https://raw.githubusercontent.com/hagezi/dns-blocklists/main/adblock/light.txt	55,000	~65 MB
Hagezi Multi Normal	https://raw.githubusercontent.com/hagezi/dns-blocklists/main/adblock/multi.txt	159,000	~190 MB
Hagezi Pro	https://raw.githubusercontent.com/hagezi/dns-blocklists/main/adblock/pro.txt	195,000	~235 MB
OISD Small	https://small.oisd.nl/	58,000	~70 MB
OISD Big	https://big.oisd.nl/	241,000	~290 MB
StevenBlack hosts	https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts	73,000	~45 MB

One good list is usually enough; lists overlap a lot. Hagezi Multi Normal is a balanced start; Light and OISD Small block less but almost never something you need.

Updates. jarld checks each list every blocking.refresh (a day by default) and downloads it only when the server says it changed. A new version is checked with named-checkzone and replaces the old one only when its content differs; named then reloads it. If a download or check fails, named keeps using the previous version, jarld tries again within the hour, and the dashboard shows the error. To update now:

jarl blocklist refresh              # every list; or: refresh hagezi-multi [--force]

Managing lists:

jarl blocklist update hagezi-multi --view internal     # --view auto: every view with recursion
jarl blocklist update hagezi-multi --url URL --name NEW-NAME
jarl blocklist disable hagezi-multi                    # stop using it, keep it (enable: back without a download)
jarl blocklist delete hagezi-multi

A list's state is ok (in use), waiting (not downloaded yet), error (the last update failed; the previous version stays in use), disabled, or idle (it applies to no view, so it does nothing).

Checking a name

jarl block check NAME, or the box at the top of the Blocking page, says for each view whether a name is blocked or allowed, and by which rule or list entry:

$ jarl block check img.ads.example.com
view internal:  blocked by blocklist hagezi-multi (entry *.ads.example.com)
view guest:     allowed by your rule 12 (entry *.ads.example.com)

Views without blocking aren't listed.

In the web UI a blocked name gets an Allow button, and the statistics' most blocked names link to this check.

Pausing

To see whether blocking is what breaks a site, pause it: every name is answered normally until the time is up (at most a day), then blocking resumes by itself, also if jarld was restarted in between.

jarl block pause          # 10 minutes; or: jarl block pause 1h
jarl block resume         # end it now

In the web UI, Pause blocking is at the top of the Blocking page, and the dashboard says while blocking is paused. The lists stay loaded (the rules zone just lets everything through), so pausing and resuming take effect within a second. Pausing and resuming are recorded in the history like other changes.

Statistics

With query statistics on (including query_log), Jarl counts what blocking does: blocked queries over time (next to all queries) and as a share of them, which rules and lists blocked them, the most blocked names, and the clients with the most blocked queries (jarl stats summary, jarl stats top blocked, jarl stats top blocked-clients, jarl stats breakdown blocklist). Blocked answers are left out of the NXDOMAIN figures, which are about names that really don't exist.

Without statistics named doesn't log what it blocks at all.

Memory and performance

Memory is the cost to watch. named keeps each list in memory, once per view it applies to: about 0.6 KB per policy record (an Adblock entry is two records: the name, and the names below it). The Blocking page and jarl blocklist list show the estimate per list. Hagezi Pro in one view took named from 25 MB to 260 MB in a test with BIND 9.20; while a list reloads, the old and new versions briefly coexist.

Answers aren't slowed: named looks blocked names up in memory, and answers them without asking the internet.

Updating a list (Hagezi Pro: download, parse, check) takes jarld about 2 seconds. While named loads the new version, the queries that the loading thread would have answered wait, up to half a second; this only happens when the list changed, at most once per blocking.refresh.

Other changes are unaffected: the lists' contents never go through Jarl's apply, so adding a record takes as long with a list as without.

Downloads are limited by blocking.max_download_mb and blocking.max_entries (configuration.md).

How it works

For each view (or the server, without views) Jarl writes a response-policy statement and the policy zones it lists, in this order:

response-policy {
	zone "rules.jarl.invalid" min-update-interval 0;              # your rules
	zone "hagezi-multi.blocklist.jarl.invalid" min-update-interval 0;
} qname-wait-recurse no break-dnssec yes;

• Policy zones are named under .invalid, so they can't clash with real zones (zone names under jarl.invalid are refused). They allow no queries or transfers.
• The rules zone of each view is a file next to your zone files (/var/lib/bind/jarl/VIEW/rules.jarl.invalid.rpz) and shows up in the changeset diff like any other.
• A list's file is /var/cache/bind/jarl/blocklists/list-ID.rpz, shared by the views that use it. Until the first download it is an empty policy zone, so named always starts. Files of deleted lists are removed.
• qname-wait-recurse no blocks without first resolving the real answer; break-dnssec yes also blocks for clients that ask for DNSSEC data; min-update-interval 0 applies a new version at once.
• named looks names up in a policy zone like in any zone, so a wildcard doesn't apply below a name the zone also contains. Jarl writes the zones so that the most specific rule still wins.
• A response-policy option of your own can't be combined with Jarl's blocking in the same view: Jarl refuses the change and says so.
• Rewrites are logged to Jarl's response log when statistics read it, and not at all otherwise.

Lists and rules need the blocking permission (permissions.md).

Troubleshooting

• "no domains found in N lines": the URL didn't return a list (often an HTML error page). Check it in a browser.
• A list has no effect / is "idle": no view it applies to offers recursion. Pick the view your devices use (--view internal).
• Something is still answered: jarl block check NAME shows whether Jarl blocks it. If it does, the device probably doesn't use your server (DNS over HTTPS, another resolver), or has the answer cached for a while.
• Something you need is blocked: jarl block check NAME shows which list; jarl block allow NAME overrides it.