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:
-
Status polls can use pings to check that a node and its interfaces are reachable (see ICMP Status Determination).
-
The ICMP poll, a separate poll type, collects response statistics for each node: response time, packet loss, and jitter (see ICMP Response Statistics).
-
The ping subagent (
ping) sends pings from an agent host to the targets that you configure (see Agent-Side ICMP (Ping Subagent)).
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 |
|---|---|
|
Collect ICMP response statistics for all nodes that have collection mode Default (default: yes) |
|
Total ICMP packet size in bytes, including IP and ICMP headers (minimum: 28; default: 46, i.e. 18 bytes of payload) |
|
Timeout for ICMP ping response in milliseconds (default: 1500) |
|
Interval between ICMP polls in seconds (default: 60) |
|
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 , and set ICMP response statistic collection:
| Mode | Description |
|---|---|
Default |
Use the value of |
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 |
|---|---|
|
Last ping response time in milliseconds |
|
Average ping response time over the statistics period |
|
Minimum ping response time over the statistics period |
|
Maximum ping response time over the statistics period |
|
Packet loss percentage over the statistics period |
|
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.
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 |
Agent with the |
Default rate |
1 ping per minute for each target ( |
4 pings per minute for each target ( |
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 |
|---|---|---|
|
3000 |
Response timeout in milliseconds |
|
46 |
Total ICMP packet size in bytes, including IP and ICMP headers (minimum: 28) |
|
off |
Set Don’t Fragment flag on ICMP packets |
|
4 |
Number of ICMP packets sent per minute (range: 1-6000) |
|
on |
Automatically add targets from DCI requests |
|
86400 |
Remove inactive auto-configured targets after this many seconds |
|
3600 |
Time period in seconds for moving average calculation |
|
1 |
Minimum number of threads in the poller thread pool |
|
1024 |
Maximum number of threads in the poller thread pool |
|
Target definition in format |
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 |
|---|---|---|
|
(required) |
IP address or hostname to ping |
|
|
Response timeout in milliseconds (clamped to 100-5000) |
|
|
Total ICMP packet size in bytes, including IP and ICMP headers (minimum: 28) |
|
|
Non-zero to set the Don’t Fragment bit |
|
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 |
|---|---|
|
Average response time for the last minute |
|
Last ping response time |
|
Maximum response time for the last minute |
|
Minimum response time for the last minute |
|
Cumulative maximum response time since agent start |
|
Cumulative minimum response time since agent start |
|
Exponential moving average of response time |
|
Packet loss percentage (0-100) |
|
Average jitter in milliseconds for the last minute |
|
Exponential moving average of jitter |
|
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 |
|---|---|
|
Names of all configured and auto-registered ping targets |
|
Scan an IPv4 address range and return list of responding addresses. Default timeout: 1000 ms. If |
Icmp.Targets Table
The Icmp.Targets table provides comprehensive status of all ping targets:
| Column | Type | Description |
|---|---|---|
|
STRING |
Target IP address (key column) |
|
UINT |
Last response time (ms) |
|
UINT |
Average response time (ms) |
|
UINT |
Minimum response time (ms) |
|
UINT |
Maximum response time (ms) |
|
UINT |
Moving average of response time (ms) |
|
UINT |
Standard deviation of response time (ms) |
|
UINT |
Average jitter (ms) |
|
UINT |
Moving average of jitter (ms) |
|
UINT |
Cumulative minimum response time (ms) |
|
UINT |
Cumulative maximum response time (ms) |
|
UINT |
Packet loss percentage |
|
UINT |
Configured packet size (bytes) |
|
STRING |
Target name |
|
STRING |
Target DNS name |
|
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 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.