From 70a4a3e3e1d1338ff9bee92b18a2d1bac6c3a0bd Mon Sep 17 00:00:00 2001
From: DL6ER <dl6er@dl6er.de>
Date: Tue, 17 Jul 2018 19:46:53 +0200
Subject: [PATCH] Add regex debugging documentation

Signed-off-by: DL6ER <dl6er@dl6er.de>
---
 docs/abbreviations.md          |  2 ++
 docs/ftldns/configfile.md      | 10 ++++++++++
 docs/ftldns/regex/debugging.md | 17 ++++++++++++++++-
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/docs/abbreviations.md b/docs/abbreviations.md
index 52e7a0e..50266f5 100644
--- a/docs/abbreviations.md
+++ b/docs/abbreviations.md
@@ -30,6 +30,8 @@
 *[GCC]: the GNU compiler collection (compiler system produced by the GNU Project supporting various programming languages)
 *[repo]: Repository on GitHub
 *[RegEx]: Regular expression
+*[Regex]: Regular expression
+*[regex]: Regular expression
 *[SQLite3]: Database engine that handles an SQL databases in a file
 *[ID]: Indentifier
 *[SSH]: Secure Shell is a cryptographic network protocol for operating network services securely over an unsecured network
diff --git a/docs/ftldns/configfile.md b/docs/ftldns/configfile.md
index 1ae6674..6b2df18 100644
--- a/docs/ftldns/configfile.md
+++ b/docs/ftldns/configfile.md
@@ -78,4 +78,14 @@ How should `FTL` reply to blocked queries?
 
 **[More details](blockingmode.md)**
 
+### REGEX_DEBUGMODE
+```
+REGEX_DEBUGMODE=false|true
+```
+
+Controls if *FTL*DNS should print extended details about regex matching into `pihole-FTL.log`.
+
+**[More details](regex/debugging.md)**
+
+
 {!abbreviations.md!}
diff --git a/docs/ftldns/regex/debugging.md b/docs/ftldns/regex/debugging.md
index 336aa70..75c195d 100644
--- a/docs/ftldns/regex/debugging.md
+++ b/docs/ftldns/regex/debugging.md
@@ -1 +1,16 @@
-# Pi-hole Regex debugging mode
\ No newline at end of file
+# Pi-hole Regex debugging mode
+To ease the usage of regular expression filters in *FTL*DNS, we offer a regex debugging mode. Set
+```
+REGEX_DEBUGMODE=true
+```
+in your `/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] DEBUG: Regex in line 2 ("((^)|(\.))twitter\.") matches "whatever.twitter.com"
+```
+The given line number corresponds to the line in the file `/etc/pihole/regex.list`.
+
+Note that validation is only done on the first occurrence of a domain to increase the computational efficiency of *FTL*DNS.
+
+{!abbreviations.md!}