Home › Documentation › Usage

Usage

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

Before you start: these tools shape, spoof, capture and inject on a live network. Only run them on networks you own or are explicitly authorised to test. If in doubt, run gnulte-doctor and read authorised use.

Quick start

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

gnulte-lan                                             # six-screen live watch (auto-discovers subnet)
gnulte-lan -t 192.168.1.20 --duration 60               # one host, up close
gnulte-scan --deep                                     # sweep + in-Go port scan + OS fingerprint
gnulte-scan --watch 5                                  # live re-scan: ▲ new ▼ gone ~ changed
gnulte-scan -T                                         # tabbed browser: Devices / Log / Summary
gnulte-devices -s                                      # instant ARP inventory + optional sweep

Recipe: shape one host and keep the evidence

A labelled run that auto-stops, records the traffic and files a report:

sudo gnulte -t 192.168.1.50 -l 250 -j 40 -p 2 \
  --duration 300 --note gaming-latency-test-3 \
  --capture session.pcap

The dashboard shows per-second ping results while the run lasts and a live netem live line straight from tc -s qdisc; when it ends, a session summary (min/avg/p95/max, jitter, loss distribution, a rough E-model MOS) is printed and the HTML report lands in ~/GNULTE Reports/.

Recipe: watch first, then test

The tools are designed to hand off to each other. Start a watch, pick the noisy host, and press ⏎ to open gnulte -t <ip> in a terminal window with that host already loaded:

gnulte-lan                    # discover and watch the whole LAN
# ... find the host, press ⏎ to test it, or x to save the watch to the device store

The device store is shared: gnulte reads it with w in the target picker, and gnulte-scan marks devices it already knows with *.

The LAN-watch screens and keys

ScreenShows
1 hostsevery host with live down/up speed, packet rate, latency and a health grade; one stable colour per IP
2 talkerstop talkers ranked with bars and peer counts
3 flowsper-pair conversations (needs the root capture socket)
4 neighboursthe ARP/neighbour table
5 mapthe live interconnection map: devices as nodes, live pairs as edges (root)
6 historythe session's alarms beside today's recorded up/down transitions

Keys: ↑↓ browse · ⏎/g hand off to gnulte -t <ip> · Tab/d detail · 1–6 (or t/f/n/m) screens · x save the watch to the shared store · s sort · a alarm-only · o settings · h help · q quit.

Recipe: motion detection with jq

Several tools emit machine-readable feeds. gnulte-scan --watch N --json prints one JSON object per sweep — a {"kind":"baseline"} object, then {"kind":"delta"} objects with the movement — while the narrative goes to stderr:

gnulte-scan --watch 5 --json | jq 'select(.kind=="delta")'

gnulte-lan --json | jq .          # JSON-lines: baseline, per-second rates + alerts
gnulte-top --json                 # one bandwidth sample as JSON
gnulte-trace --json               # the finished path table as JSON
gnulte-doctor --json              # the pre-flight report as JSON

Recipe: find what a slow network is doing to a path

sudo gnulte-trace 1.1.1.1                 # live hop-by-hop table with loss per hop
sudo gnulte-trace -m 20 --html trace.html # bounded, with a self-contained report

Ending a run

The first Ctrl+C restores the screen and lets the shutdown finish — previous qdisc and ip_forward value restored, ARP caches repaired. A second Ctrl+C (or a grace-period timeout) forces the exit if a teardown really is stuck. Do not kill -9 a shaping run: it leaves targets mid-spoof.

Per-tool flags and options: the tool directory and the command reference.