Skip to main content
ICMP probes ping a host on the configured interval and report one of: average round-trip latency, packet loss percentage, or plain reachability. This is the lowest-level “is this host up?” check, below HTTP / TCP / DNS. The agent shells out to the system ping binary, so ICMP needs raw-socket privilege on the agent (see below). The agent never falls back to a TCP probe when ICMP can’t run: a TCP connect tests a different layer and would hide the real failure.

​
When to use ICMP vs a TCP probe

  • ICMP tests pure network reachability to a host (router, switch, bastion, internal host). It doesn’t care whether any service is listening.
  • TCP tests that a specific port accepts connections, and runs unprivileged. If you only care that a service is up, prefer the TCP probe (no special privilege needed).
  • Many networks block ICMP entirely (cloud security groups, corporate firewalls). If pings are filtered, use TCP.

​
Privilege requirement

Sending ICMP needs a raw socket, which is privileged on every platform:
  • Linux: CAP_NET_RAW capability (or root).
  • macOS: the system ping is setuid and works without extra setup.
  • Windows: ICMP probes are not supported on the Windows binary; use a TCP probe.
The published container image cannot run ICMP probesThe image at ghcr.io/useobserver/agent is distroless and ships no ping binary, so ICMP probes in it report icmp_unavailable. Adding NET_RAW does not change that: the capability is useless without the binary. For ICMP, run the release binary on a host that has ping, or build your own image that adds iputils and grant it NET_RAW.
Wherever ping is available, grant the capability rather than running the whole agent as root.

​
systemd

​
Docker (custom image with ping)

​
Kubernetes (custom image with ping)

On a host or in a custom image without ping, install it: on Debian/Ubuntu iputils-ping, on Alpine apk add iputils. Without the binary the probe reports icmp_unavailable. When the agent lacks the privilege, the probe reports icmp_privilege_denied with a pointer to this page. It does not silently degrade to a different check.

​
Configuration shape

​
Field reference

​
Interpretations

Pick reachability for “is this host up at all”, latency for network quality, packet_loss for flaky links.

​
Reason codes

  • icmp_privilege_denied: the agent can’t open a raw socket. Grant CAP_NET_RAW and restart.
  • icmp_unavailable: no usable ping binary on the agent host. This is always the result in the published container image. Install iputils-ping / iputils, or run the release binary on the host.
  • icmp_dns_failed: the hostname didn’t resolve. Distinct from “host unreachable”. Check the name and the agent’s DNS.
  • icmp_all_timeout: every ping timed out (latency interpretation only). The host is down or ICMP is filtered. With packet_loss this reads as 100; with reachability it reads as 0.
  • icmp_error: an uncategorised ping failure. Check the agent log.

​
Troubleshooting

  • icmp_privilege_denied even after adding CAP_NET_RAW. The capability must reach the agent process, not just the container. For systemd use AmbientCapabilities (not only CapabilityBoundingSet). For Kubernetes confirm the pod’s securityContext adds NET_RAW and no policy strips it.
  • icmp_all_timeout but the host is up. The network likely blocks ICMP. Confirm with a TCP probe against a known-open port; if TCP succeeds, switch this metric to TCP.
  • icmp_dns_failed for an IP literal. Check the value isn’t mistyped; IP literals never go through DNS.