Sinkhole lists

Sinkhole lists decide what your clients may resolve: a blacklist blocks matching names, a whitelist lets them through even if a blacklist matches. Part of DNS filtering; needs a personal key. See How a lookup is decided.

dinio sinkhole create --type blacklist --name ads --link phone
dinio sinkhole rule add ads '*.tracker.example'
dinio sinkhole rule add ads ads.example.com
dinio sinkhole show ads

LIST is the list’s name or its uuid. Names are matched ignoring case, your own lists first. Names don’t have to be unique; when one is ambiguous, the error lists the matching uuids — use one of them.

Lists

Command
sinkhole list [--shared]	Your lists, or with --shared every shared list on the platform.
sinkhole show LIST [--all]	A list with its source, its rules and the clients you linked to it. Shows the first 500 rules; --all shows every one.
sinkhole create --type blacklist|whitelist	Create an empty list. Options below.
sinkhole rename LIST [NAME]	Rename a list; without NAME, remove its name.
sinkhole share LIST	Let other users link their clients to it. They can read its rules, not change them.
sinkhole unshare LIST	Stop new links from other users; existing ones stay.
sinkhole delete LIST	Delete a list with its rules and every link to it — for a shared list, other users’ links too. Asks for confirmation.

create takes:

Option
--name NAME	A name, so you can address the list by it.
--shared	Share it right away.
--link CLIENT	Apply it to one of your clients right away: name, identifying value or uuid. Repeatable.

Rules

Command
sinkhole rule add LIST PATTERN [--type exact|wildcard|regex]	Add a rule.
sinkhole rule update LIST (PATTERN | --id UUID) [--pattern NEW] [--type …]	Change a rule.
sinkhole rule rm LIST (PATTERN… | --id UUID)	Remove rules. Asks for confirmation.

The rule type follows from the pattern: *.example.com is a wildcard — every name strictly below example.com — and any other pattern is an exact name. A regular expression needs --type regex; write it without the trailing dot:

dinio sinkhole rule add ads '^ads[0-9]+\.example\.com$' --type regex

To empty a list, delete it; to swap all of its rules for others, import a file with --replace (below).

Import and export

dinio sinkhole import ads hosts.txt
dinio sinkhole import ads hosts.txt --replace
dinio sinkhole export ads --format adblock --file ads.txt

Command
sinkhole import LIST FILE [--replace] [--dry-run]	Add the rules of a blocklist file to a list. FILE can be - for stdin.
sinkhole export LIST [--format F] [--file PATH]	Write the list’s rules as a file, to stdout or to PATH.

import reads hosts files, plain names, *.names, Adblock/AdGuard (||name^), dnsmasq (address=/name/…) and the CSV of sinkhole export — mixed in one file too, up to 10 MiB; see Import a file for how each line becomes a rule. By default it only adds what the list doesn’t have. --replace makes the list exactly the file, removing the rules that aren’t in it; the CLI first shows how many rules would be added and removed, and asks. --dry-run only shows the report: rules found, duplicates, and lines left out, with examples.

export --format:

Format
csv (default)	type,pattern lines: every rule, imports back exactly.
adblock	||name^ and /regex/ (AdGuard Home, uBlock Origin): every rule.
hosts	0.0.0.0 name (Pi-hole): exact names only.
domains	One name per line: exact names only.

URL sources

A list can follow a public blocklist on the web: Dinio downloads the file, replaces the list’s rules with it, and refreshes it on a schedule or when you ask.

dinio sinkhole source set ads https://blocklists.example.com/hosts.txt --every 1d
dinio sinkhole refresh ads

Command
sinkhole source set LIST URL [--every DURATION] [--dry-run]	Fill the list from URL (https://, a public host) now. --every refreshes it automatically, 1d to 30d; without it, only on request. Asks for confirmation.
sinkhole source every LIST DURATION|manual	Change how often it is refreshed; manual for only on request.
sinkhole refresh LIST [--force]	Download the source now. Without --force, an unchanged file is left alone.
sinkhole source rm LIST	Remove the source. The list keeps its rules and takes manual ones again.

A list with a source takes no manual rules and no imports — the next refresh would undo them. Put your own rules in a second list and link it to the same clients. sinkhole show shows when the source was last fetched, and why it failed if it did.

Links

A link applies a list to a client. The list must be yours or shared.

Command
sinkhole link list [CLIENT]	Links of your clients, or of one client.
sinkhole link add CLIENT LIST	Apply a list to a client.
sinkhole link rm CLIENT LIST	Stop applying it. Asks for confirmation.

Here LIST can also be someone else’s shared list, by name or uuid:

dinio sinkhole list --shared
dinio sinkhole link add phone malware