Add regex description

Signed-off-by: DL6ER <dl6er@dl6er.de>

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)

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")

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':