Skip to content


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

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.


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.


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


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.


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.


Some examples of ICMP health checks:

A basic configuration:


# The list of health checks

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

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


# The list of health checks

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

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


# The list of health 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
      method: icmp
      host: 2001:db8:ffff::5
      count: 4
      max_latency: 250
      max_loss: 2
      - 2001:db8:a::/64
    nexthop: self