			              perfSONAR SNMP MA Service

--------------------------------------------------------------------------------

About:
------

The perfSONAR-PS SNMP based Measurement Archive (SNMP MA) is able to expose data
collected via variables from the Simple Network Management Protocol (SNMP)
protocol found on networked devices and stored in Round Robin Databases (RRD)
archives. The measurements are collected through external means, normally
through software such as MRTG, CACTI, or Cricket, and is commonly stored in RRD
archives. External access to commonly requested data items, remains challenging
due to physical and political boundaries.

The SNMP MA provides a simple interface that is cable of exposing these files
after basic configuration for consumption by perfSONAR client applications and
services alike. The Web Service front end provides a uniform method of access
using the perfSONAR XML protocols and delivers the data in an unambiguous
manner, thus eliminating the mystery associated with the backend storage. 

Installation:
-------------

Please read the INSTALL file for instructions
  
Configuration:
--------------

The SNMP MA comes with a base configuration via the installation procedure.
This is meant to allow for immediate testing as well as serve as a guide for
customizing the service.  

There are several files that may be adjusted manually to configure this service
for a specific use case:

  - etc/daemon.conf: 
  
    Contains information that identifies the service uniquely and allows it to
    run in a given environment.  There are several options that should be
    changed:  
   
      rrdtool                  - location of the rrdtool binary
      service_accesspoint      - Change the "hostname" from localhost
      service_description      - Identifying information about the service
      service_name             - Service Name (short)  

    There are also several options that may be changed for a configuration:

      port                     - Port the service listens on
      endpoint                 - Endpoint to contact the service
      default_resolution       - Raise higher or lower depending on RRD files
      metadata_db_external     - Used with external tools (Cacti/Cricket)
      ls_registration_interval - Length of time (minutes) between contacting LS 
      enable_registration      - Turn on or off LS registration
    
    The rest of the items are normally not to be adjusted.  See also the service
    wiki page for more information:
    
      http://code.google.com/p/perfsonar-ps/wiki/SNMPMA
    
  - etc/daemon_logger.conf:

    Contains information related to logging, there are three modes:
    
      Log::Dispatch::Screen     - Log messages to screen (useful for debugging)
      Log::Dispatch::Syslog     - Log messages to syslog facility
      Log::Dispatch::FileRotate - Log messages to specified file

    Each logging mode is achieved by commenting/uncommenting specific lines in
    the file.  Refer to the file for instructions.

    The rest of the items are normally not to be adjusted.  See also the service
    wiki page for more information:
    
      http://code.google.com/p/perfsonar-ps/wiki/SNMPMA

  - /var/lib/perfsonar/snmp_ma/store.xml: 

    This file represents the "explanation" of the data that is being offered by
    the service.  It is written in XML and is configured for a "localhost"
    environment with a single empty RRD file.  This file may be modified by hand
    to add new existing RRD files that describe specific interfaces.  It is also
    possible to configure your service to use external collection tools such as
    Cacti or Cricket.

    See the wiki page for more information:
    
      http://code.google.com/p/perfsonar-ps/wiki/SNMPMA

Starting/Stopping:
------------------

The service comes with init scripts that may be used to start and stop
operation:

  (sudo) /etc/init.d/snmp_ma start
  (sudo) /etc/init.d/snmp_ma stop
  (sudo) /etc/init.d/snmp_ma restart

The service can also be run in a manual fashion (useful for debugging):

  (sudo) perl bin/daemon.pl --verbose --conf=etc/daemon.conf --logger=etc/daemon_logger.conf
  
Before doing this, be sure to edit "etc/daemon_logger.conf" to enable "Screen"
debugging.

Testing:
--------

The service comes with a client application and several test messages that can
be used to test functionality.  The client application sends the XML file
specified on the command line as a request to the URL specified on the command
line.  The XML response from the server is returned. There are many messages
provided as examples, to test the service only one is recommended:

  (sudo) perl bin/client.pl http://localhost:9990/perfSONAR_PS/services/SNMPMA etc/requests/EchoRequest.xml

These two will test the major functions of this service. To test:

  1) Ensure the service is started, this can be done two ways:
  
    a) Start the service via the init script - you will not be able to monitor
       the service 'live', but log files may be examined to determine if things
       are working.  
  
    b) Start the service in 'debug' mode:
    
       (sudo) perl bin/daemon.pl --verbose --conf=etc/daemon.conf --logger=etc/daemon_logger.conf
       
       Be sure that logging is configured to the use the "Screen" so you may
       monitor the service's activities.

  2) Run the client:
  
     perl bin/client.pl URL FILENAME
  
  3) The results of the first test will be an XML message that indicates the service
     is working:
     
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"
messageIdRef="EchoMessage1" id="message.12780503" type="EchoResponse"><nmwg:metadata
metadataIdRef="metadata1"
id="metadata.5353493"><nmwg:eventType>success.echo</nmwg:eventType></nmwg:metadata><nmwg:data
metadataIdRef="metadata.5353493" id="data.1643179"><nmwgr:datum
xmlns:nmwgr="http://ggf.org/ns/nmwg/result/2.0/">The echo request has
passed.</nmwgr:datum></nmwg:data><nmwg:metadata
xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/" id="metadata1">
    <nmwg:eventType>http://schemas.perfsonar.net/tools/admin/echo/2.0</nmwg:eventType>
  </nmwg:metadata></nmwg:message>  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

  4) In a similar manner, it is possible to test other messages:

  (sudo) perl bin/client.pl http://localhost:9990/perfSONAR_PS/services/SNMPMA etc/requests/EchoRequest.xml
  (sudo) perl bin/client.pl http://localhost:9990/perfSONAR_PS/services/SNMPMA etc/requests/MetadataKeyRequest-1.xml 
  (sudo) perl bin/client.pl http://localhost:9990/perfSONAR_PS/services/SNMPMA etc/requests/DataInfoRequest-1.xml 
  (sudo) perl bin/client.pl http://localhost:9990/perfSONAR_PS/services/SNMPMA etc/requests/SetupDataRequest-1.xml

     The response to these messages may differ from service to service, so they
     will not be enumerated here.  
       
  5) If everything looks OK, return logging to normal and restart service via
     the init system.  



Maintenance:
------------

Subscribe to the user mailing lists if you are seeking help on some problem
related to this software.  Announcements regarding availability of new releases
will also be sent to these locations

  perfSONAR-PS Users Group - https://mail.internet2.edu/wws/info/psps-users
  perfSONAR-PS Announcements - https://mail.internet2.edu/wws/info/psps-announce

  Performance Node Users - https://mail.internet2.edu/wws/info/performance-node-users
  Performance Node Announcements - https://mail.internet2.edu/wws/info/performance-node-announce

Also if you are using package management software and have installed the
Internet2 software repository, a typical upgrade should download new releases:

  (sudo) yum update

or

  (sudo) apt-get upgrade
  
Finally, check the following websites for news of software releases:

  http://software.internet2.edu
  http://www.internet2.edu/performance

--------------------------------------------------------------------------------

Fri Apr 23 14:37:12 EDT 2010
