SNM - System and Network Monitor

SNM Configuration and Operation Guide

Prerequisites and Tools
Configuring SNM (Win32 and Linux)
   Setup - snm.cgi
   Setup - Configuration File
   Setup - Target File
   Setup - Graph File
How to configure Modules in SNM
How Alerts in SNM work
How Attribute Discovery works
How SNM works
Starting SNM

Prerequisites and Tools

An understanding of xml, ip networking and snmp is assumed.

  • Editing Tool:
    Komodo is used to develop SNM, hence is recommended if you do not already have a preferred editor.
  • snmp Query Tool:
    Getif for Win32 or net-snmp for Linux are recommended for the snmp querying of devices to assist in determining OIDs, etc.

Configuring SNM (Win32 and Linux)

Up to four files may require modification:

  1. <web directory>/snm.cgi
  2. Configuration File (eg. <config directory>/config.xml)
  3. Target File (eg. <config directory>/targets.xml)
  4. Graph File (eg. <config directory>/graph.xml)

When making changes to the Configuration or Target files, SNM will need to be restarted to activate the changes.
SNM does not need to be restarted for changes to Graph files, just a refresh of the web browser.

Below are details of all configuration attributes, including descriptions, limitations and examples. Each attribute is also identified as optional or mandatory. If you are new to SNM, this may seem daunting. To assist in overcoming this it is recommended to:

  1. Start with a minimal configuration of a few devices by removing or commenting out optional components
    <!-- an example of xml comments -->
    An example of prefixing "no_" to comment out: no_font="C:\WINNT\Fonts\verdana.ttf"
  2. Within a console (dos or unix command line), use the test (-t) mode when first executing SNM
  3. If test mode is successful, execute SNM in normal mode
  4. Modify config.xml, targets.xml and graphs.xml as appropriate and restart SNM as necessary. In some circumstances .rrd file may need to be deleted (SNM will create new files for you). If there are difficulties, use verbose (-v) mode and logging to assist diagnosis
  5. Upon the initial configuration stabilizing, commence expanding the targets, graphs and options as required
Setup - snm.cgi
  1. When using Apache 2 in a Win32 environment, line 1 in snm.cgi may require modification:
    • Example for Linux and Win32/IIS:  line 1:  #!/usr/bin/perl -w
    • Example for Win32/Apache2:     line 1:  #!c:/perl/bin/perl.exe -w

    so that the first line of snm.cgi points to the Perl executable

  2. Line 27 and 28 in snm.cgi may require modification:
    • For Win32: line 27: my $cfgfile_win32 = "C:\\Program Files\\snm\\config.xml";
    • For Linux: line 28: my $cfgfile_linux = "/etc/opt/snm/config.xml";

    Where: $cfgfile_xxxxx = The full path of the location of the configuration file

Note: For Win32, use \\ for directories instead of \.

Setup - Configuration File : <config directory>/config.xml

The configuration file, is a XML file with the following properties (refer to config.xml as an example):

   <opt>
    <language language="en" />
    <config directory="C:\Program Files\snm" />
    <app directory="C:\Program Files\snm" />
    <web directory="C:\Inetpub\wwwroot\snm" />
    <log file="C:\Inetpub\wwwroot\snm\snm.log" purge="7" />
    <alerts>
      <mail server="192.168.1.50" from="snm@example.com" />
      <alert id="syslog" syslogserver="mysyslogserver" syslogseverity="alert"/>
      <alert id="email" mailto="snm@example.com" />
      <alert id="logandmail" mailto="snm@example.com;admin@example.com"
      syslogserver="mysyslogserver" syslogseverity="warning"/>
    </alerts>
    <attributes frequency="24" />
    <default frequency="300" timeout="3" />
    <ping module="internal" />
    <snmp port="161" retries="2" />
    <image format="PNG" width="520" height="120"/>
    <graph font="C:\WINNT\Fonts\Verdana.ttf" font_color="555555" tab="30" />
    <rrdstep timeout="2" />
    <!-- <nix_mgt user="snm" group="snm" PID_path="/var/run/snm.pid"/> -->
   </opt>
<language>
language=
(mandatory) 		the language to present SNM in.
  • Either language="en" (English)
  • language="de" (Deutsch)
  • language="es" (Español)
  • language="fr" (Français)
  • default is "en" (English)

For Win32 users using a non-English language in SNM, the command prompt window will not display extended characters ( e.g. in 8859-1 ) properly. This is a problem with Windows console and not Perl or SNM.

Assuming a console running in a window (as opposed to running full-screen) then two things are required:
1. The default raster font used for console windows doesn't know about 8859-1 / latin-1, so change it. Use the system menu, Properties and select "Lucida Console" instead of "Raster Fonts".
2. Use the CHCP command to select the 1252 (Latin 1) codepage: CHCP 1252
Now re-run SNM in console mode and you should see the correct extended characters.

To create additional languages, refer to: How to....
<config>
directory=
(mandatory) 		the full path to a directory, where the configuration files are located. The four configuration files are: config.xml, targets.xml, graphs.xml and discover.xml.
  • Example for Win32: C:\Program Files\snm
  • Example for Linux: /etc/opt/snm
<app>
directory=
(mandatory) 		the full path to a directory, where the application files are located. Subdirectories lib and lang will be created in this directory.
  • Example for Win32: C:\Program Files\snm
  • Example for Linux: /opt/snm
<web>
directory=
(mandatory) 		the full path to a writeable directory, where the cgi and htmt template files are located. Subdirectories rrd, graphs and lang will be created in this directory.
  • Example for Win32/IIS: C:\Inetpub\wwwroot\snm
  • Example for Win32/Apache: C:\Program Files\Apache Group\Apache2\snm
  • Example for Fedora/Apache: /var/www/html/snm
  • Example for Ubuntu/Apache: /var/www/snm
<log>
file=
(recommended)		 the full path to the log file
  • Example for Win32: C:\inetpub\wwwroot\snm\log\snm.log
  • Example for Linux: /var/log/snm.log
  • If a log file is not defined, logging will not be activated.
purge=
(optional) 		The number of days before log file entries are purged.
  • A natural number, only using digits "0-9"
  • min = 1
  • max = 90
  • default = 14
<alerts>
<alerts> - <mail>
server=
(optional) 		the SMTP e-mail server that alerts are sent to.
  • server name or ip address
  • example: mail.example.com
  • Note: no mail server dictates no mail
from=
(optional) 		the e-mail address the alerts are sent from.
  • example: snm@example.com
  • default = snm@example.com
username=
(optional) 		the username to authenticate against the SMTP e-mail server
  • Use only if authentication is required for the SMTP e-mail server
  • Ensure optional perl modules Authen::SASL and MIME::Base64 are installed
password=
(optional) 		the password to authenticate against the SMTP e-mail server
  • Use only if authentication is required for the SMTP e-mail server
  • Ensure optional perl modules Authen::SASL and MIME::Base64 are installed
<alerts> - <alert>s
id=
(mandatory) 		the name of the alert:
  • must be unique
mailto=
(optional) 		the e-mail address the alerts are sent to.
  • Must be a valid e-mail address
  • Multiple e-mail addresses can be configured, separated by ; or , (no spaces)
  • example: snm@example.com
  • example: someone@example.com;someone_else@example.com
syslogserver=
(optional) 		the IP address or name of the syslog server
  • example: localhost
  • example: syslog.example.com
  • example: 192.168.1.50
syslogseverity=
(optional) 		the severity of the syslog message (align with rfc 3164)
  • Valid severities are: emerg, alert, crit, err, warning, notice, info and debug
  • example = warning
  • default = info
<attributes> How Attribute Discovery works
in_file=
(optional) 		the full path to the attributes file
  • Example for Win32: C:\Program Files\snm\discover.xml
  • Example for Linux: /etc/opt/snm/discover.xml
  • If an attributes in_file is not defined, attributes will not be activated.
out_file=
(optional) 		the file name of the attributes output file. This file will be created in each target directory the attributes are discovered.
  • Example for Win32: attributes.xml
  • Example for Linux: attributes.xml
  • default = attributes.xml
frequency=
(optional) 		The number of hours between each attribute discovery.
  • A number, only using digits "0-9"
  • default = 24 hrs
<default>
frequency=
(optional) 		the default frequency (in seconds) that data will be fed into RRD
  • minimum = 60 (1 minute)
  • maximum = 14400 (4 hours)
  • default = 300 (5 minutes)
timeout=
(optional) 		the period (in seconds) to wait for a response to a query
  • min = 1
  • max = 20
  • default = 4
<ping>
method=
(optional) 		use the internal (perl) ping library or the external (operating system) ping file
  • Example: internal
  • Example: external
  • If a ping file is not defined, the internal ping library (Net::Ping) will be used.

For Linux/Unix only: Using an external ping (e.g. /bin/ping) allows snm to be run as a non-root user
<snmp>
port=
(optional) 		the snmp agents UDP port
  • A natural number, only using digits "0-9"
  • default = 161
retries=
(optional) 		The number of times the snmp agent on the target will be queried for data
  • min = 1
  • max = 5
  • default = 2
<image>
format=
(optional) 		the image format. You may choose:
  • PNG - Portable Network Graphics
  • GIF - Graphics Interchange Format
  • IGIF - Interlaced GIF
  • default = PNG
width=
(optional) 		the WIDTH of the graphic (in pixels):
  • minimum = 100
  • maximum = 1000
  • default = 400
height=
(optional) 		the HEIGHT of the graphic (in pixels):
  • minimum = 25
  • maximum = 250
  • default = 100
<graph>
font=
(optional) 		the font path and file name used to create the graphs
  • Example: C:\WINNT\Fonts\Verdana.ttf
  • Example: /usr/share/fonts/liberation/LiberationMono-Regular.ttf
back_color=
(optional) 		the RRBBGG color to be presented by the graph font:
  • range is from 000000 (black) to FFFFFF (white)
  • default is eeeeee (light gray),
  • example: 008000 is green,
  • example: 0000FF is blue,
  • example: FF0000 in red

SEE the wc3 web colors for more information
canvas_color=
(optional) 		the RRBBGG color to be presented by the graph font:
  • range is from 000000 (black) to FFFFFF (white),
  • default is ffffff (white)
font_color=
(optional) 		the RRBBGG color to be presented by the graph font:
  • range is from 000000 (black) to FFFFFF (white),
  • default is 000000 (black)
tab=
(optional) 		the tab width (in pixels) used to create the legend in the graphs
  • A natural number, only using digits "0-9"
  • example: 30
  • default: 40
<rrdstep>
timeout=
(optional) 		"step_timeout*frequency" is the timeout value (seconds) that without getting data, rrdtool will plot 0 in the graphics.
  • minimum = 1
  • maximum = 2
  • default = 2
<nix_mgt>
user=
group=
PID_path=
(optional) 		For Linux/Unix only: Set the user, group and process IDs

Note: If you have a requirement for modifying the ownership of the SNM process when running on Linux/Unix, then <nix_mgt> will enable this. Otherwise use of <nix_mgt> is unnecessary.
Reference: Linux Tutorial - Identifiers

To set the user and group that the process is running on behalf of:
  • Example user="snm"
  • Example group="snm"

To create a PID for SNM:

  • Example PID_path="/var/run/snm.pid"

Default: user, group and process IDs are not set
Setup - Target File : <config directory>/targets.xml

Note: If the number of targets becomes too large, multiple target files can be configured, refer to: How to....

The target file is a XML format file. Additional targets should be added, one for each device required. (refer to targets.xml as an example):

     <targets>
    <target id="router_1" ip_address="127.0.0.1" community="public"
        port="161" alert="2:email" attributes="no">
      <template id="ping" ping="4" data_source_type="GAUGE" />
      <template id="sysUpTime" oid="1.3.6.1.2.1.1.3.0"
        data_source_type="GAUGE" frequency="900" />
      <template id="ifUsage" oid="1.3.6.1.2.1.2.2.1.int" data_source_type="COUNTER">
        <interface int="10.2" description="Ethernet 0 ifInOctet"
        input_min="0" input_max="10e6" />
        <interface int="16.2" description="Ethernet 0 ifOutOctet"
        input_min="0" input_max="10e6" />
      </template>
    </target>
    <target id="win_host" ip_address="192.168.1.100" version="2"
        community="public" alert="2:syslog">
      <template id="ping" ping="4" data_source_type="GAUGE" />
      <template id="sysUpTime" oid="1.3.6.1.2.1.1.3.0"
        data_source_type="GAUGE" frequency="900" />
      <template id="ifUsage" oid="1.3.6.1.2.1.2.2.1.int" data_source_type="COUNTER">
        <interface int="10.16777219" description="Ethernet 0 ifInOctet"
            input_min="0" input_max="10e6" />
        <interface int="16.16777219" description="Ethernet 0 ifOutOctet"
            input_min="0" input_max="10e6" />
      </template>
      <template id="ifErrors" oid="1.3.6.1.2.1.2.2.1.int"
        data_source_type="COUNTER" frequency="900">
        <interface int="13.16777219" description="Ethernet 0 ifInDiscard"
            input_min="0" />
        <interface int="19.16777219" description="Ethernet 0 ifOutDscard"
            input_min="0" />
        <interface int="14.16777219" description="Ethernet 0 ifInError "
            input_min="0" />
        <interface int="20.16777219" description="Ethernet 0 ifOutError "
            input_min="0" />
      </template>
      <template id="win_disk" oid="1.3.6.1.4.1.311.1.1.3.1.1.5.1.3.2.int"
        data_source_type="GAUGE" frequency="3600">
        <!-- Refer to the OID .1.3.6.1.4.1.311.1.1.3.1.1.5.1.1 to obtain
            logical disk information. -->
        <!-- If using this OID to monitor Windows 2000 disk space, remember
            to initialise diskperf -y. -->
        <interface int="67.58" description="Volume C" int_alert="lt:80:1" />
        <interface int="68.58" description="Volume D" int_alert="lt:80:1" />
        <interface int="69.58" description="Volume E" int_alert="lt:80:1" />
      </template>
      <template id="win_cpu" oid="1.3.6.1.2.1.25.3.3.1.2.int" data_source_type="GAUGE">
        <interface int="3" description="cpu load" input_min="0" input_max="100" />
      </template>
    </target>
   </targets>
  • The target file targets.xml contains one-to-many <target>s
  • Each <target> contains one-to-many <template>s
  • Each <template> contains one-to-many* <interface>s

*Note: If an interface is not configured, SNM defaults it to '0'
<target>
id=
(mandatory) 		The name of the target
  • Allowed characters are "a-zA-Z0-9_.-"
  • id must be between 1-36 characters in length
  • example: localhost
  • example: ftp.example.com
ip_address=
(mandatory) 		The ip address or name of the target
  • For IP address, format is nnn.nnn.nnn.nnn where n are natural numbers between 0 and 254
  • example: 127.0.0.1
  • example: 192.168.1.1
  • For name, format is in accordance with dns naming standards
  • example: server1
  • example: server1.example.com
version=
(optional) 		The snmp version of the target.
  • either version = 1 (snmp version 1)
  • or version = 2 (snmp version 2c)
  • or version = 3 (snmp version 3, no Authentication, no Privacy)
  • default version = 1
community=
(optional) 		The snmp read community of the target.
  • snmp v1/2c queries for this target will only be loaded if community is configured
  • Any characters are allowed
  • minimum number of characters is 1
  • maximum number of characters is 36
  • example: public
username=
(optional) 		The snmp v3 (noAuthNoPriv) username of the target.
  • snmp v3 queries for this target will only be loaded if username is configured
  • Any characters are allowed
  • minimum number of characters is 1
  • maximum number of characters is 36
  • example: public
alert=
(optional)
  • Format is: n:alertid or nU:alertid
    1. n = the number of query failures before an e-mail alert is triggered
      U (case insensitive) will also send an e-mail when the status changes from down to up
    • A natural number, only using digits "0-9"
    • min = 1
    • max = 999
    1. alertid = the id of the alert to send alerts to
    • Must be a valid alert id
    • example: logandmail
  • example: 2u:email (if there are 2 concurrent failures, send an e-mail, also send an e-mail when the status changes from down to up)
  • If this alert is not defined, no e-mail will be generated in the event of an int_alert
port=
(optional) 		The target's snmp agent UDP port
  • A natural number, only using digits "0-9"
  • The <port> in the config file will be used if not specified
  • example: 161
attributes=
(optional) 		When <attributes> is set in the config file (e.g. config.xml), attributes are discovered on all targets using the first <suite> unless:
  • a non-default <suite> is set, example: attributes="another_suite" or,
  • multiple suites can be discovered, example: attributes="suite1,suite2", or
  • target discovery is excluded by setting attributes="no" or "n".

Refer to: How Attribute Discovery works
<template>
id=
(mandatory) 		The name of the template
  • Within each target, each template id must be unique
  • Allowed characters are "a-zA-Z0-9_.-"
  • id must be between 1-20 characters in length
  • Hint: use the snmp OID text name (ie MIB)
  • example: ifInOctets
  • example: iis_web_hits
ping= or
oid= or
module=
(mandatory)

The type of query ( ping, oid, or module ) and the value to query.

  1. ping
    The number of pings used to collect ping statistics
    • A natural number, only using digits "0-9"
    • Value must be between 1-20
    • default = 4
  2. oid
    The snmp OID in dotted number format, excluding "int"
    • Allowed characters are "0-9."
    • Where an interface ID forms part of the OID, the special characters "int" are used.
    • The int (as per the target file) replaces "int" when SNM processing occurs.
    • example: 1.3.6.1.2.1.2.2.1.10.int
    • example: 1.3.6.1.4.1.9.2.1.58.int
  3. module
    The program line to execute the module's subroutine, including parameters
    • The program line parameters may include any of the SNM variables %ip_address%, %metric% and %community%
    • Refer to: How to configure Modules in SNM for more information
    • example:
      Apachestats::stats( '%ip_address%', 'apache_total_hits')
 
data_source_type=
(recommended) 		 The type of data returned from a query - refer to rrdtool documentation
  • either GAUGE is for things like temperatures or value of a share,
  • or COUNTER is for continuous incrementing counters like the InOctets counter in a router.
  • or DERIVE will store the derivative of the line going from the last to the current value of the data source. DERIVE works exactly like COUNTER but without overflow checks.
  • or ABSOLUTE is for counters which get reset upon reading.
  • default is COUNTER
frequency=
(optional) 		The frequency this template for the target will be queried in seconds.
  • A natural number, only using digits "0-9"
  • min = 60 seconds
  • max = 3600 seconds
  • else the default value <frequency_default> will be used.
<interface>
int=
(recommended) 		The interface or sub-interface to be measured
  • snmp oid format, only using characters "0-9" and "."
  • must be between 1-16 characters in length
  • example: 5
  • example 5.3.212
  • default = 0
description=
(optional) 		A description of the interface
  • displayed in alerts (web page and e-mails) to assist in identifying the interface
input_max= and input_min=
(recommended) 		If input_min and/or input_max are defined, any value outside the defined range will be regarded as *UNKNOWN*.
  • A number
  • example: input_max = 10e6 eg 10 Mbit/s
  • example: input_max = 10000000 eg 10 Mbit/s
  • default will not set a defined range, hence accept all values
int_alert=
(optional) 		Set an interface alert criteria
  • Format is: criteria:value:failures
  • example: lt:25:2 (for disk space: alert if capacity is 'less than' 25% for 2 concurrent failures)
    1. Where criteria =
    • lt (less than),
    • gt (greater than),
    • le (less than or equal to),
    • ge (greater than or equal to),
    • eq (equal to), or
    • ne (not equal to).
    1. Also value = the value or threshold that will trigger the alert
    • A number
    1. And failures = the number of query failures before an e-mail alert is triggered
    • A natural number, only using digits "0-9"
    • min = 1
    • max = 999
Setup - Graph File : <config directory>/graphs.xml

Note: If the number of graphs becomes too large, multiple graph files can be configured, refer to: How to....

The graph file is a XML format file. Additional graphs should be added, one for each graph required. (refer to graphs.xml as an example):

<graphs>
 <page menu="Site 1:power:ups-1" description="Graphs for device: APC ups-1">
   <graph description="output load" vertical_label="load (%)" short_label="%"
       graph_min="0" graph_max="100" k_base="1000" number_format="fixed">
     <plot plot="LINE2" color="0000EE" description="output load">
       [ups-1:apc_ups_load:0:MAX]</plot>
   </graph>
 </page>
 <page menu="Site 1:networks:router_2" description="Graphs for device: router_2">
   <graph description="Cisco CPU Load" vertical_label="Load (%)" short_label="%"
       graph_min="0" graph_max="100" k_base="1000" number_format="fixed">
     <plot plot="LINE2" color="0099cc" description="Cisco CPU load (1min)">
       [router_2:cisco_cpu:57.0:MAX]</plot>
     <plot plot="LINE2" color="0000ee" description="Cisco CPU load (5min)">
       [router_2:cisco_cpu:58.0:MAX]</plot>
   </graph>
   <graph description="Network Usage" vertical_label="bit/sec" short_label="bit/s"
       graph_min="0" k_base="1000">
     <plot plot="AREA" color="0099cc" description="Hssi6/1/0.1-dlci212 TotalOctets"
       line="95:0099cc">
       [router_2:ifUsage:10.15.212:MAX],[router_2:ifUsage:16.15.212:MAX],+,8,*</plot>
     <plot plot="LINE2" color="0000EE" description="Hssi6/1/0.1-dlci212 ifInOctet ">
       [router_2:ifUsage:10.15.212:MAX],8,*</plot>
     <plot plot="LINE2" color="006666" description="Hssi6/1/0.1-dlci212 ifOutOctet ">
       [router_2:ifUsage:16.15.212:MAX],8,*</plot>
     <plot>1024e3</plot>
   </graph>
 </page>
</graphs>
 
  • The graph file graphs.xml contains one-to-many <page>s
  • Each <page> contains one-to-many <graph>s
  • Each <graph> contains one-to-many <plot>s
<page>
menu=
(mandatory) 		The page navigation path
  • Format is:
    • menu3 or
    • menu2:menu3 or
    • menu1:menu2:menu3
  • Allowed characters are "a-zA-Z0-9_.-:" and " "
  • Maximum length of each menu segment is 20 characters
  • example: building:floor:device
description=
(recommended) 		A description for the page of graphs
  • The description is displayed in the web page title
  • Allowed characters are "a-zA-Z0-9_.-:/()" and " "
  • Maximum length of each menu segment is 36 characters
  • default = " "
<graph>
description=
(recommended) 		A description of the group of metrics that are being measured
  • The description is displayed in the graph title
  • Allowed characters are "a-zA-Z0-9_.-:/()" and " "
  • Maximum length of each menu segment is 36 characters
  • default = " "
vertical_label=
(recommended) 		A description of the vertical scale units of measure:
  • A maximum of 20 characters is permitted, any additional characters will be trimmed
  • Note: the graph will automatically add G, M or k as required
  • example: "bit/sec" for network traffic
  • example: "utilisation (%)" for CPU utilisation
  • no default
short_label=
(optional) 		A short description of the vertical scale units of measure:
  • A maximum of 5 characters is permitted, any additional characters will be trimmed
  • The short_label is used in the legend below the graph
  • Note: the graph will automatically add G, M or k as required
  • example: "bit/s" for network traffic
  • example: "%" for CPU utilisation
  • no default
comment=
(optional) 		Place a comment at the bottom of the graph.

Note: The use of XML for graphs.xml restricts the use of &, ", <, > in the comments. To print these, replace:
   -   & with &amp;
   -   " with &quot;
   -   < with &lt;
   -   > with &gt;
graph_max= and/or graph_min=
(optional) 		The upper and lower limits defined on the graph:
  • A number
  • The graph will change these limits if the values collected exceed the limits
  • example: graph_max = "10e6" eg 10 Mbit/s
  • example: graph_max = "10000000" eg 10 Mbit/s
  • no default
autoscale=
(optional) 		By default the graph will be autoscale="normal" so that it will adjust the y-axis to the range of the data. This may be sub optimal when you need to graph something like 260 + 0.001 * sin(x). The autoscale=alt (alternate) option calculates the minimum and maximum y-axis from the actual minimum and maximum data values. The example would display slightly less than 260-0.001 to slightly more than 260+0.001
  • either "normal"
  • or "alt"
  • default = "normal"
k_base=
(optional) 		The number of units per "k":
  • either 1000 for traffic measurement (1 kbit/s = 1000 bits/s),
  • or 1024 for memory measurement (1 KB = 1024 bytes)
  • default = "1000"
number_format=
(optional) 		The format of the numbers in the graph legend
  • either SI
    (use of the appropriate SI magnitude unit ( u, m, k, M, G ) and the value will be scaled accordingly, i.e. 654321 -> 654.32 k),
  • or fixed
    (number format is fixed at 2 decimal places, SI units are not used)
  • default: SI

Hint: It is recommended to initially use SI for all number_formats, only changing them to fixed if the output is overly complex or confusing. Where the number is always 3 digits or less, it may be appropriate to use fixed: e.g. for cpu the number is always ≤ 100, so to avoid 971.12 m% (milli-percent), use fixed i.e. 0.97 %.
<plot>
<plot> Either an RPN expression or a number

For RPN expression

  • this feature, provides the capability to develop graphing, from simple single source, through to complex graphs with multiple data sources, logic and conversions.
  • a comma separated RPN expression, including the use of data collected in the rrd files
  • RPN general reference: http://en.wikipedia.org/wiki/Reverse_Polish_notation
  • RPN general reference http://www.calculator.org/RPN.html
  • RPN rrd reference: http://oss.oetiker.ch/rrdtool/doc/rrdgraph_rpn.en.html
  • format to collect rrd data is: [target id:template id:int:consolidate] where
    • target id is from a target in the target file
    • template id is from the target id nominated above
    • int is from the template id nominated above
    • consolidate
      • When SNM (rrd) consolidates data from daily to weekly, monthly and yearly, the method of consolidation is to either AVERAGE the data or select the MAXimum value of the data to be consolidated. This attribute only effects the graph output and can be changed at the users discretion without impacting the underlying data.
      • either AVERAGE,
      • or MAX

For number:

  • a number
  • SNM will plot this as a line
  • example: <plot color="999999">10e6</plot> eg 10 Mbit/s

Examples:

  • [router_2:cisco_cpu:57.0:MAX]
    • Target id is router_2, template id is cisco_cpu, interface is 57.0 and consolidation is MAX
  • [router_2:ifUsage:16.15.212:MAX],8,*
    • Target id is router_2, template id is ifUsage, interface is 16.15.212 (OutOctets) and consolidation is MAX.
    • This value is then x8 to convert from Octets to bit/sec
  • [router_2:ifUsage:10.15.212:MAX],[router_2:ifUsage:16.15.212:MAX],+,8,*
    • First target id is router_2, template id is ifUsage, interface is 10.15.212 (InOctets) and consolidation is MAX.
    • Second target id is router_2, template id is ifUsage, interface is 16.15.212 (OutOctets) and consolidation is MAX.
    • These values are added (TotalOctets) and then x8 to convert from Octets to bit/sec
plot=
(recommended) 		The plot type to be presented on the graph:
  • either AREA (the area between 0 and the value will be filled),
  • or LINE1 (a line of width approximately 1 pixel),
  • or LINE2 (a line of width approximately 2 pixels),
  • or LINE3 (a line of width approximately 3 pixels),
  • or STACK (a line or area stacked upon the previous)
  • default is LINE2
  • AREA or LINEx must always precede STACK
  • SEE the RRD GRAPH manual for more information
color=
(recommended) 		The RRBBGG color to be presented on the graph:
  • range is from 000000 (black) to FFFFFF (white),
  • default is 000000 (black),
  • example: 008000 is green,
  • example: 0000FF is blue,
  • example: FF0000 in red
  • SEE the w3c web colors for more information
description=
(recommended) 		A description of the plot
  • The description is displayed in the graph legend
  • Allowed characters are "a-zA-Z0-9_.-:/()" and " "
  • Maximum length of each menu segment is 36 characters
  • default = " "
line=
(optional) 		Draw a horizontal line on the graph of the AVERAGE, MAXimum or 95th percentile
  • Format is: type:color where:
  • type is: AVERAGE, MAX, or 95, and
  • color is from 000000 (black) to FFFFFF (white)
  • example: 95:0000FF (draw a blue line of the 95%ile of the metric)

How to configure Modules in SNM

When configuring the targets file (eg targets.xml), modules may be configured within each target. 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 id of the template of the target
    • %community%  - the snmp community string for the target

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

  <metric module="Apachestats::stats( '%ip_address%', 'apache_total_hits')"
    data_source_type="COUNTER" convert="60" plot="LINE2"
    color="00BB00" consolidate="MAX">apache_hits</metric>

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

For further information, refer to: Modules

How Alerts in SNM work

Alerts are triggered by two methods:

  • <alert>     - failure of the target to respond to a (ping, snmp or module) query. Configuration is only required for sending e-mail or syslog alerts.
  • <int_alert> - a query result does not meet a criteria. Configuration is required to set the criteria.

Note: to e-mail/syslog a <int_alert>, an <alert> must be configured

Alerts are presented in two forms:

  • On the SNM Alert web page (snm.cgi).
    • All alerts are presented on the SNM Alert web page (no configuration required)
    • Interface alerts are presented on the SNM Alert web page if <int_alert> is configured
  • Send via e-mail and/or syslog. The sending of alerts via e-mail/syslog is optional. To send e-mail/syslog alerts:
    • Configure <mail_server> and <alert>s in the configuration file (config.xml)
    • Configure <alert> in the target file (target.xml)
    • Optionally configure criteria in <int_alert> in the target file (target.xml)

How Attribute Discovery works

Attribute discovery is designed to allow the viewing of target properties that change infrequently (e.g. System Description and System Contact).

  • Attribute discovery is optional.
  • When activated, attribute discovery is delivered by querying of snmp properties on targets and storing the results in <web directory>\rrd\<target>\attributes.xml.

Four components comprise attribute discovery:

  1. Configuration file (e.g. config.xml)
    If attribute discovery is required, <attributes> are configured. Refer to: Setup - Configuration File.
  2. Discover file (e.g. discover.xml)
    Within discover.xml there are suites (e.g. <suite id="">). Each target uses one or more <suite>s, by default the first suite is used, unless in <target attributes=""> is configured. Each <suite> comprises the <value>, <table> and <column> snmp oids to query. Note, the <value> oids return a single value and the <column> oids return multiple values. The file discover.xml can be modified to provide differing discovered snmp oid values (upon testing and restarting SNM).
  3. The attributes file (e.g. <web directory>\rrd\<target>\attributes.xml)
    Contains the query return values, ready for display using a web browser.
  4. The <target attributes="">
    Is configured to either select a non-default <suite>, multiple <suite>s, or to not discover the target by setting <target attributes="no">.
  • The discover file (e.g. discover.xml) contains one-to-many <suite>s
  • Each <suite> contains 0-to-many <value>s, and
  • Each <suite> contains 0-to-many <table>s
  • Each <value> contains 0-to-many <translate>s
  • Each <table> contains one-to-many <column>s
  • Each <column> contains 0-to-many <translate>s
<suite>
id=
(mandatory) 		The suite identifier
  • Allowed characters are "a-zA-Z0-9_.-"
  • Maximum length is 36 characters
  • Must be unique
<value>
oid=
(mandatory) 		The snmp OID, in dotted number format, that returns a single value
  • Allowed characters are "0-9."
  • example: 1.3.6.1.2.1.2.2.1.10.0
  • example: 1.3.6.1.4.1.9.2.1.58.0
description=
(mandatory) 		A description of the Attribute/OID that is being queried
  • The description is displayed in the value table
  • Allowed characters are "a-zA-Z0-9_.-" and " "
convert=
(optional) 		Convert a returned value.
  • If convert="date", the value will be converted from DateAndTime (rfc 2579) to yyyy-mm-dd hh:mm:ss
  • Example: returned value=0x07d6021c16070e00 after, converted value=2006-02-28 22:07:14
calculate=
(optional) 		An RPN (http://en.wikipedia.org/wiki/Reverse_Polish_notation) suffix to derive the attribute value
  • Valid characters are "0-9.,-+*/eE"
  • Valid numbers include +-, integer, decimal and exponential notation (e.g. 10e6 = 10 Mbit/sec)
  • Valid operators are "-+*/"
  • Example: if the returned value is bit/sec and the desired value is Mbit/sec, set calculate="1e6,/".
    A return value of 10000000 bit/sec will thus be calculated RPN: 10000000,1e6,/ = 10000000/1e6 = 10 Mbit/sec
<table>
description=
(mandatory) 		A description of the table of attributes being queried
  • The description is displayed in the table
  • Allowed characters are "a-zA-Z0-9_.-" and " "
<column>
oid=
(mandatory) 		The snmp OID, in dotted number format, that returns one-to-many values
  • Allowed characters are "0-9."
  • example: 1.3.6.1.2.1.2.2.1.1
  • example: 1.3.6.1.2.1.25.2.3.1.3
description=
(mandatory) 		A description of the Attribute/OID that are being queried
  • The description is displayed in the table
  • Allowed characters are "a-zA-Z0-9_.-" and " "
convert=
(optional) 		Convert a returned value.
  • If convert="date", the value will be converted from DateAndTime (rfc 2579) to yyyy-mm-dd hh:mm:ss
  • Example: returned value=0x07d6021c16070e00 after, converted value=2006-02-28 22:07:14
calculate=
(optional) 		An RPN (http://en.wikipedia.org/wiki/Reverse_Polish_notation) suffix to derive the attribute value
  • Valid characters are "0-9.,-+*/eE"
  • Valid numbers include +-, integer, decimal and exponential notation (e.g. 10e6 = 10 Mbit/sec)
  • Valid operators are "-+*/"
  • Example: if the returned value is bit/sec and the desired value is Mbit/sec, set calculate="1e6,/".
    A return value of 10000000 will thus be calculated RPN: 10000000,1e6,/ = 10000000/1e6 = 10 Mbit/sec
<translate> (used by both <value> and <column>)
value=
(mandatory) 		The value to match against return column values
text=
(mandatory) 		The replacement text if value matches a return column value

How SNM works

There are two program files that comprise SNM, the server program snm.pl and the browser program snm.cgi.

  1. snm.pl is the server program that:
    1. loads then verifies the configuration and target files,
    2. queries targets at predetermined intervals,
    3. writes the data to .rrd files (creating them if they do not exist),
    4. creates an alert file of unsuccessful queries and criteria, and
    5. sends e-mail alerts.

    There are two methods of running the SNM server:

    • Console Mode - using the DOS or terminal console. The SNM server has no graphical interface, the method of viewing SNM server messages are via the console or the log file.
    • Service Mode - When SNM server is correctly configured and has been operating in console mode without issue for a reasonable time, the SNM server can be configured to operate as a service. This eliminates the use of the console and provides for automatic start-up upon the server booting without user login or interaction.

    snm.pl creates sub-directories in <web_dir>, one for each target. In each target subdirectory, one .rrd file will be produced for each template associated with that target.

  2. snm.cgi is a program that creates the graphs and presents them via a web browser (Internet Explorer, Firefox, etc).
    1. snm.cgi is executed each time the user requests new or updated presentation of the graphs.
    2. New graphs are generated.
    3. Data is developed from snm.cgi and parsed to template files (.htmt) used to create the presentation. The output is then presented to the user using a standard web browser.
    4. The alert file is also queried and displayed as requested by the user.
    5. The most recent 100 lines of the log file are also queried and displayed as requested by the user.

Starting SNM

Normal SNM Server Operation

For Win32 users using a non-English language in SNM, the command prompt window will not display extended characters ( e.g. in 8859-1 ) properly. This is a problem with Windows console and not Perl or SNM.

Assuming a console running in a window (as opposed to running full-screen) then two things are required:
1. The default raster font used for console windows doesn't know about 8859-1 / latin-1, so change it. Use the system menu, Properties and select "Lucida Console" instead of "Raster Fonts".
2. Use the CHCP command to select the 1252 (Latin 1) codepage: CHCP 1252
Now re-run SNM in console mode and you should see the correct extended characters.

At the console prompt:

  1. Go to the directory where snm.pl resides:
    Example: C:\Program Files\snm>
  2. If starting for the first time it is recommended to run the program in test mode:
    Win32 Example: C:\Program Files\snm>snm.pl -c config.xml -t, or
    Linux Example: [root@host snm] perl snm.pl -c /etc/opt/snm/config.xml -t.
    If any error messages are displayed after the test, attend to as appropriate.
  3. Run the program:
    Win32 Example: C:\Program Files\snm>snm.pl -c config.xml, or
    Linux Example: [root@host snm] perl snm.pl -c /etc/opt/snm/config.xml.
  4. In the console a start-up message should appear:
    Example: 0000000000 main(): Loop start Day Mth 0 00:00:00 0000
  5. If any error messages are displayed after the start-up, attend to as appropriate.
  6. Only when SNM has been tested for a time, if appropriate, it can be installed as a service.

At the console prompt, to stop SNM, use Ctrl^C.

Note, it may take up to 10 seconds to stop processing.

SNM Browser Operation

To view the graphs via a web interface, go to the configured web path / cgi file name:
Example: http://localhost/snm/snm.cgi

SNM Server Operation Options

To test and verify the correct operation of SNM, two settings have been developed.
Also, in the event of anomalies, these two methods can be used to correct the condition:

Note: It is recommended that test and verbose modes are only activated in console mode.

  1. Test Mode (snm.pl -c config.xml -t)
    When test mode is activated, SNM will test and log itself including the configuration and target files but will not query any targets. Included is a test of RRDs (the perl RRDs shared module) to a test_x.rrd file, where the test .rrd file is created from the command rrdtool create test.rrd DS:test:GAUGE:300:U:U RRA:LAST:0.5:1:10.
  2. Verbose Mode (snm.pl -c config.xml -v)
    When verbose mode is activated, SNM will provide verbose logging of all activities to assist in verifying and identifying configuration corrections including target query anomalies.

Both test mode and verbose mode will output to console as well as to the log file (if defined in the configuration file).

SNM Server Maintenance
  1. The menu in the web browser provides an alert status.
  2. Remember to regularly review the log file if it has been defined (SNM will purge old logs automatically).

System and Network Monitor Copyright 2008 Thomas Price