Home › Documentation › Troubleshooting
Troubleshooting
Run the doctor first
Almost everything that can be wrong with the machine is checked by
gnulte-doctor. It prints a PASS/WARN/FAIL table with fix-it hints,
supports --json, and exits non-zero when anything fails — so it can
gate a script:
gnulte-doctor # human table
gnulte-doctor --json # for scripts
gnulte-doctor -q # only warnings and failures
Symptoms
“Shaping does nothing — the target is unaffected”
- Was the run started as root?
sudo gnulte ...— the engine re-execs itself, but a broken sudo setup means it never gets there. - Check
tc qdisc showduring a run: anetemqdisc should be present on the egress interface. - Is
ip_forwardon? The doctor checks it; the engine also sets it for the duration of the run and restores the old value on exit. - Is the target actually routed through the machine? A target that is not on the same broadcast domain, or that pins its gateway's MAC, will not be caught by ARP spoofing.
“The target lost all connectivity”
- A run that was killed with
kill -9never got to clean up: its ARP cache was left poisoned. Fix it by restarting the target's network interface, or by waiting for the ARP entry to expire, or by running one shortgnulterun against the host and ending it with a clean Ctrl+C — the teardown un-spoofs. - Use Ctrl+C, not
SIGKILL: the first signal restores the previous qdisc andip_forwardand lets the shutdown finish; a second one forces the exit only if it is stuck.
“tc / iptables: command not found”
Install iproute2 and iptables from your distribution.
These are the kernel interfaces for shaping and forwarding; they are not optional
for gnulte and are not replaced by anything in the toolkit.
“netem: No such file or directory” / unknown qdisc
The sch_netem kernel module is not loaded. Load it with
sudo modprobe sch_netem; most distributions load it on demand when
tc asks. The doctor reports the module state explicitly.
“A host never answers the dashboard's pings”
Some devices filter ICMP. The engine falls back to TCP probes on well-known ports; pick the ports the host actually listens on:
sudo gnulte -t 192.168.1.50 --probe-ports 443,80,53 ...
“A host does not show up in a scan”
- Use
--arp(automatic as root): a device that blocks ICMP but still answers ARP — phones in doze, printers, TVs — is caught by the ARP sweep. - The kernel neighbour table is only a cache;
gnulte-scansweeps the interface subnet so the answer does not depend on prior traffic.
“gnulte-trace shows only * for every hop”
The path probes need raw ICMP sockets and therefore root; routers along the path may also rate-limit their ICMP replies, which shows up as per-hop loss rather than as total failure. Loss is part of the measurement.
“gnulte-top / flows screen: no per-host rates”
The in-process AF_PACKET counter needs a capture socket, which needs root. Run
with sudo.
“gnulte-wifi injects nothing”
- The interface must already be in monitor mode
(
airmon-ng start wlan0oriw dev wlan0 set type monitor). GNULTE does not change the interface mode itself. - Some adapters cap injection rates: a single frame rarely lands. Raise
--count.
“Permission denied” writing a report or capture
Reports go to ~/GNULTE Reports/, created with your user's ownership;
a report written from a root process is handed back to the invoking user. If you
name the file yourself (--report FILE, --capture FILE),
make sure the directory is writable by the user you started from.
“Two hosts answer for the same IP”
Check for conflicts before blaming the toolkit:
gnulte --dupcheck # scan the LAN for duplicate IPs / ARP conflicts and exit
The doctor also reports duplicate IPs as a WARN during its route checks.
“Ctrl+C takes a moment to exit”
By design: the first Ctrl+C restores the screen and terminal and runs
the full teardown (un-spoof, restore qdisc, restore ip_forward). Only a
second Ctrl+C — or a stuck teardown after the grace period — forces the
exit. Before v16.0 a hard exit could leave targets with a poisoned ARP cache.
Still stuck?
Open an issue on the
issue tracker
with the output of gnulte-doctor --json, the exact command line, your
distribution and kernel version. That is most of a diagnosis already.