Home › Documentation › Troubleshooting

Troubleshooting

Applies to GNULTE v16.13 · last updated 2026-10-15

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 show during a run: a netem qdisc should be present on the egress interface.
  • Is ip_forward on? 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 -9 never 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 short gnulte run 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 and ip_forward and 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-scan sweeps 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 wlan0 or iw 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.