From d062ed2e1aa4116bb654c1f05ab8eadcddce4ec7 Mon Sep 17 00:00:00 2001 From: DL6ER Date: Sat, 5 May 2018 22:33:02 +0200 Subject: [PATCH] Add debugging instructions Signed-off-by: DL6ER --- docs/ftldns/debugging.md | 12 ++++++++++++ mkdocs.yml | 1 + 2 files changed, 13 insertions(+) create mode 100644 docs/ftldns/debugging.md diff --git a/docs/ftldns/debugging.md b/docs/ftldns/debugging.md new file mode 100644 index 0000000..066f1f4 --- /dev/null +++ b/docs/ftldns/debugging.md @@ -0,0 +1,12 @@ +Once you are used to it, you can skip most of the steps. Debugging *FTL*DNS is actually quite easy as `pihole-FTL` has been designed such that a debugger can be attached to an already running process. It can give you insights into how software (not limited to `pihole-FTL`) works. + +1. Install `screen` and `gdb` using `sudo apt-get install screen gdb` +2. Start a screen session (it will allow you to come back even if the SSH connection died) + * If you don't know about `screen`, then read about it (you *will* love it!) +3. Start a screen session using `screen` +4. Use `sudo gdb -p $(pidof pihole-FTL)` to attach the debugger to the already running `pihole-FTL` process +5. Once loading of the symbols has finished (the `(gdb)` input prompt is shown), run `handle SIGHUP nostop SIGPIPE nostop` +6. Enter `continue` to continue operation of `pihole-FTL` inside the debugger. All debugger features are now available. +7. When `pihole-FTL` has crashed, copy&paste the terminal output into a (new) issue. Also type `backtrace` and include its output. We might ask for additional information in order to isolate your particular issue. + + diff --git a/mkdocs.yml b/mkdocs.yml index dbabb98..61a0963 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,6 +26,7 @@ pages: - 'Updating': 'main/update.md' - 'FTLDNS': - 'Overview': "ftldns/index.md" + - 'Debugging FTLDNS': "ftldns/debugging.md" - 'Blocking mode': "ftldns/blockingmode.md" - 'RegEx blocking': "ftldns/regex.md" # - 'Privacy levels': "ftldns/privacy.md"