Litmus Documentation
Full Feature Breakdown
Version 1.1.1. Two applications, one protocol — any Litmus instance can test against any other. Both are self-contained single-file executables: no .NET runtime, no installer, no dependencies.
| App | Platform | Roles |
|---|---|---|
Litmus Desktop (Litmus.exe) | Windows 10/11 x64 | Client with live chart + full server |
Litmus CLI (litmus) | Linux x64 (servers, WSL, routers) | Client, server (3-pane TUI or headless), chat relay |
Test Engine
Everything the measurement core can do — shared by both apps.
Protocols
TCP, UDP, or both sequentially (--both).
Directions
Download (server → client, default), upload, bidirectional (simultaneous).
Parallel streams
1–8 concurrent connections per test (-P), each with its own data connection; results aggregate live.
Duration / termination
Time-based (seconds to multi-day), byte-count (-n 1G), or packet-count (-k, UDP) termination modes.
Warmup omit
Exclude the first N seconds (TCP ramp-up) from final statistics (-O, default 2 s).
Bandwidth shaping
Target rate cap (-b 100, -b 2G) with smooth token-bucket pacing — turns the UDP test into a clean path-capacity/loss probe.
Data patterns
Random (seeded, integrity-verifiable), zeros, ones, 0x55/0xAA alternating, incrementing, microwave (RF-stress), high-bit, or any custom byte (custom:0xNN) — for links where payload entropy matters (compression, RF modulation).
Data integrity
CRC32 verification — per-datagram on UDP, full-stream PRNG verification on TCP. Corruption is reported, not silently ignored.
Latency & jitter
RTT measured continuously over the control channel (idle baseline + under-load), jitter per RFC 3550.
Packet loss
Per-packet sequence tracking with time-stamped loss events (UDP).
UDP specifics
Configurable packet size (-l, default 1400 B), Don't-Fragment bit (-D), configurable ramp-up period.
QoS
DSCP/ToS marking 0–63 (-S) for testing prioritization policies.
Socket buffers
OS auto-tuned by default; optional explicit pinning (--buffer <KB>) for controlled-window experiments.
Network details
Bind to a specific interface (-B), TCP connection-time measurement, TCP retransmit counters (Linux).
Live Monitoring
Three interfaces, all updating in real time while tests run.
Desktop
- Real-time OxyPlot bandwidth chart (0.5 s updates)
- Up to 4 overlaid runs for comparisons
- Live latency / jitter / loss readouts
- Per-stream progress
- Elapsed / remaining progress bar
CLI client
- Live interval readouts with smoothed rates
--plainfor log-friendly ASCII--jsonfor machine-readable results
CLI server TUI
- tmux-style 3-pane layout
- Server info: listen address, uptime, CPU, totals
- Active connections table: remote, protocol, direction, smoothed bandwidth, data, time
- Combined chat/event log with input
- Headless
--no-tuimode for services
Quality Scoring & Certification
A composite A–F grade and a scriptable six-test certification suite.
Network Quality Score weights
Certification suite (--certify)
- All six protocol × direction combinations in one run, with per-test PASS/FAIL verdicts against configurable thresholds (defaults: latency 100 ms, jitter 10 ms, loss 0.05%).
- Latency/jitter breaches are flagged WARN without failing the suite.
- Survives individual test errors (records a failed result and continues) and salvages partial results on Ctrl+C.
| Exit code | Meaning (for scripting / CI) |
|---|---|
0 | Pass |
1 | Certification fail |
2 | Error |
130 | Cancelled |
SLA reporting
Define throughput, latency, jitter, loss, and availability thresholds per circuit and get compliance percentages with headroom bars.
Reporting & Export
PDF reports are auto-generated or requested with --report — 11 designs, all with light + dark mode.
| Design | Highlight |
|---|---|
| Standard | Hero throughput banner + config/quality layout |
| Executive Summary | One-page brief with grade badge + sparkline |
| Comparison | Before/after with delta arrows + overlay chart |
| Gauge Dashboard | Semicircle gauges |
| Technical | Dense 3-column metrics |
| SLA Compliance | Per-metric pass/fail + headroom |
| Landscape | A4 landscape sidebar layout |
| Wall Certificate | Decorative certificate with shield badge |
| Timeline | Test lifecycle phases + stability analysis |
| Score Card | Radar chart of the 5 quality metrics |
| Diagnostic | Issue detection with severity + recommendations |
- Charts auto-scale axes from seconds to days; multi-day runs table samples at natural intervals instead of hundreds of pages.
- CSV / JSON export at full sample resolution.
- Robust saving: atomic writes, automatic fallback directories, collision-safe filenames; cancelled runs keep partial reports.
Discovery, Chat & Reliability
Built for LANs and engineered for long, unattended runs.
Peer discovery & chat
- LAN discovery: servers announce via UDP multicast (239.255.69.67:45678); clients list discovered peers — no IP hunting on the LAN.
- Lightweight LAN chat between Litmus instances (multicast + direct TCP), with rate limiting and message-size caps; the CLI can run as a multicast chat relay bridging interfaces (
--chat). - Server events (connections, completions, errors) stream into the same chat/log pane.
Reliability engineering
- Multi-day tests: bounded in-memory sample storage, control-channel deadlines and TCP keepalives, hung-stream backstops, full task cleanup between tests.
- Crash-proof timer paths and thread-safe multi-client stats on the server.
- Settings persistence: every option saved to JSON and restored on launch (desktop).
Technical Reference
- TCP: 256 KB application pump, NoDelay, JSON control handshake; OS-auto-tuned socket buffers.
- UDP datagram: 4 B sequence + 8 B timestamp + 4 B CRC32 + payload (1400 B default).
- Sampling: raw application-layer goodput at 100 ms resolution; displays use 0.5 s means; reports compute statistics post-omit.
- Ports: default 7201 (TCP + UDP); data connections on OS-assigned ports or a configured
--port-range.
CLI quick reference
# server (TUI)
litmus -s
# headless server: fixed data ports + log file
litmus -s --no-tui --port-range 10000-10100 --log /var/log/litmus.log
# 60 s TCP download, 8 streams
litmus -c HOST -t 60 -P 8
# upload
litmus -c HOST --upload -t 60
# shaped 300 Mbps UDP capacity probe
litmus -c HOST --udp -b 300 -t 30
# TCP+UDP, bidirectional
litmus -c HOST --both --bidir
# 6-test certification + PDF report
litmus -c HOST --certify --report
# JSON output
litmus -c HOST -J
Full flag list: litmus --help — or see the CLI flag reference on the downloads page.