Home › Documentation › Tools › gnulte-lan

gnulte-lan(8) — the LAN watch

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

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

KeyScreen
1Hosts — live down/up speed, packet rate, latency and a health grade; every IP keeps one stable colour
2Talkers — ranked ↓/↑ with bars and peer counts (t)
3Flows — per-pair conversations, A ↔ B with the root socket at the centre (f)
4Neighbours — the live ARP/neighbour table (n)
5Map — the live interconnection map: devices as nodes, live flows as pulsing edges (m)
6History — the session's alarms beside today's recorded up/down transitions

Keys

KeyAction
↑↓browse hosts (one row per press; no phantom repeat)
⏎ / ghand off to gnulte -t <ip> — opens a terminal with the target loaded
Tab / dhost detail pane
1–6screens (also t/f/n/m)
xsave the watch to the shared device store (~/.config/gnulte-go/devices.json)
ssort
aalarm-only view
osettings editor
hhelp
q / Escquit / peel back a pane

Options

FlagDescription
-t IP[,IP...]host IP(s) to watch (empty = watch the whole LAN)
-i IFACEnetwork interface (default: auto-detect)
-interval Nseconds between updates (0 = settings/1)
-duration Nauto-stop after N seconds (0 = until interrupt)
-history Nrate/ping samples kept per host (0 = settings/60)
-alarm-rate Nalarm hosts above N kbps (0 = settings)
-alarm-latency-ms Nalarm hosts above N ms average ping (0 = settings)
-alert-debounce Nconsecutive samples before an up/down transition is believed (v16.13)
--jsonemit 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 FILEappend per-tick samples as CSV to FILE
--history-file FILEup/down timeline store (default ~/.config/gnulte-go/watch-history.jsonl)
--no-historydo not read or write the up/down timeline store
-no-reportskip the end-of-session HTML report
-qquiet: no banner, plain transcript
-versionprint 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-debounce if a flapping host alarms constantly.
A host never appears
With no -t the 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