Netmond V2. NetState service

The NetState service is a special built-in mechanism to provide actual real-time network status information.
Service enables with a Port directive. Possible parameters are TCP port number and access list for hosts authorization.


Basic algorithm and conventions

NetState service protocol is a classical text-based session oriented client-server protocol. Client connects to NetState TCP port, send requests and receive answer messages. Multiple requests possible in the same session.
Any TCP port can be used as a NetState service port. Author use 3333 as a default port number.

Client function are:

  1. Session initialization.
  2. Preparing and issuing requests.
  3. Returned data interpreting.
  4. Session closing.

Server functions are:

  1. Listen for incoming sessions on a specified port.
  2. Access control.
  3. Incoming requests parsing.
  4. Replying requested data.

Server listen specified TCP port forever. Client connects this TCP port when needed. Server check client address against their access list. If client unauthorized, server close session. Otherwise server send greeting message and wait for client request. Client send request and waiting for answer. Server parses and process request and reply answer. This can happen multiple times, until client close session, activity timeout elapsed, or error takes place.

NetState protocol request is a single string consisting of a number of keywords and a mandatory argument. Syntax conventions are:

  • Letter case in keywords ignored.
  • Argument is a REGEX statement; letter case is taking into account.
  • The whole request string is ended with CRLF.
  • Only printable ASCII letters possible in a request.
  • Request components are separated each other with any number of blanks.
  • The total request string length is up to 1024 chars.

Client and server waiting for peer side message until Timeout elapsed. Client has to send next request when server readiness string appear.

NetState protocol answer is a multistring message. Answer consists of number of status strings, and a number of meaningful data strings. Syntax conventions for answer are:

  • Each string is ended with CRLF and has up to 1024 chars.
  • Status string begins with !.
  • Strings without ! at the beginning is a data.
  • Single ! with following CRLF is an "end of answer" flag. Server waiting for a next request.
  • Single ! with following blank and a possible text string finished with CRLF is an error message.
  • Single ! with following uppercase keyword finished with CRLF is a data context switch flag. This context valid until next status string.
  • Empty answer is possible.

If requested data not found, data strings are absent in server answer. But context switch flags may present. This way user can calculate total monitored objects count, and total objects types available. with current Netmond configuration

Client close session with special command QUIT without arguments.
The only reason for server to close session is a Timeout while waiting client request.


Object types

Data is grouping by objects types in a NetState server answer. Following object types possible:

OBJECT
Basic monitoring target, parent object with IP address.
INTERFACE
Network interface, subobject of OBJECT.
SERVICE
Network service, subobject of OBJECT.
BGPAS
Autonomous system, subobject of OBJECT.
BGPPEER
BGP peer in this AS, subobject of BGPAS.
ENVMON
Environment controller Cisco, subobject of OBJECT.
ENVTEMP
Cisco thermal probe, subobject of ENVMON.

NetState protocol objects types strictly correspond to Netmond types. NetState can have and report more object types then client expect. So, client has to be ready to ignore such a data strings. NetState server reports error when client request unknown object type data.


Client-side commands

Client-side NetState protocol commands consist of:

  1. Optional command modifier.
  2. Command keyword.
  3. Command argument.

NetState protocol request is a single string consisting of a number of keywords and a mandatory argument. Request components are separated each other with any number of blanks. The total request string length is up to 1024 chars.

Letter case in keywords ignored. Argument is a REGEX statement; letter case is taking into account.

Modifiers are optional. Following modifiers are possible now:

OLD
Return previous values for requested variables.
MTIME
Return last modification time for requested variables. Modifier available if Netmond compiled with USE_VAR_MTIME option.

Command is a requested object's type keyword or an ANY keyword, matching any type of objects. So commands are:

ANY
Get all data, for all objects types.
OBJECT
Get data for objects context only
INTERFACE
Get data for interfaces.
SERVICE
Get data for service subobjects.
BGPAS
Get data for BGP autonomous system subobjects.
BGPPEER
Get data for BGP peer subobjects.
ENVMON
Get data for Cisco environment controller subobjects.
ENVTEMP
Get data for Cisco thermal probe subobjects.
QUIT
Close session.

The only QUIT command has no modifiers and arguments.

Argument is a REGEX statement. This mask filters requested objects names and variable - only matched variables reported to client.

This is sample client-side command:

Old Any .*\r\n

Here Old - is a modifier, Any - is a command, and .* - is an argument. NetState server will return previous values for all known variables, for all objects.


Returning data

Object type keywords used in requests also used as an object type switches in replies.

NetState server return variables whose name matched with REGEX and variable's parent object type match command keyword. Object type switches return for each object of this type all the time, even if no variables matched with REGEX.
This way client can count number of objects and object's types Netmond support.

Data reported as text string. String consist of full variable name and their value, separated with "=" sign:

object!subobject!variable = value

Full variable name is a full hierarchy path. Hierarchy nodes names are separated with exclamation sign !.

Variable value can be integer, float or a quoted string, for example "No error". Special untypified value Unused reported if variable is not yet evaluated.

Current variables values are reported for request without modifiers. Previous variables values are reported for request with OLD modifier.

Single ! followed by CRLF is an "end of answer" flag.


Simple session example

Here is simple NetState session example. Server replies marked by "S:" prefix, client's requests marked by "C:" prefix:


   netmon:bob:~/work> telnet localhost 3333
   Trying 127.0.0.1...
   Connected to localhost.
   Escape character is '^]'.
S: NetState server ready (timeout 30 sec.)
S: !
C: interface Octets
S: !INTERFACE
S: host-1!Serial0/0!ifInOctets = 2345522619
S: host-1!Serial0/0!ifOutOctets = 2566982883
S: !INTERFACE
S: host-1!Serial0/2!ifInOctets = 3272028327
S: host-1!Serial0/2!ifOutOctets = 1026741022
S: !
C: interface REPLY
S: !INTERFACE
S: host-1!Serial0/0!REPLYTIME = 948284131
S: !INTERFACE
S: host-1!Serial0/2!REPLYTIME = 948284131
S: !
C: old interface Octets
S: !INTERFACE
S: host-1!Serial0/0!ifInOctets = 2345415173
S: host-1!Serial0/0!ifOutOctets = 2566644924
S: !INTERFACE
S: host-1!Serial0/2!ifInOctets = 3271986926
S: host-1!Serial0/2!ifOutOctets = 1025637499
S: !
C: old interface REPLY
S: !INTERFACE
S: host-1!Serial0/0!REPLYTIME = 948284101
S: !INTERFACE
S: host-1!Serial0/2!REPLYTIME = 948284101
S: !
C: quit
   Connection closed by foreign host.


See also:
Trap directive
Internal variables

© 1998-2002, Rinet Software