Home › Documentation › Tools › gnulte
gnulte(8) — the shaping engine
The core of the suite: route a target's traffic through your machine with ARP
spoofing and impair it with real kernel tc netem — latency, jitter,
loss, duplication, reordering and bandwidth caps — while a live dashboard shows the
round-trip picture and the kernel's own queue statistics. When the run ends, a
session summary and an HTML report are filed.
Requirements
- Root. The engine re-execs itself for sudo on first launch.
tc(iproute2),iptables; thesch_netemmodule loaded or loadable.pingis not required (since v16.7);tcpdumpis not required for--capture(since v16.8).
Synopsis
gnulte [options] (prompts for sudo on first launch)
sudo gnulte [options]
Options
Every option accepts both -flag and --flag.
Targeting
| Option | Description |
|---|---|
-t, --target IP | target IP(s), comma-separated (hostnames and .local names resolve automatically) |
-m, --mac MAC | target by MAC address (resolved via ARP) |
-r, --range CIDR | target an entire subnet (e.g. 192.168.1.0/24) |
-w, --whitelist IP | exclude IP(s) from a range (comma-separated) |
--device-type KINDS | target every LAN device of these kinds (comma-separated, e.g. phone,router,printer) |
--vendor NAMES | target every LAN device by vendor name (substring, e.g. Xiaomi) |
Targets can also be picked interactively from the last LAN watch: run
gnulte with no target and press w in the picker. The
gateway and the local machine are refused as targets.
Parameters
| Option | Description |
|---|---|
-l, --latency MS | base delay in ms |
-j, --jitter MS | random variation in ms |
-p, --loss % | packet drop % |
-d, --duplicate % | duplicate packets % |
-e, --reorder % | out-of-order packets % |
-b, --bandwidth KBPS | bandwidth cap in kbps (0 = unlimited) |
Every parameter is validated before the run and its impact is estimated out loud. Caps are chained so nothing is silently dropped.
Profiles
| Option | Description |
|---|---|
--profile NAME | apply a preset (see --list-profiles: 12 built-in); save:NAME stores the current flags as a reusable profile |
--list-profiles | list the preset profiles and exit |
--random | re-roll latency/jitter/loss every second |
--scenario FILE | JSON scenario script of timed phases; see configuration |
--per-target FILE | JSON file mapping target IP → impairment override |
Watch
| Option | Description |
|---|---|
--traffic-window | with 2+ targets, open the GNULTE-LAN watch in a separate terminal window |
-q, --quiet | results only |
Advanced
| Option | Description |
|---|---|
--duration SECONDS | auto-stop after N seconds (0 = until interrupt) |
--interval SECONDS | ping every N seconds (default 1) |
-c, --capture FILE | capture target traffic to FILE as pcap (- = stdout) |
-S, --stealth | stealth ARP spoofing: answer only when asked, slow jittered cache refresh — far less visible to other scanners on the LAN |
--block | fully block the target (no forwarding) instead of shaping |
--sound / --no-sound | beep per ping result, pitch scaled by latency (default: on) |
--export FILE | stream per-second results to a CSV file |
--note TEXT | label this session (shown in the console header and the report) |
--report FILE / --no-report | write (default, to ~/GNULTE Reports/) or skip the post-test HTML report |
--probe-ports PORTS | TCP fallback probe ports when ICMP is filtered (default 443,80,53) |
--compare A B | diff two -j report JSON snapshots and exit (v16.14, unreleased); --compare-html FILE writes the diff as an HTML report |
--force | skip interactive confirmations |
--no-banner | skip the banner (alias: --minimal) |
--dupcheck | scan the LAN for duplicate IPs / ARP conflicts and exit |
--settings | open the settings editor (saved defaults) and exit |
--docs | print the safety documents and exit |
--reset-safety | remove the acceptance record and exit |
--version | print version and exit |
-h, --help | show the built-in help |
Examples
sudo gnulte # guided menu: target -> conditions -> run
sudo gnulte -t 192.168.1.50 -l 300 -j 30 --duration 90 # 300ms latency + 30ms jitter, 90s auto-stop
sudo gnulte -r 192.168.1.0/24 -w 192.168.1.100 --profile throttle --duration 600
sudo gnulte -t 192.168.1.50 --note gaming-test-3 -c session.pcap
sudo gnulte -t 192.168.1.50 -l 250 -j 40 -p 2 --scenario storm-drill.json
Sample output — the built-in profiles
Captured from gnulte --list-profiles (version 16.13):
Preset impairment profiles (latency|jitter|loss|dup|reorder|bandwidth-kbps):
gaming 1500ms jitter 300ms loss 2% dup 0% reorder 0% cap 0kbps
streaming 2500ms jitter 500ms loss 5% dup 0% reorder 0% cap 0kbps
voip 3000ms jitter 200ms loss 0% dup 0% reorder 5% cap 0kbps
throttle 500ms jitter 200ms loss 0% dup 0% reorder 0% cap 512kbps
...
nightmare 8000ms jitter 2000ms loss 25% dup 10% reorder 10% cap 0kbps
The complete list, with every column, is in configuration.
During a run
The dashboard pings every target once per second: last, min, max, average and
loss. A netem live line reads the kernel queue straight from
tc -s qdisc so you can see the hand your own network conditions are
dealing. When the run ends, the session summary rolls up min/avg/p95/max, jitter, a
loss run-length distribution and a rough E-model MOS, printed on the console and
embedded in the HTML report.
End a run with Ctrl+C: the first signal restores the previous qdisc and
ip_forward and finishes the teardown; a second forces the exit.
Installation
Part of the GNULTE suite. Build and install everything at once;
git clone https://github.com/notmicrosoft2000-cmd/gnulte-go.git
cd gnulte-go
./build.sh # builds all eight binaries, runs go vet + go test ./...
sudo ./install.sh # installs to /usr/local/bin + safety docs
installs gnulte to /usr/local/bin/gnulte. See
installation for requirements.
Common errors
must be root/ permission denied on a raw socket- Run it with
sudo. The engine re-execs itself once, but a restricted sudo setup can stop that. tc: not found/iptables: not found- Install
iproute2andiptables. These are the kernel interface for shaping and forwarding and cannot be replaced. - The target loses connectivity after a run
- A run killed with
kill -9never un-spoofed; end runs with Ctrl+C instead. If it has already happened, restart the interface (or wait for the ARP entry to expire). - The dashboard shows no results for a host
- The host filters ICMP — name the ports it does answer on with
--probe-ports.
Related tools
- gnulte-lan — find the target and hand off to the engine with ⏎
- gnulte-doctor — verify the machine before the run
- gnulte-top — measure what the shaping did to throughput
- gnulte-trace — compare the shaped path against the clean one