SNM - System and Network Monitor

SNM Modules

SNM provides a capability of developing custom built modules and using existing or custom modules to query any device.

Five modules have been developed and included with SNM :

  • Apache statistics
  • MySQL performance
  • TCP ping (ftp, http, smtp, telnet, etc), and
  • Web page monitoring
  • DNS monitoring

Modules provided with SNM

A description, installation and configuration instructions as well as references are provided for the modules included with SNM

Module Apache statistics
File snm/lib/Apachestats.pm
Description Outputs current statistics of an apache web server
Installation

Ensure the following is in httpd.conf of the target apache server:

LoadModule status_module    libexec/apache/mod_status.so
ExtendedStatus On
 
<Location /server-status>
  SetHandler server-status
  Order deny,allow
  Deny from all
  Allow from 123.123.123.123 <-- the IP address of your SNM host
</Location>
Configuration

In a <template> in targets.xml use

  Apachestats::stats('ip_address', 'counter_type')

Where counter_type is one of:

    apache_total_hits
    apache_total_kbytes
    apache_busy_workers
    apache_idle_workers
    req_per_sec
    bytes_per_sec
    bytes_per_req
Example <template id="apache_hit_stats" module="Apachestats::stats( '%ipaddress%', 'apache_total_hits' )" data_source_type="GAUGE" />
References http://httpd.apache.org/docs/2.0/mod/mod_status.html
 
Module MySQL performance
File snm/lib/Mysqlstats.pm
Description Outputs current statistics of a mysql server
Installation

Install perl module Net-mysql:

  ppm install Net-mysql

If using MySQL on Windows XP SP2, set an exception on the firewall for MySQL (default = TCP 3306)
If the following error occurs when you try to connect from a remote host, it means there is no row in the MySQL user table with a Host value that matches the remote host: "Host ... is not allowed to connect to this MySQL server"
This can overcome by by setting up a MySQL account for the combination of remote hostname and username that you are using when trying to connect. If you do not know the IP number or hostname of the remote machine from which you are connecting, you should put a row with '%' as the Host column value in the user table. After trying to connect from the client machine, use a SELECT USER() query to see how you really did connect. (Then change the '%' in the user table row to the actual hostname that shows up in the log. Otherwise, the system maybe left insecure as it allows connections from any host for the given username.)
Configuration

In a <template> in targets.xml use

Mysqlstats::stats( 'database', 'variable', 'ip_address', 'user', 'password' );

Where: variable is one of those referenced in: http://dev.mysql.com/doc/mysql/en/server-status-variables.html
References http://search.cpan.org/dist/Net-MySQL/MySQL.pm
http://dev.mysql.com/doc/mysql/en/server-status-variables.html
 
Module MySQL status
File snm/lib/Mysqlstatus.pm
Description Outputs current status of a mysql server
Installation

Install perl modules DBI and DBD-mysql:

  ppm install DBI
  ppm install DBD-mysql

If using MySQL with firewalls, set an exception on the firewall for MySQL (default = TCP 3306)

If the following error occurs when you try to connect from a remote host, it means there is no row in the MySQL user table with a Host value that matches the remote host: "Host ... is not allowed to connect to this MySQL server"

On the MySQL Server:
You can fix this by setting up a MySQL account for the combination of remote hostname and username that you are using when trying to connect. If you do not know the IP number or hostname of the remote machine from which you are connecting, you should put a row with '%' as the Host column value in the user table. After trying to connect from the client machine, use a SELECT USER() query to see how you really did connect. (Then change the '%' in the user table row to the actual hostname that shows up in the log. Otherwise, your system is left insecure because it allows connections from any host for the given username.)

Recommendation is to create a new empty database and give a user USAGE privileges to this database (USAGE only allows running stats and basic stuff -- no selects, inserts, deletes etc):

create database DATABASE;;
grant USAGE on DATABASE to 'USERNAME'@'IP_ADDRESS' identified by 'PASSWORD';
flush privileges;

Be sure to flush privileges so that the new privileges and user are available immediately
Configuration In a <template> in targets.xml use

Mysqlstatus::status( 'database', 'variable', 'ip_address', 'user', 'password', 'port' );

Where: variable is one of those referenced in: http://dev.mysql.com/doc/mysql/en/server-status-variables.html
Author Stephen Russell
References http://dev.mysql.com/doc/mysql/en/server-status-variables.html
 
Module TCP ping
File snm/lib/Tcpping.pm
Description Outputs the latency for creating a tcp (socket) connection to a target
The tcp connection can be any port number (ftp = 21, telnet = 23, smtp = 25, http = 80, etc)
Installation Ensure perl module is installed:

ppm install IO-Socket
Configuration

In a <template> in targets.xml use

Tcpping::query('ip_address', 'port_num')
Example <template id="Tcp_ping" module="Tcpping::query( '%ipaddress%', '23' )" data_source_type="GAUGE" />
References http://www.iana.org/assignments/port-numbers
 
Module Webmon
File snm/lib/Webmon.pm
Description Outputs the latency of a valid HTTP query
The query is valid if the HTTP request returns a status code 2xx 'Success' in accordance with rfc2616.
Installation Ensure perl module is installed:

ppm install LWP-UserAgent
Configuration

In a <template> in targets.xml use

Webmon::header('url', 'time_out')

url = the identity of an Internet link or resource
time_out = The requests is aborted if no activity on the connection is observed for timeout seconds. Note: This means that the time it takes for the complete transaction might be longer
Example <template id="web_mon" module="Webmon::header( 'http://www.example.com/', '5' )" data_source_type="GAUGE" />
References http://tools.ietf.org/html/rfc2616
 
Module DNScheck
File snm/lib/DNScheck.pm
Description Outputs the latency of a valid DNS query
The DNS query is valid if the return is non-empty.
Installation Ensure perl module is installed:

ppm install Net-DNS
Configuration

In a <template> in targets.xml use

DNScheck::query( 'server_ip', 'lookuphost', 'type', 'timeout' )

server_ip = the IP address of the DNS server
lookuphost = the name of the host to look up
type = the DNS query type, either: 'NS', 'A', 'MX', 'CNAME', 'SOA', 'TXT' or 'search'
timeout = The requests is aborted if no activity on the connection is observed for timeout seconds.
Example <template id="Dns_check" module="DNScheck::query( '192.168.1.1', 'www.example.com', 'NS', '5' )" data_source_type="GAUGE" />
Author Stephen Russell
References
 
Module SHOUTcast DNAS server Status
File snm/lib/DNASstatus.pm
Description Returns statistics on a SHOUTcast DNAS server.
This does NOT work for Icecast or other shoutcast "compatible" servers.
Installation Ensure perl module LWP-UserAgent is installed:

ppm install LWP-UserAgent
Configuration

In a <template> in targets.xml use

DNASstatus::query( 'server_url', 'statistic', 'timeout' );

server_url = url for your shoutcast server including port information and WITHOUT playlist,
      e.g. http://music.shoutcastserver.com:8200
statistic = an integer between 0 and 5 where:
      0 = current_listeners
      1 = status
      2 = listener_peak
      3 = max_listeners
      4 = unique_listeners
      5 = bitrate
      All of the statistics return a value except for status,
      which will return 1 or a query failure (generating an alert).
timeout = the maximum amount of time (seconds) to wait for a connection.
Author Stephen Russell
References http://www.shoutcast.com
 

If you have a requirement for a module and need assistance, please contact the author via the SNM forum at sourceforge

How to configure Modules in SNM

When configuring the templates file (eg templates.xml), modules may be configured within each template. If modules are used, the following requirements apply:

  • Modules must be located in SNM's \lib directory.
  • The module must return a single numeric value. SNM validates this, returning UNKNOWN if invalid.
  • The module is required to exit gracefully in the event of a failure.
  • The module must be written in perl.
  • Three optional variables are avaivable within SNM to assist module parameters:
    • %ip_address% - the ip address of the target
    • %interface%  - the interface (int) as defined in the target file (eg targets.xml)
    • %community%  - the snmp community string for the target

An example is apache_hits where %ip_address% is used as a module parameter:

   <template id="Apache_hits" module="Apachestats::stats( '%ip_address%', 'apache_total_hits')"
       data_source_type="COUNTER">

It is strongly recommended to test the module before using within SNM.

For further information, refer to: How to create a SNM module and How to test and implement a SNM module

How to create a SNM module

Note: To assist in creating modules, a number have been developed and placed in SNM's /lib directory. It is recommended to use these as examples to assist in developing additional modules.

  1. Build a perl script that queries the computing device or application. To minimise development effort, take advantage of CPAN and the many other sources of libraries, modules and examples available on the Internet.
    • For success, ensure there is only one numeric value returned.
    • In the event of failure, the return of a 'plain language' reason for failure is acceptable, SNM will log this.
    • The script may use parameters to set variable query data, for example: ip_address, login and password. This will provide greater flexibility when configuring SNM.
  2. Test your script for success, also test your script for graceful completion in the event of failure.
  3. Convert your script (.pl) to a module (.pm). To assist in simplifying this, the following template and procedures have been developed: 
        ## -*- perl -*-
    package Mymodule;
    use strict;
    use warnings;
    our $VERSION = '0.00';
    use other_modules_if_required;
    sub mysubroutine {
     
      ...add query details here...
     
      return $my_query_value;
    }
    1;
    • Copy the script into the module template, ensuring the structure of the template is maintained:
    • The module must contain a package, eg: package Mymodule;
    • The query must be inside a subroutine, eg: sub mysubroutine {...}
    • The module must return a single numeric value, eg: return $my_query_value;
  4. Implement the module as per How to test and implement a SNM module

If you require assistance in developing a module, please contact the author via the SNM forum at sourceforge

How to test and implement a SNM module

  1. Install the perl module in SNM's /lib directory.
  2. Ensure the module is tested successfully on the SNM server.
    An example test script to achieve this is: 
        #!/usr/bin/perl -w
    use strict;
    use warnings;
    use FindBin;
    use lib "$FindBin::Bin/lib";
    use Mymodule;
    my $test = Mymodule::mysubroutine('192.168.1.1', 'param2', 'param3');
    print "$test\n";
  3. Run the test numerous times, cycling through each parameter, varying it for success and failure. Ensure the module behaves appropriately in all circumstances.
  4. Create a new, or modify existing SNM template (in targets.xml) as required. The template may include, for example: 
        <template id="ifUsage" module="Mymodule::mysubroutine('%ip_address%', 'param2',
	'param3')" data_source_type="GAUGE"</metric>
  5. Add the device to the target file
  6. Stop, then run SNM in test mode to validate
  7. Start SNM
  8. Configure a graph and view the results after allowing 2 * frequency time to pass
  9. Important: When SNM is installed on a Win32 server, monitor the memory and threads (using Windows Task Manager or similar) used by perl.exe.
    • If the memory continually increases over time, there is a memory leak,
    • If there is more than 1 thread used perl, hence SNM, may eventually fail.
    The thread issue is not of concern on *nix servers.
For further information, refer to: How to configure Modules in SNM

System and Network Monitor Copyright 2008 Thomas Price