               perfSONAR-PS PingER Installation Instructions

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

The perfSONAR-PS PingER service is an evolution of the PingER project
(http://www-iepm.slac.stanford.edu/pinger/) with more than 10 years experience
in collecting and analysising network performance across the world. The
perfSONAR-PS PingER service is composed of both a storage backend (MA) and
measurement frontend (MP) to conduct and store ping measurements and to make
available such data for consumption by interested parties. Network
characteristics supported include availability, latency and jitter, which
provide a broad spectrum of determining end-to-end network performance.

perfSONAR-PS PingER is designed to be scalable enough in order to accommodate
hundreds of monitored pairs of hosts and uses a relational database backend
(MySQL, Postgres, SQLite) to efficiently store and retrieve such performance
information.

perfSONAR-PS PingER also supports the registration of data through perfSONAR
LS's to faciliate the dynamic discovery and querying of unknown deployments.

The MA provides a web service interface based on NMWG XML that allows queries on
the PingER data and to be consumpted by perfSONAR client applications and
services alike.

Prerequisites:
--------------

PingER is packaged as an RPM - a binary installation format that is geared
towards use on Red Hat linux based systems.  Examples include Fedora, Red Hat
Enterprise Linux, CentOS, White Box, Scientific Linux, and possibly others.  

These Linux distributions normally rely on "Package Management" tools to install
and maintain software.  Examples of these tools include up2Date, YUM, and
APT-RPM.  Internet2 has created a repository to house the perfSONAR-PS software,
related performance tools, and hard to find prerequisites.  We encourage
adopters of these tools to install a simple RPM package that gives the necessary
configuration information for the YUM and APT-RPM tools.  The RPM can be found
here:

  wget -c http://software.internet2.edu/Internet2-repo-0.1-2.noarch.rpm
  
To install this RPM first import the signing key:

  rpm --import http://software.internet2.edu/rpms/RPM-GPG-KEY-Internet2

Then install the RPM:

  rpm -ivh Internet2-repo-0.1-2.noarch.rpm

It is also recommended that an additional repository be installed for hard to 
find prerequisite software that may not be available in traditional repositories
used by the Linux distributions.  Two regarded repositories are:

 * http://dries.ulyssis.org/rpm/
 * http://dag.wieers.com/rpm/
 
Each site provides configuration instructions and packages similar to the
Internet2 repository.

If using a package management system is not an option, or if your system is not
RedHat based (e.g. Debian, Gentoo, etc.) it is still possible to install this
software and related requirements by hand.  Please see the "Installation (Tar
Package)" and "Installation (SVN)" sections for more details.  This tool uses
the following Perl libraries, libraries, and external tools to function:

  * Libraries
    - LibXML2
  * Tools
    - MySQL or SQLite



Installation (YUM):
-------------------

Like Apt, YUM installation also manages the task of finding dependencies.  The
following command is all that is needed:

  yum install perfSONAR_PS-PingER-server-v3.1-13.pSPS.noarch.rpm

There may be several prerequisites to install depending on the age of your
system.  To ensure that all are found, please be sure to install one of the
alternative repositories above. 



Installation (APT-RPM):
-------------------

Installation through APT-RPM is easy, simply let the package manager do the work
of managing the dependencies:

  apt-get update
  apt-get install perfSONAR_PS-PingER-server-v3.1-13.pSPS.noarch.rpm

There may be several prerequisites to install depending on the age of your
system.  To ensure that all are found, please be sure to install one of the
alternative repositories above.  



Installation (Bare RPM):
------------------------

If you do not wish to install the Internet2 Repository package, you may simply
install a noarch RPM:

  wget -c http://lhcopnmon1-mgm.fnal.gov:9090/downloads/perfSONAR_PS-PingER-server-v3.1-13.pSPS.noarch.rpm 
  
To install without package manager help:

  rpm -ivh perfSONAR_PS-PingER-server-v3.1-13.pSPS.noarch.rpm
  
Note that this RPM may need packages to install correctly: if they are not found
on your system manual download and install will be required.  An alternate
method is to still use a package manager in a "local" way (YUM only):

  yum localinstall perfSONAR_PS-PingER-server-v3.1-13.pSPS.noarch.rpm
  
This will still search the available repositories for any necessary packages.


In addition to perl requirements, there are other software requirements that
should be installed.  These are not controlled via the dependency scripts due to
differences in package mangement.  The tools are listed below:

  * MySQL
    - Package management names:
      * Debian/Ubuntu: mysql-server-5.0, mysql-client-5.0, libdbd-mysql-perl,
                       libdbd-mysql
      * RedHat Systems: mysql-server, mysql, mysql-devel, libdbi-dbd-mysql,
                        perl-DBD-MySQL
  * SQLite
    - Package management names:
      * Debian/Ubuntu: sqlite3, libsqlite3-0, libsqlite3-dev,
                       libdbd-sqlite3-perl, libdbd-sqlite3
      * RedHat Systems: sqlite, sqlite-devel, perl-DBD-SQLite
  * LibXML2
    - Package management names:
      * Debian/Ubuntu: libxml2, libxml2-dev, libxml2-utils
      * RedHat Systems: libxml2, libxml2-devel
      


Installation (SVN):
-------------------

Software may be downloaded directly from our anonymous subversion server.  This
installation method allows for easy upgrades between versions and access to 
bugfixes immediately.  There are two ways to download from our server, one that
retrieves all software and another that retrieves only selective services.

To download the entire release:

  svn checkout http://anonsvn.internet2.edu/svn/perfSONAR-PS/tags/RELEASE_3.1 perfSONAR-PS
  
The instructions are the same here as for the Tar package.  Note that
installation may require pre-requisite software.  Read the preceding sections
for necessary items and suggestions on how to install and configure them.  When
you wish to update the checkout (to retrieve new development or bugfixes):

  cd perfSONAR-PS
  svn update
  
If a single service is all that is required, a similar method is used but also
note that the service must have access to a "Shared" directory that contains
perfSONAR-PS libraries:

  svn checkout http://anonsvn.internet2.edu/svn/perfSONAR-PS/tags/RELEASE_3.1/perfSONAR_PS-PingER/
  svn checkout http://anonsvn.internet2.edu/svn/perfSONAR-PS/tags/RELEASE_3.1/Shared

The instructions are also the same as above:

  cd Shared
  svn update

and

  cd perfSONAR_PS-PingER
  svn update


Keeping PingER running
-----------------------

In order to assure uninterruptable service it is recommended to configure a cronjob
under the "root" account as:

0,10,20,30,40,50 * * * * /opt/perfsonar_ps/PingER/bin/pinger_service_check.pl --mail='<ENTER_SYSADMIN_EMAIL_ACCOUNT>'  --restart 2>&1 > /dev/null
---------------

This script will be checking the health of the PingER MP and MA and will attempt to restart service if it will die for any reason.
The email notification will be send to the specified email account.


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

Mon Apr 13 08:40:45 EDT 2009

