> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure ICMP ping probes

> Ping a host for reachability, latency, or packet loss. A layer-3 network health check.

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.

<Warning>
  **The published container image cannot run ICMP probes**

  The 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](/agent/quickstart/install-binary) on a host that
  has `ping`, or build your own image that adds `iputils` and grant it
  `NET_RAW`.
</Warning>

Wherever `ping` is available, grant the capability rather than
running the whole agent as root.

### systemd

```ini theme={null}
[Service]
AmbientCapabilities=CAP_NET_RAW
CapabilityBoundingSet=CAP_NET_RAW
```

### Docker (custom image with `ping`)

```bash theme={null}
docker run --cap-add=NET_RAW ...
```

### Kubernetes (custom image with `ping`)

```yaml theme={null}
securityContext:
  capabilities:
    add: ["NET_RAW"]
```

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

```json theme={null}
{
  "host": "db.internal",
  "count": 3,
  "timeout_ms": 1000,
  "interpretation": "latency"
}
```

## Field reference

| Field | Default | Notes |
| - | - | - |
| `host` | required | Hostname or IPv4 address. Must not start with `-`. ICMPv4 only. |
| `count` | `3` | Pings per probe, 1 to 10. Latencies are averaged across the successful ones. |
| `timeout_ms` | `1000` | Per-ping timeout, 100 to 5000 ms. On Linux it is rounded up to whole seconds (minimum 1 s). |
| `interpretation` | `latency` | What the metric value represents: `latency`, `packet_loss`, or `reachability`. |

## Interpretations

| Interpretation | Value | Threshold idea |
| - | - | - |
| `latency` | Average RTT in ms across successful pings. `no_data` (`icmp_all_timeout`) when every ping is lost. | Healthy: under 50, Unhealthy: over 200 |
| `packet_loss` | Percentage of pings that didn't return (0 to 100). | Healthy: under 1, Unhealthy: over 10 |
| `reachability` | `1` if any ping succeeded, else `0`. | Healthy: over 0, Unhealthy: under 1 |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.