Input Stream Monitor (ISM) Server Reference

The Input Stream Monitor (ISM) Server allows any external tool to send text messages to NetVigil. The messages will be processed as if NetVigil ISM monitors had collected it from a log file or via SNMP trap.

While the EDF Server described in Chapter 18, "External Data Feed (EDF) Reference" inserts numeric data that is compared against warning and critical thresholds, the ISM server makes it possible to insert text strings, or messages. The messages are compared against user-specified regular expressions. (The syslog monitor actually uses the ISM Server internally when parsing for regular expressions.) When NetVigil receives a message that matches a specified regular expression, it can trigger an action, just as it does for a `regular' test. For example, you can configure NetVigil to take action when it receives a message that matches the regular expression, "Too many login failures".

These messages (as well as syslog and trap messages) are displayed on the Messages Window in NetVigil.

inserting a text message using `message.insert' where you specify the severity, and this text string shows up in the alarms window. The system does not search for any matching tests and does not trigger any events or actions.

you create a `pattern matching' (regular expression) test for a device using the Web interface (under Advanced Tests) first. Then messages are inserted via the ISM server directly and each message is tested against the regular expressions and if a match is found, an action is triggered.

The ISM Server is accessed via a text based protocol over a TCP socket. Protocol messages can be sent from programs written in C, Java, Perl or any other language.

An alternative to accessing the ISM Server directly is to use the NetVigil Perl API described in Chapter 20, "NetVigil Perl API".

19.1.1 Connecting to the Server

Communication with the ISM server consists of two phases - a connection establishment phase and a command-execution phase. The connection establishment phase is where remote client provides authentication information to the server in the form of a login id, and the corresponding password. Once the authentication information has been verified, all subsequent commands sent to the server will be executed with the permissions and privileges of the specified user.

Note that the login information provided to the EDF Server is the username and password specified in the dge.xml configuration file and not the web user login and password. On login, the user can insert data for all the devices and tests in NetVigil.

Once the connection establishment phase has been completed, the client application may send one command at a time and wait to receive a reply (possibly consisting of multiple lines of output) from the server.

A client application establishes a connection to the ISM Server by opening a TCP/IP socket, using the hostname/ip of the server that is running the monitor, and a pre-defined port number (default port number is 7659). Upon establishment of the TCP session, the server will greet the client with a welcome message following the rules outlined below. If the server is ready to accept data, it will print

at which point the remote client can send authentication information. If the server is unavailable, an error message would be printed in the form

19.1.2 Disconnecting from the Server

When the client application would like to disconnect from the NetVigil platform, it is recommended that the client issue a disconnect request (see below for appropriate command) instead of simply closing the socket connection. This will allow the server to perform proper cleanup before disconnecting the session.

Also if the NetVigil platform does not receive anything from the client the session will timeout and disconnect the client from the NetVigil platform. The default timeout is currently 2 minutes.

19.2 Command-reply Formatting Rules

The commands sent by a client and responses sent back by the server must adhere to the following formatting conventions:

Client Command Format

Each client command is composed of a single line of text terminated by a newline character. A carriage return followed by a newline (\r\n) is considered to be the same as a newline character (\n) alone.

Client commands may or may not require additional parameters. Each parameter consists of values, separated by 'pipe' symbol (|). Example command_name value1 [ | value2 | value3 .. ].

Pipe symbol (|) is not permitted as part of the value.

For each client command, the server will respond with a response code indicating success or failure, and optionally some descriptive text indication actions taken.

Command names are NOT case sensitive.

Parameters/values for any command must appear in exact order following the command. If a value is not applicable or existent for a particular command, an empty value (| |) should be provided.

Server Response Format

The server will always respond (to client initiated commands/requests) with text of the following format:

19.3 Client Commands

Provide authentication information to the server. This username and password are specified in the dge.xml configuration file.

Logout | Quit

Message.insert

Message.insert device_name | device_addr | test_name | 
test_serial | date_time | severity | message

severity is one of "ok", "warning", "error", "critical", signifying level of urgency for the message. The default severity is "ok".

message is free flowing text, up to 255 characters.

test_name and test_serial can remain blank, and the message would be inserted as a general message for the device, identified by device_name and/or device_addr.

You can also enter a free-form text message (without Message.insert) which will be processed using same rules as monitoring a log file (see Section 3.6, "Monitoring Log Files" on page 3-42. In this case the device name will be extracted using regular expressions already configured and applied in the system.If no match is found, the message will be silently ignored.