Pi-hole regex extensions¶
Only match specific query types¶
You can amend the regular expressions by special keywords added at the end to fine-tine regular expressions to match only specific query types.
dig AAAA abc
dig A abc
This allows you to do query type based black-/whitelisting.
Some user-provided examples are:
A regex blacklist entry for blocking
AAAA(in fact, everything else than
A, call it "anti-
A") requests for all clients assigned to the same group. This has been mentioned to be beneficial for devices like Chromecast. You may want to fine-tune this further to specific domains.
A regex whitelist entry used to permit
PTRlookups with the above "anti-
A regex blacklist entry to block
ANYrequest network wide.
Sometimes, it may be useful to be able to invert a regular expression altogether. Hence, we added the keyword
;invert to achieve exactly this.
will not block
abc with type
AAAA (but everything else) for the clients assigned to the same groups. This inversion is independent for the query type, e.g.
will block not block
abc but everything else.
Specify reply type¶
Pi-hole allows you to configure the reply it serves when a regular expression matches a query. This can be controlled via the
Valid options are:
;reply=nodata(an empty answer will be provided)
;reply=nxdomain("no such domain" will be provided, can cause unintended side-effects)
;reply=refused(the query will be refused)
;reply=none(the query will be silently dropped)
;reply=ip(the Pi-hole's IP address if not overwritten by
;reply=18.104.22.168(any valid IPv4 address)
;reply=fe80::1234(any valid IPv6 address)
Only one option should be specified. An exception to this rule are the last two options which may be specified at the same time to configure both an IPv4 and an IPv6 address:
- IPv4 only:
will result in
A 22.214.171.124 and
- IPv6 only:
will result in
A 0.0.0.0 and
- IPv4 and IPv6:
will result in
A 126.96.36.199 and
You can specify comments within your regex using the syntax
(?#some comment here)
The comment can contain any characters except for a closing parenthesis
) (for the sole reason being the terminating element). The text in the comment is completely ignored by the regex parser and it used solely for readability purposes.
$ pihole-FTL regex-test "doubleclick.net" "(^|\.)doubleclick\.(?#TODO: We need to maybe support more than just .net here)net$" FTL Regex test: Domain: "doubleclick.net" Regex: "(^|\.)doubleclick\.(?#TODO: We need to maybe support more than just .net here)net$" Step 1: Compiling regex filter... Compiled regex filter in 0.167 msec Step 2: Checking domain... Done in 0.032 msec MATCH
A back reference is a backslash followed by a single non-zero decimal digit
d. It matches the same sequence of characters matched by the
dth parenthesized subexpression.
"cat.foo.dog---cat%dog!foo" is matched by "(cat)\.(foo)\.(dog)---\1%\3!\2"
Another (more complex example is):
MATCH: 1234.foo.dog--1234 MATCH: 4321.foo.dog--4321 NO MATCH: 1234.foo.dog--4321
Mind that the last line gives no match as
\1 matches exactly the same sequence the first character group matched. And
4321 is not the same as
1234 even when both are valid replies for
(1234|4321) Back references are not defined for POSIX EREs (for BREs they are, surprisingly enough). We add them to ERE in the BRE style.
$ pihole-FTL regex-test "someverylongandmaybecomplexthing.foo.dog--someverylongandmaybecomplexthing" "(someverylongandmaybecomplexthing|somelesscomplexitem)\.(foo)\.(dog)--\1" FTL Regex test: Domain: "someverylongandmaybecomplexthing.foo.dog--someverylongandmaybecomplexthing" Regex: "(someverylongandmaybecomplexthing|somelesscomplexitem)\.(foo)\.(dog)--\1" Step 1: Compiling regex filter... Compiled regex filter in 0.563 msec Step 2: Checking domain... Done in 0.031 msec MATCH
More character classes for bracket expressions¶
A bracket expression specifies a set of characters by enclosing a nonempty list of items in brackets. Normally anything matching any item in the list is matched. If the list begins with
^ the meaning is negated; any character matching no item in the list is matched.
- Multiple characters:
- Character ranges:
[0-9]matches any decimal digit.
- Character classes:
[:digit:]decimal digits (0 - 9)
[:graph:]all printable characters except space
[:lower:]lower-case letters (FTL matches case-insensitive by default)
[:print:]printable characters including space
[:punct:]printable characters not space or alphanumeric
[:upper:]upper case letters (FTL matches case-insensitive by default)
Furthermore, there are two shortcuts for some character classes:
\d- Digit character (equivalent to
\D- Non-digit character (equivalent to