DNS filtering

DNS filtering is the resolving side of Dinio. Your devices or networks use Dinio as their DNS resolver, and Dinio decides for each lookup whether to answer it or block it: ads, trackers, malware and phishing domains, or anything else you put on a list. Blocking happens at the DNS level, so it covers every app on the device, not just the browser.

It is separate from DNS hosting. You don’t need a zone to use it, and the domains you filter are anyone’s domains, not yours. Everything here belongs to your user, not to a zone — so it needs a personal key; a zone key gets 403 FORBIDDEN.

The pieces

Piece	What it is
Client identity	How Dinio recognises one of your clients: a device, an office network, a router.
Sinkhole list	A `Blacklist` or a `Whitelist` of rules.
Rule	One name pattern on a list: exact name, wildcard or regular expression.
Link	Applies a list to a client identity. One identity can have many lists, and one list can apply to many identities.

Client identities

A client identity tells Dinio which queries are yours. How a client is recognised depends on the protocol it uses to reach Dinio:

`id_type`	Protocol	Recognised by
`IP`	Plain DNS over UDP/TCP	The client’s source IP address.
`Hostname`	DNS over TLS (DoT)	The hostname the client connects to.
`Path`	DNS over HTTPS (DoH)	The part of the request path that identifies the client.

DoT and DoH work wherever a device goes — on mobile data, in a hotel — because they don’t depend on the source address. IP suits a network with a fixed public address, such as an office.

The identifying value (identify) is unique across Dinio: one IP address, hostname or path belongs to one identity. For IP you give the address. For Hostname and Path, Dinio generates the value — 16 random characters such as k3x7q2mzr5tvb4wa — and you configure it on the device. You can replace it with a new one at any time; the old one stops working.

Give an identity a name (phone, office) to tell your identities apart. You can switch an identity off with enabled: false without deleting it: Dinio then stops recognising the client, and its lists no longer apply. Dinio can also suspend an identity; you can delete a suspended identity, but not change it or link lists to it (403 SUSPENDED).

Lists and rules

A list is a Blacklist or a Whitelist. Its rules match names in one of three ways:

Rule type	Example pattern	Matches
`Exact`	`ads.example.com`	That name only.
`Wildcard`	`*.example.com`	Every name strictly below `example.com` — not `example.com` itself.
`Regex`	`^ads[0-9]+\.example\.com$`	Names matching the regular expression, written without the trailing dot.

A list can have a name, so you can tell your lists apart (ads, kids, office). Names don’t have to be unique.

Rules can be added one by one, or many at once:

Import a file — a hosts file, a plain list of names, Adblock/AdGuard or dnsmasq rules, or Dinio’s own CSV. Merge it into the list, or make the list exactly the file.
Follow a URL — point a list at a public blocklist on the web, and Dinio downloads it and keeps the list up to date, daily or less often. Such a list takes no manual rules; keep your own in a second list.
Export a list as CSV, Adblock, hosts or plain names — to back it up, or to use it in another blocker.

A list holds up to 500 000 rules; your package sets how many lists and rules you can have. See Import and export.

Shared lists

The owner of a list can share it. Other users can then link their own identities to it — a curated block list maintained by one person, used by many. They can read its rules — to see what it blocks for them — but not change or export them. Unsharing stops new links; links that already exist stay.

How a lookup is decided

For a query from a recognised client, Dinio looks at every list linked to that client:

If a rule on any linked whitelist matches, the name is resolved normally.
Otherwise, if a rule on any linked blacklist matches, the name is blocked: Dinio answers as if it did not exist.
Otherwise the name is resolved normally.

Everything is allowed by default. A whitelist is an exception to your blacklists, not “allow only these”: to keep cdn.ads.example working while blocking *.ads.example, put the first on a whitelist and the second on a blacklist, and link both.

Filtering applies only to clients Dinio recognises through one of your identities, and only the lists linked to that identity count.

Getting started

Create a client identity for your device or network.
Create a list and add rules to it — or find a shared list you want to use.
Link the list to the identity.

The CLI does it in three commands:

dinio client create --type path --name phone   # prints the generated DoH path part
dinio sinkhole create --type blacklist --name ads --link phone
dinio sinkhole rule add ads '*.tracker.example'

Reference: API, CLI.

Statistics

Dinio counts the lookups of your clients: how many were answered, blocked or failed, the response codes, and which names were blocked most often — per client or for all of yours. How far back they reach depends on your package. See Statistics.