			              perfSONAR Lookup Service

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

About:
------

PingER (Ping End-to-end Reporting) is the name given to the Internet
End-to-end Performance Measurement (IEPM) project to monitor end-to-end
performance of Internet links. It is led by SLAC and development includes
NUST/NIIT, FNAL, GATech and ICTP/Trieste.

Originally in 1995 it was for the High Eneergy Physics community, however,
this century it has been more focussed on measuring the Digital Divide from an
Internet Performance viewpoint. The project now involves measurement to over
600 sites in over 125 countries, and we are actively seeking new sites to
monitor and monitoring sites for this project, as well as people interested in
our data.

PingER has a decade old data repository of network performance measurements
from and to sites around the world. Currently, there are around 35 monitoring
hosts in 13 countries monitoring over 300 sites in over 115 countries that
amongst them contain around 99% of the worlds Internet connected population.

PingER provides insight into a multitude of network activity. To summarize the
results, it is necessary to aggregate the measurements by region and to
divided them into measurements of long-term trends and of short-term glitches.

Uses for PingER:
----------------

Technical: PingER data provides a lightweight way of monitoring the
throughput, loss and response times, effectively measuring the quality of a
particular link with little overhead. This also provides information for
setting up and auditing Service Level Agreements

Economical: Based on the presentation of the PingER findings, a recommendation
can be made to the policy/funding people to increase the bandwidth.
Furthermore, if one site in a certain region can attain credible connectivity,
then other sites in that region should be able to have better connectivity as
well. As a troubleshooting tool, PingER can be used to discern if a problem is
network related, identify the time the problem started, whether it is still
occurring, and provide quantitative analysis.

Collaboration: In order for scientists to collaborate, a certain level of link
quality is required. By using PingER to measure the loss and RTT, you are able
to provide expectations for the performance for bulk data transfer and other
applications. In case of real-time collaboration, by comparing the results
from PingER with various recommendations for loss, RTT and jitter, together
with the perceptions of voice quality from the users, you can determine how
well VoIP and other interactive applications might work between various pairs
of sites.

Architecture:
-------------

PingER uses the ubiquitous Internet ping facility to measure the short and
long term Response Time, Packet Loss percentages, the variability of the
response time (jitter), and the lack of reachability (no response for a
succession of pings).

Ping is usually pre-installed on almost all platforms, so there is nothing to
install on the clients. The server (i.e. the echo responder) runs at a high
priority (e.g. in the kernel on UNIX) and so is more likely to provide a good
measure of network performance than a user application.

PingER is very modest in its network bandwidth requirements (~100 bps per
monitoring-remote- host-pair for the way we use it).

Due to the volume of data that can be collected by PingER, perfSONAR-PS PingER
can be configured to utilize SQLite, MySQL or Postgres storage backends.

perfSONAR-PS PingER is composed of two distinctive (kind of) components:

1) Measurement Archive (MA): Which allows communication via XML document based
Remote Procedure Call (XML) the data archive of PingER data.

2) Measurement Point (MP): Which performs the measurement and calculation of
derived statistics from Pings.

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

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

If not started already, start MySQL:

  (sudo) /etc/init.d/mysqld restart

If not done already, set the MySQL Root password:

  (sudo) /usr/bin/mysqladmin -u root password 'new-password'

Edit Files (each is annotated with locations and instructions).  Run
configuration script:

  /opt/perfsonar_ps/PingER/bin/pinger_ConfigureDaemon
  
Answer all questions or accept defaults about desired location of the
service/port/description etc...  This script will attempt to create the MA
database.

Check logging config file: 
     
  /etc/PingER/logger.conf

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

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

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

Create symlinks to allow automated start/stop at the boot/shutdown time:
	
        ln -s /etc/init.d/PingER /etc/rc2.d/S99PingER
        ln -s /etc/init.d/PingER /etc/rc6.d/K02PingER
        ln -s /etc/init.d/PingER /etc/rc0.d/K02PingER

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

  perl bin/daemon.pl --verbose --conf=etc/daemon.conf
  
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.


Testing:
--------

Test the web service:

  /opt/perfsonar_ps/PingER/client/bin/pinger_client.pl

It will print  something like this:
    
[netadmin@lhcopnmon1-mgm client]$ ./pinger_client.pl 
Metadata: src=lhcopnmon1-mgm.fnal.gov dst=tier2.ucsd.edu  packetSize=1000
Metadata Key(s): 8 :
Metadata: src=lhcopnmon1.fnal.gov dst=cithep130.ultralight.org  packetSize=1000
Metadata Key(s): 22 :
Metadata: src=lhcopnmon1.fnal.gov dst=tier2.ihepa.ufl.edu  packetSize=1000
Metadata Key(s): 21 :
Metadata: src=lhcopnmon1-mgm.fnal.gov dst=pinger.fnal.gov  packetSize=1000
Metadata Key(s): 1 :
Metadata: src=lhcopnmon1.fnal.gov dst=phedex.rcac.purdue.edu  packetSize=1000
Metadata Key(s): 15 :
Metadata: src=lhcopnmon1-mgm.fnal.gov dst=www.cmsaf.mit.edu  packetSize=1000
Metadata Key(s): 9 :
Metadata: src=lhcopnmon1.fnal.gov dst=t2.unl.edu  packetSize=1000

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:

  yum update

or

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

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

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

Fri Apr  3 10:43:20 EDT 2009

