A regular expression, or RegEx for short, is a pattern that can be used for building arbitrarily complex filter rules in FTLDNS.
We implement the POSIX Extended Regular Expressions similar to the one used by the UNIX
grep -E) command. We amend the regex engine by approximate blocking (compare to
agrep) and other special features like matching to specific query types only.
Our implementation is light and fast as each domain is only checked once for a match. When you query
google.com, it will be checked against your RegEx. Any subsequent query to the same domain will not be checked again until you restart
Hierarchy of regex filters in FTLDNS¶
FTLDNS uses a specific hierarchy to ensure regex filters work as you expect them to. Whitelisting always has priority over blacklisting. There are two locations where regex filters are important:
- On loading the blocking domains form the
gravitydatabase table, FTLDNS skips not only exactly whitelisted domains but also those that match enabled whitelist regex filters.
- When a queried domain matches a blacklist regex filter, the query will not be blocked if the domain also matches an exact or a regex whitelist entry.
How to use regular expressions for filtering domains¶
FTLDNS reads in regular expression filters from the two
regex database views.
To tell FTLDNS to reload the list of regex filters, either:
pihole restartdns reload-listsor
sudo killall -SIGHUP pihole-FTL) or
- Restart the service (
sudo service pihole-FTL restart)
The first command is to be preferred as it ensures that the DNS cache itself remains intact. Hence, it is also the fastest of the available options.
Pi-hole Regex debugging mode¶
To ease the usage of regular expression filters in FTLDNS, we offer a regex debugging mode. Set
/etc/pihole/pihole-FTL.conf and restart
pihole-FTL to enable or disable this mode.
Once the debugging mode is enabled, each match will be logged to
/var/log/pihole/FTL.log in the following format:
[2018-07-17 17:40:51.304] Regex blacklist (DB ID 15) >> MATCH: "whatever.twitter.com" vs. "((^)|(\.))twitter\."
The given DB ID corresponds to the ID of the corresponding row in the
domainlist database table.
Note that validation is only done on the first occurrence of a domain to increase the computational efficiency of FTLDNS. The result of this evaluation is stored in an internal DNS cache that is separate from
dnsmasq's own DNS cache. This allows us to only flush this special cache when modifying the black- and whitelists without having to flush the entire DNS cache collected so far.