Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The TUI

Six boxes, one job each. Tab cycles three layouts — classic (charts left, tables right), wide (charts across the top, tables below), tall (one column) — and boxes toggle with 1–6, collapsing cleanly when hidden. z zooms the focused box full-screen; esc restores. space freezes the frame; bytes transferred while paused are back-filled on resume, so pausing never loses accounting.

The six boxes

1 — NET

Per-NIC real-time throughput as braille area charts (rx/tx with separate gradients), plus link state, speed, duplex, MTU and addresses. Cumulative traffic shows twice: since ltop started (resettable) and since the interface came up. n switches the chart mode; the NIC cycles with a click on the header.

2 — LAN

Same-subnet devices discovered automatically (how: LAN discovery): IP, MAC, mDNS hostname, interface; gateways marked. Each neighbour shows its live connection count, current rate and accumulated bytes — the numbers link into CONNS, so “how much is going to that box” is one glance, and one enter pins the neighbour and filters CONNS to that peer.

3 / 4 — DISK I/O and DISKS

Read/write rate charts (deduplicated across stacked devices — nvme0n1 and its dm-0(root) child are one sample, not two) beside the device list: capacity bars and live per-device rates, the fs type as a dim tail after each name. On macOS the list shows mounted volumes only: VMs and simulators attach their virtual disks as host-visible synthesized devices — often a dozen or more per machine — and the host cannot see anything about their internal capacity or usage, so those rows would be pure noise. On Linux a VM’s disks never appear as host block devices (they are plain files in a filesystem), so the device tree reflects real hardware and stays the full physical tree — disk → partition → dm with unmounted rows, where LUKS/LVM layering stays readable. d expands the mount list and aims the arrow/jump keys at the disks list; i switches the chart mode. An overflowing list gets a btop-style scrollbar in its right edge — click the track to page, drag the thumb to scroll, no focus needed (the wheel already worked this way).

5 — CONNS

Every socket on the system. TCP connections show true per-connection B/s and totals; UDP “connections” are eBPF-metered (Linux, via the eBPF helper) and get the same columns. Rows carry protocol tags (tcp/udp, lan for local-peers), and closed connections linger as grayed tombstone rows for 5 seconds (tombstone_ttl_ms configurable) so a finished transfer is still readable. f cycles the filter (all → lan → tcp → udp), o cycles sorts — including proc grouping, which folds same-name processes into an expandable group head (▸ firefox ×17 with the group Σ; enter on the head collapses/expands, search hits auto-expand).

6 — PROCS

Per-process session totals for network (TCP+UDP — short-lived connections are never missed by sampling, because eBPF counts bytes at the syscall) and disk I/O, plus live rates. Exited processes stay grayed out with their captured command line; s relaunches one, or enter opens the detail panel for a copy of the exact command. r cycles sorts (net-sum → net-rate → disk-sum → disk-rate → name). Exited ledgers are evicted after 30 minutes by default (proc_exit_retention_min, 0 = keep forever).

Focus, selection, detail

  • p / c / l single-focus PROCS / CONNS / LAN: the chosen box fills the screen’s attention (the others dim to stubs). esc clears.
  • Arrow-key selection follows its process/connection/neighbour across re-sorts and group collapse — the row you watch stays the row you watch.
  • enter on a conns/procs row opens the detail panel: processes show state, uptime, full captured command line, exe/cwd, RSS and a UDP breakdown; connections show protocol, owner, lifetime, totals and rates. Inside the panel: space/t pin-tracks the row (tracked rows stay on top), k kills, s relaunches, ↑↓ moves a field cursor and y copies the selected value to the clipboard via OSC 52 (works over SSH, no X11 dependency).
  • enter on a LAN row pins the neighbour (red highlight, stays on top) and filters CONNS to that peer; repeat to unpin, esc/f clear.

/ searches by name substring across processes and connections (Tab switches the target box, enter applies, esc clears). Matches also drive sorts — a filtered PROCS view is still sorted by your chosen mode.

Kill-guard rails

k kills the selected process (or closes the socket). Killing other users’ processes requires allow_global_kill = true in the config; the default denies it.

Monitoring log

L (or start with --log) records per-process ledgers to ~/.local/state/ltop/ltop-log-<ts>.jsonl at log_interval_ms (default 60 s), sharing the same schema-v1 snapshot format as watch; retention (log_retention_days, default 7) purges old files at startup. Replay and export: --replay [--csv OUT]. Details in The data plane.

Full key bindings

KeyAction
q / Ctrl-Cquit
spacepause/resume sampling (back-fill on resume)
/search (Tab switches box, enter applies, esc clears)
mmenu: themes / settings / reset / graphs / help / quit
Escclear focus & selection; close panels
1–6toggle boxes: net, lan, disk i/o, disks, conns, procs
Tablayout classic → wide → tall
p / c / lsingle-focus procs / conns / lan
rprocs sort cycle
f / oconns filter cycle / sort cycle
enter, ←→ on a group headcollapse / expand process group
dexpand/collapse disk mount tree; arrow/jump keys then target the disks list
elan sort: ip → hostname → mac → iface
n / inet / disk chart mode
↑↓ PgUp PgDn / wheelmove selection; PgUp/PgDn page by visible height; wheel scrolls the list under the cursor; click selects
disks scrollbarclick the track to page, drag the thumb to scroll — works without focus
enter on a lan rowpin neighbour + filter CONNS to that peer
enter on a conns/procs rowdetail panel (track t/space, kill k, relaunch s, copy y)
zzoom the focused box full-screen
Home/End/g/Gjump to first/last row
Ltoggle the monitoring log
sLAN sweep on/off (main screen; in detail panels s relaunches)
+/-refresh interval ±250 ms

Settings worth knowing (all in m → settings, persisted to ~/.config/ltop/config.conf): refresh tick_ms (default 2000), tombstone TTL, the recording toggle (same as the L key), log interval/retention, sweep interval, default sort/filter modes, theme, lang, proc_expand_default (groups expanded by default), proc_exit_retention_min, allow_global_kill (exposes the k key; default off), allow_global_log (exposes the L record hotkey; default off).