Home › Documentation › Tools › gnulte-lan
gnulte-lan(8) — the LAN watch
Discover what is online, identify each device (MAC, vendor, type, hostname), and watch its down/up speed, packet rate and latency live — with alarms when a host crosses a rate or latency threshold. Passive: frames are only counted, nothing is shaped or intercepted.
Requirements
- Runs unprivileged. The flows screen (3) and the map (5) need the root capture socket and show reduced data without it.
- With no
-t, the subnet is auto-discovered (your host and the router are skipped).
Synopsis
gnulte-lan [flags]
The six screens
| Key | Screen |
|---|---|
| 1 | Hosts — live down/up speed, packet rate, latency and a health grade; every IP keeps one stable colour |
| 2 | Talkers — ranked ↓/↑ with bars and peer counts (t) |
| 3 | Flows — per-pair conversations, A ↔ B with the root socket at the centre (f) |
| 4 | Neighbours — the live ARP/neighbour table (n) |
| 5 | Map — the live interconnection map: devices as nodes, live flows as pulsing edges (m) |
| 6 | History — the session's alarms beside today's recorded up/down transitions |
Keys
| Key | Action |
|---|---|
| ↑↓ | browse hosts (one row per press; no phantom repeat) |
| ⏎ / g | hand off to gnulte -t <ip> — opens a terminal with the target loaded |
| Tab / d | host detail pane |
| 1–6 | screens (also t/f/n/m) |
| x | save the watch to the shared device store (~/.config/gnulte-go/devices.json) |
| s | sort |
| a | alarm-only view |
| o | settings editor |
| h | help |
| q / Esc | quit / peel back a pane |
Options
| Flag | Description |
|---|---|
-t IP[,IP...] | host IP(s) to watch (empty = watch the whole LAN) |
-i IFACE | network interface (default: auto-detect) |
-interval N | seconds between updates (0 = settings/1) |
-duration N | auto-stop after N seconds (0 = until interrupt) |
-history N | rate/ping samples kept per host (0 = settings/60) |
-alarm-rate N | alarm hosts above N kbps (0 = settings) |
-alarm-latency-ms N | alarm hosts above N ms average ping (0 = settings) |
-alert-debounce N | consecutive samples before an up/down transition is believed (v16.13) |
--json | emit a JSON-lines event feed on stdout: a baseline object, a per-second object of host rates and latency, and an alert per transition. All human output moves to stderr (v16.13) |
-export FILE | append per-tick samples as CSV to FILE |
--history-file FILE | up/down timeline store (default ~/.config/gnulte-go/watch-history.jsonl) |
--no-history | do not read or write the up/down timeline store |
-no-report | skip the end-of-session HTML report |
-q | quiet: no banner, plain transcript |
-version | print version and exit |
Examples
gnulte-lan # watch the whole LAN (auto-discovery)
gnulte-lan -t 192.168.1.20 --duration 60 # one host, up close
gnulte-lan --duration 60 --export watch.csv --alarm-rate 500
gnulte-lan --json | jq 'select(.kind=="alert")' # alerts only (narrative is on stderr)
Reports and history
An HTML report is written at the end of the session (suppress with
-no-report). Since v16.13 it carries a 7-day latency bar chart per host
and a blunt 0–100 health score (loss first, then drift from the host's own
baseline, spread, and up/down churn). The up/down timeline it is built from is a
plain JSONL file you can process yourself.
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-lan to /usr/local/bin/gnulte-lan. See
installation for requirements.
Common errors
- Screens 3 and 5 are empty
- The flows and map screens need the root capture socket; run with
sudo. - No alarms
- Set thresholds with
-alarm-rate/-alarm-latency-ms, or in the settings editor (o); raise-alert-debounceif a flapping host alarms constantly. - A host never appears
- With no
-tthe watch auto-discovers the subnet and skips your host and the gateway; a sleeping device that sends no traffic may only be visible on the neighbours screen.
Related tools
- gnulte — the hand-off target: test a host from the watch
- gnulte-scan — deeper identification and port scanning
- gnulte-top — the same counter without the console UI