Release: Wombat

Wombat is the current DocsHub architecture.

StaxPing2 usage and configuration

Controls

Key	Action
`t`	Trace every host; press again to abort active traces.
`m`	Probe the largest working payload and estimated IPv4 MTU.
`e`	Export current state to `export.json` in the configuration directory.
`s`	Cycle sorting through config order, latency, loss, and name.
`PgUp`, `PgDn`	Move through host pages when panels exceed terminal height.
`q`, `Ctrl+C`, `Esc`	Exit.

Configuration precedence

defaults < configuration file < command-line flags

The default file is ~/.config/staxping2/config.json, respecting XDG_CONFIG_HOME. --config selects another JSON file. STAXPING_HOSTS provides comma-separated fallback hosts when the file does not define them; --host still wins.

CLI flags

Flag	Purpose	Default
`--interval <ms>`	Requested ping interval.	`1000`
`--host <hosts>`	Comma-separated hosts.	`1.1.1.1`
`--config <path>`	JSON configuration path.	Platform configuration directory
`--version`	Print the installed version.	—
`-h`, `--help`	Print command help.	—

Linux and BSD intervals are clamped to at least 200 ms. Unprivileged macOS and Windows operation is clamped to about one second; Windows ping -t has a fixed reply cadence regardless of a lower requested interval.

Configuration example

{
  "interval": 1000,
  "hosts": ["1.1.1.1", "8.8.8.8"],
  "maxSamples": 300,
  "alerts": { "latency": 100, "loss": 10 },
  "traceroute": { "enabled": true, "maxHops": 30, "probeTimeoutMs": 1500 },
  "checks": {
    "dns": { "enabled": true, "intervalMs": 30000 },
    "tcp": { "enabled": true, "ports": [443], "timeoutMs": 2000, "intervalMs": 10000 },
    "http": {
      "enabled": false,
      "timeoutMs": 3000,
      "intervalMs": 15000,
      "endpoints": [
        { "secure": true, "port": 443, "path": "/health", "expectStatus": 200 }
      ]
    },
    "probe": { "enabled": true, "maxPayload": 1472, "timeoutMs": 2000 }
  },
  "history": { "enabled": true, "maxSamples": 3600 },
  "theme": { "border": "cyan", "header": "cyan", "spark": ["cyan"] }
}

Important fields

Field	Default	Valid behavior
`maxSamples`	`300`	Live sample ring, clamped 30–3600.
`alerts.latency`	Unset	Alert threshold in milliseconds.
`alerts.loss`	Unset	Percentage from 0–100.
`traceroute.maxHops`	`30`	Clamped 1–64.
`traceroute.probeTimeoutMs`	`1500`	Clamped 500–10000 ms.
`checks.tcp.ports`	`[443]`	Ports from 1–65535.
`checks.probe.maxPayload`	`1472`	Clamped 64–8972 bytes.
`history.maxSamples`	`3600`	Per-host records, clamped 60–259200.

DNS, TCP, and HTTP checks run on independent configured cadences. HTTP endpoint objects support secure, port, path, and optional expectStatus. If HTTP checking is enabled with no endpoints, StaxPing2 checks / on port 80.

The MTU probe binary-searches payload sizes up to maxPayload. Its displayed IPv4 MTU estimate adds 28 bytes for the IPv4 and ICMP headers.

History and export

Real reply times are written to ~/.config/staxping2/history.json, respecting XDG_CONFIG_HOME, approximately every ten seconds and on clean exit. Missed packets are deliberately excluded: persisted history represents observed RTT, while current-session loss represents misses. The default buffer is roughly one hour at a one-second cadence and approximately 100 KB per host.

Pressing e writes the current statistics, outage information, samples, and latest reachability results to export.json in the same directory. Treat the export as a diagnostic snapshot, not a stable public API contract.