Documentation menu
Capabilities
What a host can honestly measure, why it differs by platform, and why a missing capability is reported rather than worked around.
Not every host can measure everything. A capability report says what this one can do, graded present, degraded or absent, each with the mechanism as the reason.
Linux
./routespear-agent -print-capabilitiesmacOS
./routespear-agent -print-capabilitiesWindows
.\routespear-agent.exe -print-capabilitiesRun it before deciding a host is a poor vantage point. Most surprises in path measurement are capability surprises.
Why this exists
The alternative is worse. A tool that quietly falls back to a weaker mechanism produces numbers that look identical to good ones, and you find out at the worst possible time, usually while presenting a graph to someone who then asks a question it cannot answer.
RouteSpear grades instead. A degraded capability produces a measurement marked degraded, so the limitation travels with the data rather than living in the head of whoever set the agent up.
The grades
Present: available and working.
Degraded: available in a reduced form, with the reduction named. The measurement is still worth taking; it just cannot claim as much.
Absent: not available, with the reason. Checks that depend on it will not run, rather than running and producing something misleading.
Flow-identifier control
The capability that matters most for path measurement, and the one people are most often surprised by.
Networks can spread traffic across multiple equal-cost paths using a hash of packet fields. Controlling those fields lets the agent keep a flow consistent within a trace and sample other flows deliberately. It does not guarantee that each flow takes a different route or that every branch is discovered.
| Recorded flow control | Meaning |
|---|---|
| Full | The transport controls the flow fields it uses. Multiple traces can sample different flows; the protocol and network still determine whether they reveal fan-out. |
| Partial | Some relevant fields are controlled, but the agent cannot guarantee full flow consistency. Discovery uses one trace. |
| None | The operating system owns the flow identifier. Discovery uses one trace and records the limitation. |
Linux UDP and TCP transports provide source-port flow control. Raw ICMP can provide full control on IPv4 when the payload has room for checksum adjustment; ICMPv6 control is partial. Datagram ICMP also reports partial control because the kernel rewrites its identifier. Even with full IPv4 control, a width of one from ICMP does not establish that the path has no branches.
Windows is not limited to its helper API. Available raw ICMP and TCP transports can provide stronger control; the helper API is a fallback with no flow-ID control. Inspect the actual transport, address family, and fidelity recorded for the measurement. A reported width of one can mean that the instrument could not observe diversity.
Concurrent hop probing
Flow control and probe scheduling are separate. Agents with discovery pipelining overlap waits for up to four TTL positions per flow by default on Linux UDP, raw ICMP, and datagram ICMP. They assemble replies in hop order. TCP, Windows helper API, and unknown transports retain sequential discovery within each flow.
New portal Path Health checks require TCP and full flow control by default.
They therefore retain sequential hop probing. Pipelining does not change the
selected protocol or improve its flow-control grade. See the
Path Health guide for hop_window, fallback, and
the distinction between discovery timing and continuous health sampling.
Platform differences
Availability depends on the operating system, privileges, drivers, and agent build.
Linux
Linux offers unprivileged UDP and TCP path transports as well as raw ICMP when the required privilege is available.
| Capability | Requires |
|---|---|
| Raw ICMP sockets | cap_net_raw or root |
| Unprivileged datagram ICMP | A permitted ping_group_range; this does not grant raw socket access |
| eBPF flow | cap_bpf and cap_perfmon, or cap_sys_admin |
| Layer 2 capture | cap_net_raw |
| WiFi scan | cap_net_admin for an active scan; without it, degraded to reading the last cached scan |
| Bluetooth LE | A powered adapter reachable through BlueZ |
The WiFi degradation is a good example of the grading being worth the trouble. A cached scan is real data that may be minutes old, which is fine for inventory and wrong for troubleshooting someone’s connection right now. Being told which one you have is the difference.
Windows
| Capability | Grade |
|---|---|
| WiFi scan | Present, needs no elevation |
| Bluetooth LE | Degraded, iBeacon works; some advertisement types and addresses are not exposed |
| eBPF flow | Absent, a Linux kernel facility |
| Layer 2 capture | Absent, needs a third-party driver |
Windows raw ICMP and TCP path measurement depend on receiving ICMP replies; the installer adds an inbound firewall rule for that purpose. Detection checks that replies actually arrive. If the stronger transports are unavailable, automatic selection can use the helper API and record the reduced fidelity. A check requiring TCP/full is refused on an agent that cannot provide it.
macOS
| Capability | Grade |
|---|---|
| WiFi scan | Present, or absent on newer releases where Apple removed the underlying tool |
| eBPF flow | Absent |
| Layer 2 capture | Absent |
| Bluetooth LE | Absent |
macOS is a good vantage point for path, HTTP, DNS and the other network checks, and a poor one for wireless and link-layer work. If you are measuring a wireless environment, put a Linux host in it.
Choosing a transport deliberately
The agent picks the best available probe transport by default. On a host you care about, pin it instead.
Automatic selection quietly succeeding with a weaker transport is convenient while evaluating and undesirable in production, where you would rather find out at startup than discover months later that a site has been measuring with less precision than you assumed. See the CLI reference.