ICMP¶

The icmp health check is used to validate that a host responds to ICMP ping requests. The number of ping requests, the interval between the requests and maximum jitter/latency/loss values may be defined.

Configuration Keys¶

The following configuration options apply to the ICMP health check method:

Key	Type	Default
`count`	Integer	`3`
`interval`	Integer/Float	`0.25`
`icmp_timeout`	Integer/Float	`2`
`privileged`	Bool	`False`
`max_loss`	Integer	`0`
`max_latency`	Optional Integer/Float	undef
`max_jitter`	Optional Integer/Float	undef

Remote Check Options¶

As this is a remote check, the following additional options are supported:

Key	Type	Default
`host`	String	undef
`address_family`	Optional String	undef
`all_valid`	Bool	`False`

Host¶

The host field contains the IP address or hostname that the health check should be executed against. If a hostname is supplied, each health check execution will perform a DNS resolution to ensure the current IP is used.

As the hostname may resolve to multiple addresses and/or address families (eg. IPv4 and IPv6) the address_family and all_valid options can be used to control what happens in those situations.

Warning

If specifying a host name instead of an IP address, temporary DNS resolution errors will cause the health check to fail. Specify an IP address to avoid this behaviour.

Address Family¶

The address_family key is used when host is set to a hostname. Should the hostname resolve to an IPv4 and IPv6 address you may want the check to only be sent to a single address family rather than both.

The values ipv4 or ipv6 are supported. If not defined there is no filtering for IPv4 or IPv6 addresses applied.

All Valid¶

The all_valid key is used when host is set to a hostname. If the hostname resolves to multiple IP addresses and all_valid is set to True, the health check will be executed against all IP addresses available. Should the health check to any IP address fail the service will be marked as down.

If set to the default False value a successful health check from any IP address is considered valid and the service will be marked up.

Count¶

By default, 3 ping requests will be sent. The count value may be changed should you want more/less requests.

Interval¶

The interval value sets the delay being subsequent ping requests.

ICMP Timeout¶

To limit the potential response time for individual ICMP requests the icmp_timeout is used. The timeout value must be lower than the health checks timeout value * count.

Privileged¶

If set to False (the default), the Python module is used to generate the ICMP packets. If set to True the kernel will be used instead. For more information see the icmplib root privileges page on GitHub.

Max Loss¶

The max_loss option can be adjusted to allow for packet loss. The default value of 0 means no responses may be lost.

Max Latency¶

If the max_latency option is set, ping responses must be received within the supplied amount of milliseconds.

Max Jitter¶

If the max_jitter option is set, the jitter between the ping responses must be within the supplied number of milliseconds.

Examples¶

Some examples of ICMP health checks:

BasicLatencyPacket Loss Allowed

A basic configuration:

---

# The list of health checks
checks:

  - name: Example Basic ICMP Check
    description: Ensure that the IP 8.8.8.8 responds to ICMP ping requests
    args:
      method: icmp
      host: 8.8.8.8
    prefixes:
      - 192.0.2.255
    nexthop: self

To validate that latency is within 20ms across 5 pings:

---

# The list of health checks
checks:

  - name: Example ICMP Latency Check
    description: Ensure that ICMP ping requests to the IP 192.0.2.1 have a latency below 20ms across 5 pings
    args:
      method: icmp
      host: 192.0.2.1
      count: 5
      max_latency: 20
    prefixes:
      - 192.0.2.5
    nexthop: 192.0.2.254

To validate that latency is within 250ms and allow up to 50% packet loss:

---

# The list of health checks
checks:

  - name: Example ICMP Latency + Packet Loss Check
    description: Ensure that ICMP ping requests to the IP 2001:db8:ffff::5 have a latency below 250ms but allow up to 50% packet loss
    args:
      method: icmp
      host: 2001:db8:ffff::5
      count: 4
      max_latency: 250
      max_loss: 2
    prefixes:
      - 2001:db8:a::/64
    nexthop: self