Ping Poller LAM

The Ping Poller LAM performs either ICMP or TCP pings (based on the Java Virtual Machine permissions) to one or more sets of IP addresses and will generate a Ping Fail/Ping Success event if an IP address does not respond in time (based on the configuration file for the Ping Poller LAM).

Requirements

The Ping Poller LAM generates Ping Fail events on a per-host basis if an IP address cannot be pinged (using either ICMP or TCP) based on the configurations done in the following two files:

File	Description
`$MOOGSOFT_HOME/config/ping_poller_lam.conf`	Ping Poller LAM configuration file.
`$MOOGSOFT_HOME/bots/lambots/PingPollerLam.js`	LAMbot file that processes the event data received from the event source.

Ping method - ICMP or TCP

The Ping Poller LAM will try and perform ICMP pings by default, but in some circumstances, the Java Virtual Machine will not have permission to perform ICMP pings, and it will default to TCP pings. The ICMP permission can be granted to the JVM by running the following command as root. If the command is not run as root, it will print out the command which needs to be run as the root user.

$MOOGSOFT_HOME/bin/utils/moog_init_lams.sh --pingpollerlam

Configuration

The configuration file contains a JSON object. At the first layer of the object, the Ping Poller LAM has a parameter called config, and the object that follows configuration has all the necessary information to control the LAM.

General

Field	Type	Description
`name and class`	String	Reserved fields: do not change. Default values are `Ping Poller Monitor` and `CPingPollerMonitor`
`ping_interval`	Integer	How long to wait between each ping request (in seconds) This field can be overridden by the ping_interval field in individual sources, as well as within the source input file Default: 180 seconds.
`timeout`	Integer	The amount of time to wait for the ping response (in seconds). This field can be overridden by the timeout field in individual sources. Default: 3 seconds
`retry_interval`	Integer	How long to wait between each ping retry attempt (in seconds). This field can be overridden by the retry_interval field in individual sources. Default: 5
`max_retries`	Integer	The number of attempts to resend a ping request in case of failure, used in conjunction with retry_interval configuration. This field can be overridden by the max_retries field in individual sources. Default: 3
`num_ping_threads`	Integer	The number of worker threads to use for ping requests. Default: 7
`num_retry_threads`	Integer	The number of worker threads to use for ping retries. Default: 11
`event_on_every_poll_cycle_failure`	Boolean	Set to `false` to generate a ping failure event (PingFail) only the first time the IP cannot be pinged within max_retries attempts. Setting it to true will generate a ping failure event (PingFail) event every time an IP exhausts its max_retries ping attempts. By default it is set to `false`.
`sources`	JSON Object	A way to provide configuration overrides on a per-source basis. Each source supports multiple IP addresses in a referenced file. Child keys in this block represent the name of the source. Any properties not overriden inherit the top-level property default values. If all the IP addresses which need to be pinged can use the same configuration, they can all be put into the same file and this file can be referenced in a single 'my_sources' (for example) child block under the main 'sources' key The file referenced by the file_path property can have any file extension but the format must be as described in the section below.

An example 'sources' block which reads three sets of IP addresses from three files and for each set, a different set of properties have been overridden:

sources:
{
	firstSource:
	{
		file_path: "/home/centos/ipSet1.csv",
		file_refresh_interval: 10800,
		ping_interval: 180,
		timeout: 22,
		retry_interval: 180,
		max_retries: 3
	},
	otherSource:
	{
		file_path: "/home/centos/sourcesSet2.txt",
		file_refresh_interval: 3600,
		max_retries: 30
	},
	anotherSource:
	{
		file_path: "/home/centos/specialIpAddresses3.ips",
		file_refresh_interval: 60,
		ping_interval: 30,
		timeout: 60
	}
}

Sources input file

The format must be in the following format: <ip address> <optional ping_interval for this IP>. The file must also be visible by the process and user which runs the Ping Poller LAM.

The file can have any extension but must be a space separated format and each distinct IP must be on its own line with an optional ping_interval priority after it separated by a space character.

Only IP addresses can be put into this file; hostnames and fully qualified domain names are not supported.

If the same IP address is referenced in multiple source input files, it will only actually run against the last one.

For example:

212.103.51.11 150
87.119.82.152/30 200
62.23.218.11
87.230.46.11 250

Important

This file is re-read every file_refresh_interval seconds.

If an IP address is removed or modified while the Ping Poller LAM is running, the next time the file is re-read, the IP will be considered 'dead' and there will be no more ping attempts against it. If the IP address was modified, the new IP will be considered as an additional IP to be monitored.

If an IP is added to the file this will be considered as an additional IP to be monitored.

Behaviour

For each source block it will read all the IP addresses in the input file, and for each IP address within the 'source', it will ping the IP

If the ping succeeds, no events will be sent and the ping loop resets for this IP
If the ping fails, the retry loop (including timeouts etc) will continue until max_retries is hit
- If a ping succeeds before max_retries is hit, no events will be sent and the ping loop resets
- If all the pings fail and max_retries is hit, a PingFail event will be generated for that IP and the ping loop resets
  - If a ping attempt in the new loop succeeds, a PingSuccess event will be generated which will clear the PingFail event for the current IP
  - If event_on_every_poll_cycle_failure is true, a PingFail event will be generated every time the ping loop fails max_tries attempts, and the ping loop will reset after each one. i.e. Multiple PingFail events will be sent while the IP is un-pingable.
  - If event_on_every_poll_cycle_failure is false, no more PingFail events will be generated while the IP is failing to respond to Ping attempts, and this will only be reset once a the IP can be pinged again eventually. i.e. Only one PingFail event will be sent for the IP while it is un-pingable.

Agent and Process Log

The Agent and Process Log sections allow you to configure the following properties:

name: Maps to $Laminstancename, so that the agent field indicates events Moogsoft Onprem ingests from this LAM.
capture_log: Name and location of the LAM's capture log file, which it writes to for debugging purposes.
configuration_file: Name and location of the LAM's process log configuration file. See Configure Logging for more information.Configure Logging

Mapping

You can directly map the event fields of Ping Poller LAM with Moogsoft Onprem fields, but changes to the configuration below are not needed in most cases. The parameters of the received events are displayed in Moogsoft Onprem according to the mapping done here:

mapping:
   {
   rules:
   [
       { name: "signature",                rule: "$targetIP::PingFail" },
       { name: "source_id",                rule: "$hostIP" },
       { name: "external_id",              rule: "$targetIP" },
       { name: "manager",                  rule: "$LamInstanceName" },
       { name: "source",                   rule: "$targetIP" },
       { name: "class",                    rule: "network" },
       { name: "agent",                    rule: "$LamInstanceName" },
       { name: "agent_location",           rule: "$hostIP" },
       { name: "type",                     rule: "availability" },
       { name: "severity",                 rule: "$severity" },
       { name: "description",              rule: "$eventTypeLabel : $targetIP" },
       { name: "agent_time",               rule: "$moog_now" },
       { name: "custom_info.eventDetails", rule: "$customInfo"}
   ]
}

The above example specifies the mapping of the Ping Poller event fields with the Moogsoft Onprem fields.

Note

The signature field is used by the LAM to identify correlated events.

Service Operation Reference

Process Name	Service Name
`ping_poller_lam`	pingpollerlamd

Start the LAM Service:

service pingpollerlamd start

Stop the LAM Service:

service pingpollerlamd stop

Check the LAM Service status:

service pingpollerlamd status

Command Line Reference

To see the available optional attributes of the ping_poller_lam, run the following command:

ping_poller_lam --help

The ping_poller_lam is a command line executable, and has the following optional attributes:

Option	Description
`--config`	Points to a pathname to find the configuration file for the LAM. This is where the entire configuration for the LAM is specified.
`--help`	Displays all the command line options.
`--version`	Displays the component’s version number.
`--loglevel`	Specifies the level of debugging. By default, user gets everything. In common with all executables in Moogsoft Onprem, having it set at that level can result in a lot of output (many messages per event message processed). In all production implementations, it is recommended that log level is set to WARN. This ensures only warning, error and fatal messages are recorded.

In this section: