                          perfSONAR TL1 Collector/Service

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

About:
------

The perfSONAR-PS TL1 Collector and Service allows networks to collect 
and make available TL1 performance counters.  Currently, the collector supports
querying Ciena CoreDirectors. The perfSONAR-PS TL1 Service can make this
collected data available to interested clients.

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

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

The TL1 Collector/Service comes pre-configured, allowing for for immediate testing.

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

  - etc/database.conf: 
  
    Contains information that identifies which database the service and
    collector should interact with. There are several options that should be
    changed:  
   
      collection_interval      - The time between when data is collected

      metadata_db_type         - The type of database to use. Currently supported are 'sqlite' and 'mysql'
      metadata_db_prefix       - The prefix to prepend to the database table names. Defaults to "ps" if not set.
      metadata_db_file         - The filename for a SQLite database.
      metadata_db_name         - The database name for a MySQL database.
      metadata_db_host         - The host running the MySQL database.
      metadata_db_port         - The TCP port the MySQL database is listening on. Defaults to 3306
      metadata_db_username     - The username to login to the database with. Defaults to no username.
      metadata_db_password     - The password to login to the database with. Defaults to no password.
      rrd_directory            - The directory to store the RRD files in.
      store_file               - A shared file that the service uses to make available the counter information.

  - etc/elements.conf

    Contains the set of network elements to monitor. The elements can include
    The example configuration file provided contains examples of the different
    ways that elements can be monitored.

  - etc/service.conf

    Contains information that identifies the service uniquely and allows it to
    run in a given environment. There are also several options that may be
    changed for a configuration:
   
      port                         - Port the service listens on
      endpoint                     - Endpoint to contact the service
      enable_registration          - Turn on or off LS registration
      ls_instance                  - The Lookup Service to register with
      external_address             - The address to advertise to the Lookup Service so that clients can contact this service.
      site_name                    - The network or organization which owns this service.
      site_location                - The location of this service.
      ls_registration_interval     - Length of time (minutes) between updating information in the Lookup Service.
      rrdtool                      - location of the rrdtool binary
      default_resolution           - Raise higher or lower depending on RRD files

  - etc/service_logger.conf:

    Contain information related to where the service logs, 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

    In the file, there are example instances of each of the above, with the
    Screen and Syslog sections commented out.

  - etc/collector_logger.conf:

    Contain information related to where the collector logs, 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

    In the file, there are example instances of each of the above, with the
    Screen and Syslog sections commented out.

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

The service and collector come with init scripts to start and stop them.

If installed via RPM, the service can be started, stopped or restarted with:

  /etc/init.d/perfsonar_tl1_service start
  /etc/init.d/perfsonar_tl1_service stop
  /etc/init.d/perfsonar_tl1_service restart

and the collector can be started, stopped or restarted with:

  /etc/init.d/perfsonar_tl1_collector start
  /etc/init.d/perfsonar_tl1_collector stop
  /etc/init.d/perfsonar_tl1_collector restart

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

  perl bin/service.pl --verbose --conf=etc/service.conf
  
The collector can also be started manually:

  perl bin/collector.pl --verbose --conf=etc/collector.conf

Testing:
--------

The service comes with a client application and several test messages that can
be used to test functionality once the service and collector have been
configured:

  doc/requests/EchoRequest.xml
  doc/requests/PathStatusSetupDataRequest_now.xml

To test:

  1) Ensure the service is started, it helps if you have run it using debug
     mode.  This is to monitor the service's activities.

  2) Run the client:
  
     perl bin/client.pl URL FILENAME
  
  3) If the result does not contain an error message, restart service with the
     init scripts.

Once the preliminary testing has been done, the service can be tested with
E2EMon. This can be done by giving the service URL and the chosen domain name
to an existing E2EMon installation.

Instructions for deploying your own E2EMon instance can be found at
https://wiki.man.poznan.pl/perfsonar-mdm/index.php/LHC_e2e_mon_soft . You can
then domain and service can be added to the configuration, and test the
service.

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 Users Group - https://mail.internet2.edu/wws/info/perfsonar-user
  perfSONAR Announcements - https://mail.internet2.edu/wws/info/perfsonar-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:

  yum update

Finally, check the following websites for news of software releases:

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

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

Fri Apr  3 12:38:12 EDT 2009
