Home › Documentation › Tools › gnulte

gnulte(8) — the shaping engine

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

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; the sch_netem module loaded or loadable.
  • ping is not required (since v16.7); tcpdump is 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

OptionDescription
-t, --target IPtarget IP(s), comma-separated (hostnames and .local names resolve automatically)
-m, --mac MACtarget by MAC address (resolved via ARP)
-r, --range CIDRtarget an entire subnet (e.g. 192.168.1.0/24)
-w, --whitelist IPexclude IP(s) from a range (comma-separated)
--device-type KINDStarget every LAN device of these kinds (comma-separated, e.g. phone,router,printer)
--vendor NAMEStarget 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

OptionDescription
-l, --latency MSbase delay in ms
-j, --jitter MSrandom variation in ms
-p, --loss %packet drop %
-d, --duplicate %duplicate packets %
-e, --reorder %out-of-order packets %
-b, --bandwidth KBPSbandwidth 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

OptionDescription
--profile NAMEapply a preset (see --list-profiles: 12 built-in); save:NAME stores the current flags as a reusable profile
--list-profileslist the preset profiles and exit
--randomre-roll latency/jitter/loss every second
--scenario FILEJSON scenario script of timed phases; see configuration
--per-target FILEJSON file mapping target IP → impairment override

Watch

OptionDescription
--traffic-windowwith 2+ targets, open the GNULTE-LAN watch in a separate terminal window
-q, --quietresults only

Advanced

OptionDescription
--duration SECONDSauto-stop after N seconds (0 = until interrupt)
--interval SECONDSping every N seconds (default 1)
-c, --capture FILEcapture target traffic to FILE as pcap (- = stdout)
-S, --stealthstealth ARP spoofing: answer only when asked, slow jittered cache refresh — far less visible to other scanners on the LAN
--blockfully block the target (no forwarding) instead of shaping
--sound / --no-soundbeep per ping result, pitch scaled by latency (default: on)
--export FILEstream per-second results to a CSV file
--note TEXTlabel this session (shown in the console header and the report)
--report FILE / --no-reportwrite (default, to ~/GNULTE Reports/) or skip the post-test HTML report
--probe-ports PORTSTCP fallback probe ports when ICMP is filtered (default 443,80,53)
--compare A Bdiff two -j report JSON snapshots and exit (v16.14, unreleased); --compare-html FILE writes the diff as an HTML report
--forceskip interactive confirmations
--no-bannerskip the banner (alias: --minimal)
--dupcheckscan the LAN for duplicate IPs / ARP conflicts and exit
--settingsopen the settings editor (saved defaults) and exit
--docsprint the safety documents and exit
--reset-safetyremove the acceptance record and exit
--versionprint version and exit
-h, --helpshow 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 iproute2 and iptables. 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 -9 never 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