ICMP monitors

Checking that a host answers an ICMP echo request.

Purpose

An ICMP monitor checks that a host answers an ICMP echo request — the classic "ping" check. It says nothing about any particular service on that host, only whether the host itself responds at the network layer.

Use cases

• A host or device that has no HTTP or TCP service of its own to check, such as a router or a piece of network equipment.
• A basic reachability check alongside a more specific HTTP or TCP monitor on the same host, to distinguish "the host is unreachable" from "the host is up but the service on it is not."

Configuration

Required:

• Target — a bare host: a hostname or an IP address. A path separator (/ or \) in the target is refused; nothing else about the target's shape is restricted at creation, because resolution is a property of the moment a check runs, not of the configuration.
• Interval and timeout — see Concepts: states.

An ICMP monitor has no optional per-type configuration: there is no method, no expected status, and no content assertion. There is nothing in an echo response to assert about beyond whether it arrived.

Defaults

None beyond the interval and timeout every monitor type shares.

Validation

The target must be non-blank and must not contain / or \. Whether the target resolves, and whether it answers, are probe-time facts, not validation-time ones.

Probe behavior

The probe sends an ICMP echo request to the target and waits for a reply within the monitor's timeout.

Success

The check is UP when an echo reply is received within the timeout.

Failure

A failed ICMP check states one of these causes:

capability is a fact about the node, not the target: some environments restrict raw-socket access, and a node that cannot send an echo request at all reports this cause rather than a misleading timeout for every check it runs.

Evidence

A check result records the cause if it failed and the round-trip latency if it succeeded.

Latency interpretation

Latency is the round-trip time of the echo request and reply — the smallest latency figure any monitor type reports, since there is no protocol handshake or application response to wait for beyond the reply itself.

Consensus interaction

An ICMP monitor's states, and how its assigned nodes' observations become one published state, follow the same rules every monitor type does — see Concepts: consensus.

Common mistakes

• Expecting an ICMP monitor to say anything about a service running on the host — it cannot; a host that answers ping and a service that is down on that same host are two different facts, and only a monitor aimed at the service reports the second one.
• Running ICMP checks against a target whose network deliberately blocks ICMP but permits the actual service traffic — the monitor will report unreachable or timeout for a host that is, by every other measure, fine.

Troubleshooting

• Result is capability on every check from one node — the node's environment does not grant it permission to send ICMP echo requests; confirm the deployment's network policy for that node rather than treating it as the target's fault.
• Result is unreachable for a host you can ping from elsewhere — ICMP reachability is a property of the path from the probing node, not from wherever you are checking from; confirm the node's own network route to the target.

Security and network considerations

The probe runs from the nodes assigned to the monitor, so a target that answers ICMP echo requests is answering them from wherever those nodes sit on the network. Some networks and some hosts deliberately block ICMP as a matter of policy; that is a legitimate reason for this monitor type to report unreachable and is not itself a defect.

Example

target: 203.0.113.10
interval_seconds: 60
timeout_seconds: 5

Related concepts

• TCP monitors — for checking a specific service port on the same host.
• Concepts: states

This article is part of this repository and is served by the same binary, so what you read here is the documentation for the version you are running.