diff --git a/docs/ftldns/in-depth.md b/docs/ftldns/in-depth.md index 3d29282..a6d0f49 100644 --- a/docs/ftldns/in-depth.md +++ b/docs/ftldns/in-depth.md @@ -9,6 +9,6 @@ However, this also implies that *FTL*DNS cannot bind to ports 53 (DNS) among som We specifically add the following capabilities to `pihole-FTL`: -- `CAP_NET_BIND_SERVICE`: Allows *FTl*DNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53) +- `CAP_NET_BIND_SERVICE`: Allows *FTL*DNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53) - `CAP_NET_RAW`: use RAW and PACKET sockets (we need a RAW socket for handling DHCPv6 requests) - `CAP_NET_ADMIN`: modify routing tables and other network-related operations (to allow for handling DHCP requests) diff --git a/docs/ftldns/regex.md b/docs/ftldns/regex.md new file mode 100644 index 0000000..b2fd6f9 --- /dev/null +++ b/docs/ftldns/regex.md @@ -0,0 +1,53 @@ +A regular expression, or regex for short, is a pattern that can be used for building arbitrarily complex blocking rules in *FTL*DNS. +We implement the Extended Regular Expressions flavor similar to the one used by the UNIX `egrep` (or `grep -E`) command. + +Obviously, this brief description cannot explain everything there is to know about regular expressions. For detailed information, consult one of the excelent regular expressions tutorial that are available online. + +## Language implementation +We provide a short cheat sheet for our regular expressions implementation that may come in handy when designing blocking rules. Note that this table is not complete and will be extended over time. + +### Character classes +Expression | Meaning | Example +------------ | ------------- | ----------- +`*` | Match zero, one or more of the previous | Ah* matches "Ahhhhh" or "A" +`?` | Match zero or one of the previous | Ah? matches "Al" or "Ah" +`+` | Match one or more of the previous | Ah+ matches "Ah" or "Ahhh" but not "A" +`\` | Used to escape a special character | Hungry\? matches "Hungry?" +`.` | Wildcard character, matches any character | `do.*` matches "do", dog", "door", "dot", etc. +| | `do.+` matches "dog", "door", "dot", etc. but not "do" (at wildcard with `+` requires to match at least one extra character) +`( )` | Group | See below example for alternation (`|`) +`|` | Alternation | `(Mon|Tues)day` matches "Monday" or "Tuesday" but not "Friday" or "Mond" +`[ ]` | Matches a range of characters | `[cbf]ar` matches "car", "bar", or "far" +| | `[0-9]+` matches any positive integer +| | `[a-zA-Z]` | matches ascii letters a-z (uppercase and lower case) +| | `[^0-9]` | matches any character not 0-9. +`{ }` | Matches a specified number of occurrences of the previous | `[0-9]{3}` matches any three-digit number like "315" but not "31" +| | `[0-9]{2,4}` matches two- to four-digit numbers like "12", "123", and "1234" but not "1" or "12345" +| | `[0-9]{2,}` matches any number with two or more digits like "1234567", "123456789", but not "1" +`^` | Beginning of string | `^client` matches strings that begin with "client", such as `client.server.com` but not `more.client.server.com` +| Exception: within a character range (`[]`) `^` means negation | `[^0-9]` matches any character not 0-9. +`$` | End of string | `ing$` matches "exciting" but not "ingenious" + + +### Example +We compiled an example to demonstrate the power of regex-based blocking: + +Consider the following regex: +``` +^ab.+\.com$ +``` +This pattern will block all domains that start with "ab" (`^ab`), have at least one further character (`.+`) and end in ".com" (`\.com$`). + +Examples for what would be blocked by this rule: + + - `abc.com` + - `abtest.com` + - `ab.test.com` + - `abr-------.whatever.com` + +Examples for what would not be blocked by this rule: + + - `testab.com` (the domain doesn't start with "ab") + - `tab.test.com` (the domain doesn't start with "ab") + - `ab.com` (there is no character in between "ab" and ".com") + - `test.com.something` (the domain doesn't end in ".com") diff --git a/mkdocs.yml b/mkdocs.yml index fca4da9..62acee5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,6 +26,7 @@ pages: - 'Updating': 'main/update.md' - 'FTLDNS': - 'Overview': "ftldns/index.md" + - 'RegEx blocking': "ftldns/regex.md" - 'In-depth manual': "ftldns/in-depth.md" - 'Guides': - 'Pi-hole and OpenVPN Server':