ICMP Check

Pull

Synopsis

Director sends one host a number of ICMP echo requests from where it runs, and writes the result of every check itself as an ECS document: the round trips, how many echoes were lost, and the state the host is in — up or down, since when, and after how many checks. Nothing is installed on the host.

The ICMP Check is one of six service check devices, each checking one service: a Website, an HTTP Check, a TCP Check, a DNS Check, an ICMP Check, and a TLS Check.

One device, one host. A device pings one host, so every host checked has a row of its own in the fleet list, and the device's connection state says whether that host is up.

The results are the device's own. Every check writes a result, up or down, with no dataset assigned. An ICMP Check has no datasets — see Service Check Datasets.

One Director owns each device.

note

The service check devices need Director 2.2.3 or later.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: icmp_check
  tags: <string[]>
  status: <boolean>
  properties:
    address: <string>
    attempts: <numeric>
    max_loss: <numeric>
    interval: <numeric>
    timeout: <numeric>
  pipelines: <pipeline[]>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y	-	Unique numeric identifier
name	Y	-	Device name
description	N	-	Optional description
type	Y	-	Must be icmp_check
tags	N	-	Optional tags
status	N	true	Enable/disable the device

Target

Field	Required	Default	Description
address	Y	-	A host name or an IP address — not a wildcard, a URL, or host:port. An IPv6 address as it is, or in one pair of brackets

Pipeline

The device takes at most one pre-processing pipeline of its own: the device's pipeline picker in the console, pipelines: in a configuration file. Its results go through it, and through none when the device has none.

Datasets

An ICMP Check has no datasets: it writes its results directly. Traceroute is a website's dataset alone: one still assigned to the device is left out with a warning in the device's log, and the device writes its results as before.

Advanced Configuration

Field	Required	Default	Description
attempts	N	10	Echo requests a check sends, a second apart, from 1 to 100
max_loss	N	50	The share of them, in percent, that may go unanswered while the host is up, from 0 to 99
interval	N	60	Seconds between checks: a result every interval. At least 10
timeout	N	2	Seconds each echo waits for its reply, from 1 to 120

A configuration error stops the device with Configuration error, and the message names the property. A number is read whole: a fraction, or one no 32-bit integer holds, is refused, never converted.

Permission to Ping

On Linux the Director opens an unprivileged ICMP socket first, which the kernel allows for the groups net.ipv4.ping_group_range names (its ICMPv6 sockets too). systemd sets the range to every group; a distribution without it may leave it empty. Failing that, the Director uses a raw socket, which needs root or CAP_NET_RAW. macOS opens an unprivileged socket for everyone. On Windows the echoes go through the IP Helper API, which needs no privilege.

A Director that may not send echoes fails the check and says so, with Initialization error and a message that names both sockets it tried, the range, and the Director's group. It never writes the host as having lost every echo. An echo the Director's own firewall refuses is the same. An echo the network does not take (no route to the host) is lost, as one that gets no reply is.

How a Check Works

A name is resolved once a check, and every echo goes to its first address. A check takes at least attempts - 1 seconds, and up to attempts × timeout when every echo waits its timeout out. One longer than its interval delays the next, which starts a second after it ends.

The check is up when at most max_loss percent of its echoes went unanswered. Otherwise it is down, and error.type says why:

error.type	When
dns	The name does not resolve: no echo was sent
timeout, connection	Every echo was lost
loss	Some echoes were answered, but more than max_loss percent were lost

A host whose name does not resolve was sent no echo: its result has no attempt and no loss.

Results and State

Every check writes one result, with event.dataset icmp_check and definition id 12153, to the metric table:

• destination.address, ip; network.transport (icmp or ipv6-icmp).
• service_check.icmp.attempts, succeeded, loss.pct (a fraction of 1), rtt.min, avg, max, and resolve (the name's lookup).

Every result carries the state the host is in, under state.*. For the state's fields, how to alert on it, and the fields every record carries, see Results and State.

Connection States

State	When
Connected	The host is up
Connection error	It does not answer, its name does not resolve, or too many of its echoes were lost
Initialization error	The Director may not send ICMP echoes. See Permission to Ping
Configuration error	A configuration that does not validate

Console

In the console, go to Fleet Management > Devices > ICMP Check and click Add new device. The wizard's steps are:

1. General settings, as on every device, with the device's pre-processing pipeline.
2. Check settings: Address. The wizard notes that the Director needs permission to ping.
3. Advanced settings: Interval, Timeout, Attempts, and Maximum loss.
4. Review and create.

There is no Data collection step: an ICMP Check has no datasets.

Simulation

The ICMP Check is not simulated. What it writes is what its check finds, with the state the host is in, which one generic sample cannot stand in for.

Examples

Pinging a gateway every 30 seconds, with the default ten echoes a check...

devices: - id: 512300186 name: branch-gateway type: icmp_check status: true properties: address: "203.0.113.1" interval: 30