Filters

Filters

Filters are a powerful set of built-in features, that let you control exactly what domain names and IP addresses your application are allowed to connect to, and when.

This can be used to block ads, trackers, malware, or anything you don't want your applications to load, or your devices to phone home to.

dnscrypt-proxy supports several types of filters:

• blacklists: names, or patterns that will cause a query to immediately receive a REFUSED response.

• IP blacklists: block responses containing specific IP addresses. This is especially useful to block trackers, that can use many different domain names, but share a small subset of IP addresses.

• whitelists: names, or patterns that will cause a query to bypass blacklists. It will never be blocked.

Unlike cloud-based content filters, when a query is blocked, it will be blocked by dnscrypt-proxy itself. The DNS server will never see that query, and cannot log anything about the attempt.

The configuration for each of these lists can be found in the main configuration files, in the [blacklist], [ip_blacklist] and [whitelist] sections.

As an illustration, here is the [blacklist] section from the example configuration file:

  ## Path to the file of blocking rules (absolute, or relative to the same directory as the executable file)
  # blacklist_file = 'blacklist.txt'

  ## Optional path to a file logging blocked queries
  # log_file = 'blocked.log'

  ## Optional log format: tsv or ltsv (default: tsv)
  # log_format = 'tsv'

Each filter has its own dedicated log file. If no logging is necessary, the log_file definition can just be removed or commented.

The TSV format is a simple list of TAB-separated values, that is easy to read.

The LTSV format is a structured format which is more suitable for automated log processing.

Filter patterns

Filters are loaded from files sharing a common format: a text file, with one line per pattern.

Here are examples of valid name patterns:

Pattern	Result
ads.*	matches anything with an "ads." prefix
*.example.com	matches example.com and all names within that zone such as www.example.com
example.com	identical to the above
=example.com	block example.com but not *.example.com
*sex*	matches any name containing that substring
ads[0-9]*	matches any name with the prefix "ads" followed by one digit
ads*.example*	*, ? and [] can be used anywhere, but prefixes/suffixes are faster

The example.com (shorthand for *.example.com) pattern is the most common, as it will block the domain itself, but also all names within that domain.

Filters are extremely fast at matching prefixes (ads.\*), suffixes (\*.example.com or example.com) and exact matches (=example.com), even with huge set of rules.

Other pattern types are slower and should be used with moderation.

Only prefix matching and exact matching make sense for IP addresses. Therefore, rules for the IP blacklists must be

• Either complete IP addresses: [fe80::53:b2f8:d3a4:1e48] (IPv6) or 192.168.2.44 (IPv4)
• Or prefixes: 192.168.*, [fe80:53:*]

A note on whitelists

A name can be whitelisted even if it wouldn't have been blocked by a blacklist. Since whitelists have their own log file, this can be used to log only names matching specific patterns, without blocking them.

Whitelists can be useful when you use a 3rd party blacklist and you want to make sure that some domains are always accessible.

They can also be useful if you want to blacklist *.example.com but still allow api.example.com.

Public blacklists

Instead of building blacklists from scratch, you can use some of the available ones, listed here:

Public blacklists

Anybody can maintain a blacklist and share it online. Don't hesitate to do so, and to add links to that wiki page!

Time-based filters

By default, a rule has permanent validity.

However, specific rules can also be configured to only apply on certain days, or at certain times of the day.

This can be useful for parental control, or to restrict the traffic to a minimal subset of domains when no one in your house is supposed to be accessing the Internet.

In order to apply time-based rules, a schedule has to be defined. This happens in the [schedules] section of the configuration file:

[schedules]

  [schedules.'time-to-sleep']
    mon = [{after='21:00', before='7:00'}]
    tue = [{after='21:00', before='7:00'}]
    wed = [{after='21:00', before='7:00'}]
    thu = [{after='21:00', before='7:00'}]
    fri = [{after='23:00', before='7:00'}]
    sat = [{after='23:00', before='7:00'}]
    sun = [{after='21:00', before='7:00'}]

  [schedules.'work']
    mon = [{after='9:00', before='18:00'}]
    tue = [{after='9:00', before='18:00'}]
    wed = [{after='9:00', before='18:00'}]
    thu = [{after='9:00', before='18:00'}]
    fri = [{after='9:00', before='17:00'}]

Here, we define two schedules, named time-to-sleep and work. Any number of schedules can be defined.

A schedule is a set of time ranges for days of the week.

For example,

tue = [{after='21:00', before='7:00'}]

Means that the schedule time-to-sleep will be active on Tuesday, from midnight to 7:00, and from 21:00 to midnight.

Multiple time ranges can be defined for the same day:

tue = [{after='7:00', before='10:00'}, {after='17:00', before='19:00'}]

And a schedule doesn't have to be defined for every day of the week. In the above example, the sat and sun days were not specified for the work schedule.

In order to apply a rule only when a schedule is active, the rule must be followed with @ and the schedule name.

For example, the following rule in a blacklist:

*.youtube.* @time-to-sleep

would block Youtube only between 23:00 and 7:00.

In order to only allow access to some domains at specific times or on specific days, these domains can also be permanently blacklisted, and time-based exceptions will be defined in the whitelist.

Cloaking