This is the documentation for the development version. There are no official binaries for it; build it from the source code in git. Download links on these pages work only after the release. For the current release, see version 7.0.

ICMP Monitoring

NetXMS uses ICMP (Internet Control Message Protocol) to check node reachability and measure network response times. ICMP ping is one of the most fundamental monitoring methods and is used both for status polling and as a data collection source.

How ICMP Monitoring Works

NetXMS uses ICMP echo requests (pings) in three ways:

The first two are server functions and need no agent on the monitored node. To select between response statistics and the ping subagent, see Response Statistics or Ping Subagent.

Server-Side ICMP Polling

By default, the NetXMS server sends ICMP pings from the server host. If an ICMP proxy is set for the node or its zone, the proxy agent sends the pings of the ICMP poll and of the status poll checks instead; the PING subagent must be loaded on the proxy (see Agent Proxies). The following server configuration variables control ICMP behavior:

Variable Description

ICMP.CollectPollStatistics

Collect ICMP response statistics for all nodes that have collection mode Default (default: yes)

ICMP.PingSize

Total ICMP packet size in bytes, including IP and ICMP headers (minimum: 28; default: 46, i.e. 18 bytes of payload)

ICMP.PingTimeout

Timeout for ICMP ping response in milliseconds (default: 1500)

ICMP.PollingInterval

Interval between ICMP polls in seconds (default: 60)

ICMP.StatisticPeriod

Number of polls used for ICMP statistics calculation (default: 60)

ICMP Response Statistics

The ICMP poll runs for each node independently of the status poll. Every ICMP.PollingInterval seconds the server sends one ping to each collection target of the node and records the result. For each target the server keeps the results of the last ICMP.StatisticPeriod polls and calculates the statistics from them. With the default values this is approximately one ping per minute and statistics for approximately the last hour. A ping that gets no response before the timeout counts as a lost packet. When the ping goes through a proxy agent, a response of 10000 from the proxy also counts as a lost packet. If the proxy agent does not answer the request or returns an error (for example, because the PING subagent is not loaded), the sample is skipped and does not count as packet loss.

To use a different polling interval for one node, set the custom attribute SysConfig:ICMP.PollingInterval on that node. Unmanaged nodes are not polled.

Enabling Collection

The server configuration variable ICMP.CollectPollStatistics sets the default for all nodes. To override it for one node, open the node properties, select Communication  ICMP, and set ICMP response statistic collection:

Mode Description

Default

Use the value of ICMP.CollectPollStatistics

On

Collect statistics for this node

Off

Do not collect statistics for this node; the ICMP poll does not run

Collection Targets

The primary IP address of the node is always a collection target. You can add more targets for the same node:

  • Additional targets: on the same property page, add IP addresses to the list Additional targets for ICMP response statistic collection. An address does not have to belong to the node. For example, add the far end of a WAN link to the router that terminates the link.

  • Interfaces: open the properties of an interface, select Polling, and enable Collect ICMP response statistic for this interface. The server then pings the IP address of that interface. Unmanaged interfaces are skipped.

Statistics are calculated separately for each target.

Reading the Statistics

For the primary IP address, the Overview tab of the node shows ICMP average response time and ICMP packet loss.

To keep history, draw graphs, or set thresholds, create DCIs with origin Internal on the node, using these metrics:

Metric Description

ICMP.ResponseTime.Last

Last ping response time in milliseconds

ICMP.ResponseTime.Average

Average ping response time over the statistics period

ICMP.ResponseTime.Min

Minimum ping response time over the statistics period

ICMP.ResponseTime.Max

Maximum ping response time over the statistics period

ICMP.PacketLoss

Packet loss percentage over the statistics period

ICMP.Jitter

Ping jitter (response time variation) over the statistics period

Without an argument, a metric returns the statistics for the primary IP address. To read another target, give it as the argument:

  • an additional target by its IP address, e.g. ICMP.ResponseTime.Average(10.0.0.1)

  • an interface by its name or object ID, e.g. ICMP.PacketLoss(eth0)

The server keeps only the current statistics window; to store history, create a DCI.

In NXSL, the same values are available as the attributes icmpLastRTT, icmpAverageRTT, icmpMinRTT, icmpMaxRTT, and icmpPacketLoss of the Node (primary IP address) and Interface classes.

Events

The ICMP poll also tracks whether the primary IP address responds. The server generates SYS_ICMP_UNREACHABLE when the address stops responding and SYS_ICMP_OK when it responds again. The state must stay the same for the required number of consecutive polls (Objects.PollCountForStatusChange, or Required poll count for status change in the node’s Polling properties) before the event is generated.

Response Statistics or Ping Subagent

Both methods measure response time and packet loss, but from different places and with different detail.

ICMP response statistics Ping subagent (ping)

Pings are sent from

The server, or the ICMP proxy of the node

The agent host where the subagent is loaded

Targets

The node’s primary IP address, its interfaces, and additional addresses set in node properties

Any address, set in the agent configuration file or added automatically from DCIs

Setup

Enabled for all nodes by default; no agent is necessary, unless an ICMP proxy is used (the proxy agent needs the ping subagent)

Agent with the ping subagent loaded

Default rate

1 ping per minute for each target (ICMP.PollingInterval)

4 pings per minute for each target (PacketRate)

Statistics window

Last 60 polls (1 hour by default)

Last minute, plus moving average and cumulative minimum and maximum

DCI origin

Internal, on the monitored node

NetXMS Agent, on the node that runs the agent

Use ICMP response statistics for response time and packet loss monitoring of every managed node, as seen from the server or the ICMP proxy of the node. Use the ping subagent when you need targets and ping rate that are configured independently of the server, or the more detailed metrics of the subagent.

The two methods do not share data. An ICMP proxy uses the on-demand Icmp.Ping metric of the ping subagent only to send each ping; the background poller statistics of the subagent are separate.

Agent-Side ICMP (Ping Subagent)

The ping subagent enables ICMP monitoring from the agent host. This is useful when you need to check reachability from a specific network location rather than from the server.

Configuration

Load the subagent and configure targets in the agent configuration file:

SubAgent = ping

[PING]
Timeout = 2000
DefaultPacketSize = 46
PacketRate = 4
Target = 10.0.0.1:gateway
Target = 8.8.8.8:dns
Target = 192.168.1.100:webserver

Configuration parameters:

Parameter Default Description

Timeout

3000

Response timeout in milliseconds

DefaultPacketSize

46

Total ICMP packet size in bytes, including IP and ICMP headers (minimum: 28)

DefaultDoNotFragmentFlag

off

Set Don’t Fragment flag on ICMP packets

PacketRate

4

Number of ICMP packets sent per minute (range: 1-6000)

AutoConfigureTargets

on

Automatically add targets from DCI requests

MaxTargetInactivityTime

86400

Remove inactive auto-configured targets after this many seconds

MovingAverageTimePeriod

3600

Time period in seconds for moving average calculation

ThreadPoolMinSize

1

Minimum number of threads in the poller thread pool

ThreadPoolMaxSize

1024

Maximum number of threads in the poller thread pool

Target

Target definition in format address[:name[:packet_size[:options]]]

Set the per-target options field to DF to enable the Don’t Fragment flag.

Agent Metrics

The ping subagent provides these metrics. Background poller metrics use the target name or IP address as the argument. The on-demand Icmp.Ping metric supports additional parameters for fine-grained control.

On-Demand Ping

Icmp.Ping(target[,timeout[,packetSize[,dontFragment[,retryCount]]]])
Argument Default Description

target

(required)

IP address or hostname to ping

timeout

Timeout config (3000)

Response timeout in milliseconds (clamped to 100-5000)

packetSize

DefaultPacketSize (46)

Total ICMP packet size in bytes, including IP and ICMP headers (minimum: 28)

dontFragment

DefaultDoNotFragmentFlag (0)

Non-zero to set the Don’t Fragment bit

retryCount

1

Number of ping attempts (minimum 1)

Returns the round-trip time in milliseconds on success, or 10000 on timeout/unreachable.

Background Poller Metrics

These metrics return values from the background ping poller, which continuously pings configured targets at the rate set by PacketRate.

Parameter Description

Icmp.AvgPingTime(target)

Average response time for the last minute

Icmp.LastPingTime(target)

Last ping response time

Icmp.MaxPingTime(target)

Maximum response time for the last minute

Icmp.MinPingTime(target)

Minimum response time for the last minute

Icmp.CumulativeMaxPingTime(target)

Cumulative maximum response time since agent start

Icmp.CumulativeMinPingTime(target)

Cumulative minimum response time since agent start

Icmp.MovingAvgPingTime(target)

Exponential moving average of response time

Icmp.PacketLoss(target)

Packet loss percentage (0-100)

Icmp.Jitter(target)

Average jitter in milliseconds for the last minute

Icmp.MovingAvgJitter(target)

Exponential moving average of jitter

Icmp.PingStdDev(target)

Standard deviation of response times for the last minute

All RTT/jitter values are in milliseconds. A value of 10000 indicates timeout or unreachable.

Lists

List Description

Icmp.Targets

Names of all configured and auto-registered ping targets

Icmp.ScanRange(startAddr,endAddr[,timeout[,includeRTT]])

Scan an IPv4 address range and return list of responding addresses. Default timeout: 1000 ms. If includeRTT is set, the response time is appended to each address in the output.

Icmp.Targets Table

The Icmp.Targets table provides comprehensive status of all ping targets:

Column Type Description

IP

STRING

Target IP address (key column)

LAST_RTT

UINT

Last response time (ms)

AVERAGE_RTT

UINT

Average response time (ms)

MIN_RTT

UINT

Minimum response time (ms)

MAX_RTT

UINT

Maximum response time (ms)

MOVING_AVERAGE_RTT

UINT

Moving average of response time (ms)

STD_DEV

UINT

Standard deviation of response time (ms)

JITTER

UINT

Average jitter (ms)

MOVING_AVERAGE_JITTER

UINT

Moving average of jitter (ms)

CMIN_RTT

UINT

Cumulative minimum response time (ms)

CMAX_RTT

UINT

Cumulative maximum response time (ms)

PACKET_LOSS

UINT

Packet loss percentage

PACKET_SIZE

UINT

Configured packet size (bytes)

NAME

STRING

Target name

DNS_NAME

STRING

Target DNS name

IS_AUTO

INT

1 if auto-registered from DCI request, 0 if from config

Dynamic Targets

Targets can also be added dynamically through DCIs. When you create a DCI using one of the background poller metrics (Icmp.AvgPingTime, Icmp.PacketLoss, etc.) with an address not in the configuration file, the agent adds it as a dynamic target (requires AutoConfigureTargets to be enabled). Icmp.Ping performs a one-shot ping and never registers targets. Auto-registered targets are removed after MaxTargetInactivityTime seconds of no DCI requests.

ICMP Status Determination

Status polls use ICMP pings in two places: to check the primary IP address of the node, and to determine the state of some interfaces. Pings go through the ICMP proxy of the node or its zone, if one is set (see Server-Side ICMP Polling). A node that is itself the proxy of its zone is pinged directly from the server.

Primary IP address. When no interface of the node is up and the agent, SNMP, and other protocol checks fail, the server pings the primary IP address before it considers the node down. If the address responds, the node stays reachable. The check is skipped when Disable usage of ICMP pings for status polling is enabled on the Polling page of the node properties.

Interface state. The server uses ICMP to determine interface state only for the pseudo-interface (named unknown) that the server creates for a node without interface information, and for manually created interfaces. For these interfaces, if the agent, SNMP, and the network device driver cannot provide the interface state, the server pings each IP address of the interface until one responds. The interface is up if an address responds and down if none responds. The ping is not used for an interface that has Disable status polling with ICMP enabled, for a loopback interface, for an interface without a unicast IP address, or when ICMP is disabled for the node. When the server does not use ICMP for an interface and the agent, SNMP, and the network device driver cannot provide its state, the poller reports Interface status cannot be determined.

A ping that cannot be performed (the proxy is not available or does not answer, or the PING subagent is not loaded on the proxy) does not count as a ping without response, and the poller output shows the reason. For an interface, the state then stays unknown. For the primary IP address, such a ping cannot keep the node reachable.

To alert on packet loss or high response times, create a DCI on one of the ICMP metrics and configure a threshold on it.

Network Path Trace

NetXMS can display the network path between the server (or another managed node) and a target node. The trace is not an ICMP traceroute: no probe packets are sent. Instead, the server walks the routing tables of managed nodes hop by hop (up to 30 hops), so the result reflects routing information already known to the server and does not include per-hop response times.

To perform a network path trace, open the object context menu on a node and select Open  Trace path with one of the options:

  • Route from NetXMS server — path from the management server to the node

  • Route from…​ — path from another selected node to this node

  • Route to…​ — path from this node to another selected node

  • L2 path from NetXMS server — layer 2 path from the management server to the node

  • L2 path from…​ — layer 2 path from another selected node to this node

  • L2 path to…​ — layer 2 path from this node to another selected node

The L2 path options show the switch-level path derived from collected topology information rather than routing tables.

Intermediate hops can only be shown for routers that are themselves managed nodes with readable routing tables.