Reachability detection

ProbeScope determines whether a host is up or down using a layered probing strategy, a consecutive-result threshold to suppress flapping, and a method-learning cache to keep steady-state overhead low.

Probing methods, tried in order

For a host with no explicit modifier, each ping attempt tries, in order:

1. Privileged ICMP — a raw ICMP socket (needs root, or CAP_NET_RAW on Linux).
2. Unprivileged ICMP — a datagram-based ICMP socket, no elevated privileges needed on most platforms.
3. TCP — connects to port 443 by default (or a per-host explicit port, see below); a completed TCP handshake counts as a successful probe.

Detection stops at the first method that succeeds. This chain runs automatically — you don't choose a method, ProbeScope discovers what works and remembers it (see "Method-learning cache" below).

Per-host modifiers

A host token can carry an explicit suffix to override the default chain:

• host:tcp/<port> — TCP-only, on the given port. ICMP is never tried. Useful for checking a specific service (google.com:tcp/443, internal-db:tcp/5432) rather than general host reachability.
• host:icmp — ICMP-only (privileged, then unprivileged). Never falls back to TCP.
• label=host — a purely cosmetic display label, composable with either modifier (home=1.1.1.1, work=google.com:tcp/443).

Method-learning cache

Each host remembers the last method that worked and tries it first on the next round, skipping the earlier steps in the chain. This is a preference, not a lock: a run of consecutive failures on the cached method (up to --threshold-down rounds) expires the hint, and the full chain runs again so a different working method can be rediscovered. In steady state with no root privileges, this roughly halves the socket operations per host per second compared to re-trying privileged ICMP every round.

Threshold-based up/down state

A single failed or successful ping never flips a host's displayed state on its own — that would make the display flap on ordinary packet loss. Instead:

• --threshold-down N (default 3): N consecutive failures are required before a host is declared down.
• --threshold-up N (default 3): N consecutive successes are required before a host is declared back up.

This debounced state (MonitorUp) is what drives the TUI's up/down coloring, the web console, and --db/--logging period records. The raw, non-debounced result of the most recent ping is also tracked separately and available to plugins (last_ok), so a rule can see flakiness the threshold is specifically designed to hide from the main display.

close

Detection latency is asymmetric, by nature of the probe itself

Confirming a host is down costs more wall-clock time than confirming it's up: a successful ping resolves in real round-trip time (often milliseconds), but a single failed ping can't be recognized as failed until the full --timeout elapses — there's no way to know a reply isn't coming until you've waited long enough for one. With default settings (1s interval, 3/3 threshold), that means roughly 6 seconds to confirm a host down versus roughly 2 seconds to confirm it back up. Lowering --timeout closer to --interval (tier-dependent — see the pricing page) narrows this gap.

Interface binding

--interface en0 pins every ping to a specific network interface's source IP. Without it, the OS routing table picks the interface. The default-route interface is still auto-detected and shown in the title bar/web console for situational awareness, whether or not it's the one actually pinned.