Debugging FTLDNS using gdb
¶
Once you are used to it, you can skip most of the steps. Debugging FTLDNS is quite easy. pihole-FTL
has been designed so that a debugger can be attached to an already running process. This will give you insights into how software (not limited to pihole-FTL
) works.
When running Pi-hole in a Docker container
If you are running Pi-hole in a Docker container, you will to perform all the steps described here inside the Docker container. You can use, e.g., docker exec -it <container_name> /bin/bash
to get a shell inside the container.
You will also need to (temporarily!) add the SYS_PTRACE
capability. This is required to allow gdb
to attach to the pihole-FTL
process inside the container. You can do this by starting the container with the --cap-add=SYS_PTRACE
option. Furthermore, you need to disable the Linux kernel's secure computing mode for the container. Add --security-opt seccomp:unconfined
in order to allow gdb
to disable address space randomization.
docker run -d --name pihole [your other options] --cap-add=SYS_PTRACE --security-opt seccomp:unconfined pihole/pihole
or, when using docker-compose
:
services:
pihole:
# your other options ...
cap_add:
- # your other added capabilities ...
- SYS_PTRACE
security_opt:
- seccomp:unconfined
Prerequirements (only required once)¶
- Install
screen
andgdb
usingsudo apt install screen gdb
(you may need to use another package manager, e.g.,yum
,dnf
orapk add
, depending on your distribution) - 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!)
- If you don't know about
- Start a screen session using
screen
-
Configure
gdb
by installing a globally valid initialization file:echo "handle SIGHUP nostop SIGPIPE nostop SIGTERM nostop SIG32 nostop SIG34 nostop SIG35 nostop SIG41 nostop" | sudo tee /root/.gdbinit
You can omit this step, however, you will have to remember to run the quoted line on every start of
gdb
in order to properly debug FTL.
Start of debugging session¶
- Use
sudo gdb -p $(cat /run/pihole-FTL.pid)
to attach the debugger to the already runningpihole-FTL
process - Once loading of the symbols has finished (the
(gdb)
input prompt is shown), entercontinue
to continue the operation ofpihole-FTL
inside the debugger. All debugger features are now available. - When
pihole-FTL
has crashed, copy & paste the terminal output into a (new) issue. Also, typebacktrace
and include its output. We might ask for additional information in order to isolate your particular issue.