			        perfSONAR perfSONAR-BUOY MA Service

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

About:
------

The perfSONAR-PS perfSONAR-BUOY Measurement Archive (MA) functions as both a
storage facility and a regular testing framework in conjunction with the BWCTL
and OWAMP measurement tools.  These archived measurements, stored in a MySQL
database, are exposed through a web services interface.  

The perfSONAR-BUOY MA provides a simple interface that is capable 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

Database Preparation:
---------------------

The MySQL database for the OWAMP and BWCTL data must be prepared before
collection may begin.  Note that some options regarding the database can be
adjusted in the 'owmesh.conf' file (see next section).  There are two scripts, 
one for each data type:

  (sudo) bin/owdb.pl -c ../etc -i ADMIN_USER_NAME
  (sudo) bin/bwdb.pl -c ../etc -i ADMIN_USER_NAME
  
Note that if you wish to delete an existing data base replace '-i' with '-x'.
Replace ADMIN_USER_NAME with the name of the MySQL admin (this is normally
'root').  Before starting the script a prompt will appear for this user's
password, if there is no password press enter.  
     
Configuration:
--------------

The perfSONAR-BUOY 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:  
   
      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
      ls_registration_interval - Length of time (minutes) between contacting LS 
      enable_registration      - Turn on or off LS registration
      ls_instance              - Specific hLS to register data with
      maintenance_interval     - Interval of time to re-generate the store.xml
                                 file (N.B. doing this frequently can be CPU
                                 expensive but does make test data available
                                 more quickly)
      owmesh                   - This is the *DIRECTORY* that contains the
                                 owmesh.conf file.  *DO NOT* place the full path
                                 to the file or the service will not start.
    
    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/perfSONARBUOY
    
  - 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/un-commenting 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/perfSONARBUOY

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

    The location of this file should be changed - but the file itself is dynamic
    and should not be edited.

  - etc/owmesh.conf: 

    This file is annotated with instructions on what to change.

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

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

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

There are other scripts that manage the measurement and collection of data:

 - perfsonarbuoy_bw_master      Script that performs BWCTL measurements
 - perfsonarbuoy_bw_collector   Script to collect and store BWCTL measurements
 - perfsonarbuoy_owp_master     Script that performs OWAMP measurements
 - perfsonarbuoy_owp_collector  Script to collect and store OWAMP measurements

In general, "master" scripts will run on data collector nodes (e.g. 'beacons'),
and "collector" scripts run on central node or nodes that normally contain a
database. 

An example of manually invoking the "bwmaster" script (useful for debugging):

  (sudo) perl bin/bwmaster.pl -c etc -dvZ

An example of manually invoking the "bwcollector" script (useful for debugging):

  (sudo) perl bin/bwcollector.pl -c etc -dvZ

The web 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:
--------

perfSONAR-BUOY has several unique components that should be tested individually
to ensure installation and configuration were successful.  The following
sections outline basic testing that should be done, in the specified order, to
test the installation.  

BWCTL:
------

BWCTL should be installed, configured, and running on every machine that will
function as a "beacon", e.g. a location that will participate in bandwidth
testing.  Installation and configuration of BWCTL is beyond the scope of these
instructions - please consult the appropriate documentation for the BWCTL tool
before proceeding.  To test BWCTL, log on to a beacon and run a test to all
other beacons, in both directions (e.g. use the -s and the -c flags).  E.g. try
the following where in this example "bwctl.chic.net.internet2.edu" is a beacon
we wish to test with:



[user@nms-rthr2 ~]$ bwctl -c bwctl.chic.net.internet2.edu
bwctl: Using tool: iperf
bwctl: 15 seconds until test results available

RECEIVER START
bwctl: exec_line: iperf -B 2001:468:2:11::17:2 -s -f b -m -p 5004 -t 10 -V
bwctl: start_tool: 3460893305.899586
------------------------------------------------------------
Server listening on TCP port 5004
Binding to local address 2001:468:2:11::17:2
TCP window size: 16777216 Byte (default)
------------------------------------------------------------
[ 15] local 2001:468:2:11::17:2 port 5004 connected with 2001:468:6:11::17:66 port 5004
[ 15]  0.0-10.2 sec  7833288704 Bytes  6168710093 bits/sec
[ 15] MSS size 8928 bytes (MTU 8968 bytes, unknown interface)
bwctl: stop_exec: 3460893318.983014



The opposite direction:



[user@nms-rthr2 ~]$ /usr/bin/bwctl -s bwctl.chic.net.internet2.edu
bwctl: Using tool: iperf
bwctl: 16 seconds until test results available

RECEIVER START
bwctl: exec_line: iperf -B 2001:468:6:11::17:66 -s -f b -m -p 5001 -t 10 -V
bwctl: start_tool: 3460893469.855799
------------------------------------------------------------
Server listening on TCP port 5001
Binding to local address 2001:468:6:11::17:66
TCP window size: 87380 Byte (default)
------------------------------------------------------------
[ 14] local 2001:468:6:11::17:66 port 5001 connected with 2001:468:2:11::17:2 port 5001
[ 14]  0.0-10.0 sec  7926022144 Bytes  6333901728 bits/sec
[ 14] MSS size 8928 bytes (MTU 8968 bytes, unknown interface)
bwctl: stop_exec: 3460893484.061869



This test should be replicated for each beacon.  Note that if you use both the
"-s" and the "-c" flags you can test bidirectionally and will limit the number
of times and machines that need to be directly logged on to.  

If the test fails for some reason, BWCTL may not be configured properly.
Consult the BWCTL documentation for hints on how to correct the problems before
proceeding with these instructions.

OWAMP:
------

OWAMP should be installed, configured, and running on every machine that will
function as a "beacon", e.g. a location that will participate in latency
testing.  Installation and configuration of OWAMP is beyond the scope of these
instructions - please consult the appropriate documentation for the OWAMP tool
before proceeding.  To test OWAMP, log on to a beacon and run a test to all
other beacons.  E.g. try the following where in this example
"owamp.chic.net.internet2.edu" is a beacon we wish to test with:



[user@nms-rlat ~]$ owping owamp.chic.net.internet2.edu
Approximately 13.0 seconds until results available

--- owping statistics from [2001:468:6:12::17:98]:51077 to [owamp.chic.net.internet2.edu]:52854 ---
SID:	00170034ce490c540db1e9f2befc8232
first:	2009-09-02T15:23:01.343
last:	2009-09-02T15:23:10.672
100 sent, 0 lost (0.000%), 0 duplicates
one-way delay min/median/max = 13.4/13.5/13.4 ms, (err=0.0663 ms)
one-way jitter = 0 ms (P95-P50)
TTL not reported
no reordering

--- owping statistics from [owamp.chic.net.internet2.edu]:52855 to [2001:468:6:12::17:98]:53628 ---
SID:	00170098ce490c543d72abef1f4384bf
first:	2009-09-02T15:23:01.412
last:	2009-09-02T15:23:11.383
100 sent, 0 lost (0.000%), 0 duplicates
one-way delay min/median/max = 13.6/13.7/13.6 ms, (err=0.0663 ms)
one-way jitter = 0 ms (P95-P50)
TTL not reported
no reordering



If the test fails for some reason, OWAMP may not be configured properly.
Consult the OWAMP documentation for hints on how to correct the problems before
proceeding with these instructions.

powmaster:
----------

The "powmaster" script is designed to invoke the OWPING process in tests between
beacon hosts.  The design of the script allows the host that is running the
script to run tests between any pair of beacon hosts - even if the running host
is not a beacon itself.  

To test this script, first ensure that the etc/owmesh.conf is completely
configured (see the "Configuration" section or read the notes in
"etc/owmesh.conf").  After ensuring the configuration is proper, ensure that
OWAMP is working between all beacons (see above).  The best way to test this
script is to use the "-Z", "-d", and "-v" flags.  This will pipe a lot of
output directly to the screen which can then be scrutinized.  The following is
an example of starting the script in this manner:



[user@clean-centos4 ~]$ sudo /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powmaster.pl -c /opt/perfsonar_ps/perfsonarbuoy_ma/etc -dvZ
Found 1 powstream related TESTSPEC blocks at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powmaster.pl line 215.
Found 1 powstream related MEASUREMENTSET blocks at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powmaster.pl line 232.
Calling select with tmout=nil at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powmaster.pl line 1099.
Starting MeasurementSet=TEST-LAT4-STAR
Starting Test=CENTOS_32_4:192.168.69.174 ===> CENTOS_32_4:192.168.69.174
Executing: /usr/bin/powstream -e local5 -p -S 192.168.69.174 -i 0.1 -c 10800 -d TEST-LAT4-STAR/CENTOS_32_4/CENTOS_32_4 -N 600 -L 10.0 -b 0.0001 192.168.69.174 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powmaster.pl line 1191.
Starting Test=CENTOS_32_5:192.168.69.172 ===> CENTOS_32_4:192.168.69.174
Executing: /usr/bin/powstream -e local5 -p -S 192.168.69.174 -i 0.1 -c 10800 -d TEST-LAT4-STAR/CENTOS_32_4/CENTOS_32_5 -N 600 -L 10.0 -b 0.0001 192.168.69.172 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powmaster.pl line 1191.
Starting Test=CENTOS_64_5:192.168.69.141 ===> CENTOS_32_4:192.168.69.174
Executing: /usr/bin/powstream -e local5 -p -S 192.168.69.174 -i 0.1 -c 10800 -d TEST-LAT4-STAR/CENTOS_32_4/CENTOS_64_5 -N 600 -L 10.0 -b 0.0001 192.168.69.141 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powmaster.pl line 1191.
Starting Test=CENTOS_32_4:192.168.69.174 ===> CENTOS_32_5:192.168.69.172
Executing: /usr/bin/powstream -e local5 -p -S 192.168.69.174 -i 0.1 -c 10800 -t -d TEST-LAT4-STAR/CENTOS_32_5/CENTOS_32_4 -N 600 -L 10.0 -b 0.0001 192.168.69.172 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powmaster.pl line 1191.
Starting Test=CENTOS_32_4:192.168.69.174 ===> CENTOS_64_5:192.168.69.141
Executing: /usr/bin/powstream -e local5 -p -S 192.168.69.174 -i 0.1 -c 10800 -t -d TEST-LAT4-STAR/CENTOS_64_5/CENTOS_32_4 -N 600 -L 10.0 -b 0.0001 192.168.69.141 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powmaster.pl line 1191.



To verify that the script has started, visit the following directory on the same
filesystem/machine that is running the powmaster script:



[user@clean-centos4 owamp]$ cd /var/lib/perfsonar/perfsonarbuoy_ma/owamp/
[user@clean-centos4 owamp]$ find .
.
./TEST-LAT4-STAR
./TEST-LAT4-STAR/CENTOS_64_5
./TEST-LAT4-STAR/CENTOS_64_5/CENTOS_32_4
./TEST-LAT4-STAR/CENTOS_64_5/CENTOS_32_4/.powlock
./TEST-LAT4-STAR/CENTOS_32_5
./TEST-LAT4-STAR/CENTOS_32_5/CENTOS_32_4
./TEST-LAT4-STAR/CENTOS_32_5/CENTOS_32_4/.powlock
./TEST-LAT4-STAR/CENTOS_32_4
./TEST-LAT4-STAR/CENTOS_32_4/CENTOS_64_5
./TEST-LAT4-STAR/CENTOS_32_4/CENTOS_64_5/.powlock
./TEST-LAT4-STAR/CENTOS_32_4/CENTOS_32_5
./TEST-LAT4-STAR/CENTOS_32_4/CENTOS_32_5/.powlock
./TEST-LAT4-STAR/CENTOS_32_4/CENTOS_32_4
./TEST-LAT4-STAR/CENTOS_32_4/CENTOS_32_4/.powlock




Depending on the frequency of testing, results may take some time to accumulate.  
The results of testing will appear in this directories as text files that
contain owping data.  A simple "ctrl-c" will kill the powmaster process when you
have finished debugging.

bwmaster:
---------

The "bwmaster" script is designed to invoke the BWCTL process in tests between
beacon hosts.  The design of the script allows the host that is running the
script to run tests between any pair of beacon hosts - even if the running host
is not a beacon itself.  

To test this script, first ensure that the etc/owmesh.conf is completely
configured (see the "Configuration" section or read the notes in
"etc/owmesh.conf").  After ensuring the configuration is proper, ensure that
BWCTL is working between all beacons (see above).  The best way to test this
script is to use the "-Z", "-d", and "-v" flags.  This will pipe a lot of
output directly to the screen which can then be scrutinized.  The following is
an example of starting the script in this manner:



[user@clean-centos4 ~]$ sudo /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwmaster.pl -c /opt/perfsonar_ps/perfsonarbuoy_ma/etc -dvZ
Found 1 bwctl/iperf related TESTSPEC blocks at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwmaster.pl line 221.
Found 1 bwctl/iperf related MEASUREMENTSET blocks at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwmaster.pl line 238.
Redirected STDIN from pipe at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwmaster.pl line 1034.
Calling select with tmout=nil at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwmaster.pl line 1053.
Starting MeasurementSet=TEST-BWTCP4-STAR
Starting Test=CENTOS_32_5:[192.168.69.172]:4823 ===> CENTOS_32_4:[192.168.69.174]:4823
Executing: /usr/bin/bwctl -T iperf -e local5 -p -B 192.168.69.174 -rvv -R 25 -I 7200 -i 2 -W 4M -t 60 -d TEST-BWTCP4-STAR/CENTOS_32_4/CENTOS_32_5 -s [192.168.69.172]:4823 -c [192.168.69.174]:4823 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwmaster.pl line 1155.
Starting Test=CENTOS_64_5:[192.168.69.141]:4823 ===> CENTOS_32_4:[192.168.69.174]:4823
Executing: /usr/bin/bwctl -T iperf -e local5 -p -B 192.168.69.174 -rvv -R 25 -I 7200 -i 2 -W 4M -t 60 -d TEST-BWTCP4-STAR/CENTOS_32_4/CENTOS_64_5 -s [192.168.69.141]:4823 -c [192.168.69.174]:4823 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwmaster.pl line 1155.
Starting Test=CENTOS_32_4:[192.168.69.174]:4823 ===> CENTOS_32_5:[192.168.69.172]:4823
Executing: /usr/bin/bwctl -T iperf -e local5 -p -B 192.168.69.174 -rvv -R 25 -I 7200 -i 2 -W 4M -t 60 -d TEST-BWTCP4-STAR/CENTOS_32_5/CENTOS_32_4 -s [192.168.69.174]:4823 -c [192.168.69.172]:4823 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwmaster.pl line 1155.
Starting Test=CENTOS_32_4:[192.168.69.174]:4823 ===> CENTOS_64_5:[192.168.69.141]:4823
Executing: /usr/bin/bwctl -T iperf -e local5 -p -B 192.168.69.174 -rvv -R 25 -I 7200 -i 2 -W 4M -t 60 -d TEST-BWTCP4-STAR/CENTOS_64_5/CENTOS_32_4 -s [192.168.69.174]:4823 -c [192.168.69.141]:4823 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwmaster.pl line 1155.
Messages being sent to syslog(local5,err)
bwctl[5085]: FILE=bwctl.c, LINE=1826, 941 seconds until next testing period
Messages being sent to syslog(local5,err)
bwctl[5086]: FILE=bwctl.c, LINE=1826, 5757 seconds until next testing period
Messages being sent to syslog(local5,err)
bwctl[5087]: FILE=bwctl.c, LINE=1826, 5578 seconds until next testing period
Messages being sent to syslog(local5,err)
bwctl[5088]: FILE=bwctl.c, LINE=1826, 181 seconds until next testing period



To verify that the script has started, visit the following directory on the same
filesystem/machine that is running the bwmaster script:



[user@clean-centos4 bwctl]$ cd /var/lib/perfsonar/perfsonarbuoy_ma/bwctl
[user@clean-centos4 bwctl]$ find .
.
./TEST-BWTCP4-STAR
./TEST-BWTCP4-STAR/CENTOS_64_5
./TEST-BWTCP4-STAR/CENTOS_64_5/CENTOS_32_4
./TEST-BWTCP4-STAR/CENTOS_64_5/CENTOS_32_4/.bwctllock
./TEST-BWTCP4-STAR/CENTOS_32_5
./TEST-BWTCP4-STAR/CENTOS_32_5/CENTOS_32_4
./TEST-BWTCP4-STAR/CENTOS_32_5/CENTOS_32_4/.bwctllock
./TEST-BWTCP4-STAR/CENTOS_32_4
./TEST-BWTCP4-STAR/CENTOS_32_4/CENTOS_64_5
./TEST-BWTCP4-STAR/CENTOS_32_4/CENTOS_64_5/.bwctllock
./TEST-BWTCP4-STAR/CENTOS_32_4/CENTOS_32_5
./TEST-BWTCP4-STAR/CENTOS_32_4/CENTOS_32_5/.bwctllock



Depending on the frequency of testing, results may take some time to accumulate.  
The results of testing will appear in this directories as text files that
contain iperf data.  A simple "ctrl-c" will kill the bwmaster process when you
have finished debugging.

powcollector:
-------------

The "powcollector" script will gather the results of the periodic testing that
the "powmaster" script conducts between beacons.  Before starting to test this
script, log into your MySQL instance to be sure the proper database and tables
exist.  The following is a database that *has not* been configured properly:



[user@clean-centos4 ~]$ mysql -u root
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 2 to server version: 4.1.22

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> show databases;
+----------+
| Database |
+----------+
| mysql    |
| test     |
+----------+
2 rows in set (0.09 sec)



To configure the database, run the "owdb.pl" script (described in
"Database Preparation").  The output of script should be similar to this:



[user@clean-centos4 ~]$ sudo /opt/perfsonar_ps/perfsonarbuoy_ma/bin/owdb.pl -c /opt/perfsonar_ps/perfsonarbuoy_ma/etc -i root
Enter root password: 
creating new database owamp
Creating user account perfsonar
Granting user perfsonar@localhost access to owamp
Creating user account readonly
Granting user readonly@localhost read-only access to owamp
Granting user readonly@'%' read-only access to owamp
Initializing DBI:mysql:owamp:localhost



After running the script, check mysql again to be sure the proper database and
tables are present:



mysql> show databases;
+----------+
| Database |
+----------+
| mysql    |
| owamp    |
| test     |
+----------+
3 rows in set (0.00 sec)

mysql> use owamp;
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Database changed
mysql> show tables;
+-----------------+
| Tables_in_owamp |
+-----------------+
| DATES           |
+-----------------+
1 row in set (0.00 sec)



To test the collector, first ensure that the etc/owmesh.conf is completely
configured (see the "Configuration" section or read the notes in
"etc/owmesh.conf").  After ensuring the configuration is proper, ensure that
OWPING is working between all beacons (see above).  Finally, since the collector
relies on having data to collect, the "powmaster" should be configured and
running (preferably data will be available in the collection directories - see
above).  The best way to test this script is to use the "-Z", "-d", and "-v"
flags.  This will pipe a lot of output directly to the screen which can then be
scrutinized. The following is an example of starting the script in this manner:



[user@clean-centos4 ~]$ sudo /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powcollector.pl -c /opt/perfsonar_ps/perfsonarbuoy_ma/etc -dvZ
ADD_SESSION: Adding 14864445878670581018 to 127.0.0.1_TEST-LAT4-STAR_CENTOS_32_4_CENTOS_32_5
ADD_SESSION: 127.0.0.1_TEST-LAT4-STAR_CENTOS_32_4_CENTOS_32_5: inserted 14864445878670581018 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powcollector.pl line 1165.
Date already initialized at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powcollector.pl line 682.
ADD_SESSION: Adding 14864445878501054749 to 127.0.0.1_TEST-LAT4-STAR_CENTOS_32_4_CENTOS_32_4
ADD_SESSION: 127.0.0.1_TEST-LAT4-STAR_CENTOS_32_4_CENTOS_32_4: inserted 14864445878501054749 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/powcollector.pl line 1165.



Checking back on the database, we can see that tables are being created:



mysql> show tables;
+-------------------+
| Tables_in_owamp   |
+-------------------+
| 20090902_DATA     |
| 20090902_DELAY    |
| 20090902_NODES    |
| 20090902_TESTSPEC |
| 20090902_TTL      |
| DATES             |
+-------------------+
6 rows in set (1.04 sec)



Performing select statements on tables will reveal the results of the
powcollector script:



mysql> select * from 20090902_NODES;
+------------+-------------+-------------------+----------------+----------------+------------+------------+
| node_id    | node_name   | longname          | host           | addr           | first      | last       |
+------------+-------------+-------------------+----------------+----------------+------------+------------+
| 1969976625 | CENTOS_32_4 | CentOS 4 (32 Bit) | clean-centos4  | 192.168.69.174 | 1251909701 | 1251909765 |
| 2080376972 | CENTOS_32_5 | CentOS 5 (32 Bit) | clean-centos5  | 192.168.69.172 | 1251909701 | 1251909764 |
| 2227929248 | CENTOS_64_5 | CentOS 5 (64 Bit) | 192.168.69.141 | 192.168.69.141 | 1251909702 | 1251909765 |
+------------+-------------+-------------------+----------------+----------------+------------+------------+
3 rows in set (0.00 sec)



A simple "ctrl-c" will kill the powcollector process when you have finished
debugging.

bwcollector:
------------

The "bwcollector" script will gather the results of the periodic testing that
the "bwmaster" script conducts between beacons.  Before starting to test this
script, log into your MySQL instance to be sure the proper database and tables
exist.  The following is a database that *has not* been configured properly:



[user@clean-centos4 ~]$ mysql -u root
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 2 to server version: 4.1.22

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> show databases;
+----------+
| Database |
+----------+
| mysql    |
| test     |
+----------+
2 rows in set (0.09 sec)



To configure the database, run the "bwdb.pl" script (described in
"Database Preparation").  The output of script should be similar to this:



[user@clean-centos4 ~]$ sudo /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwdb.pl -c /opt/perfsonar_ps/perfsonarbuoy_ma/etc -i root
Enter root password: 
creating new database bwctl
Creating user account perfsonar
Granting user perfsonar@localhost access to bwctl
Creating user account readonly
Granting user readonly@localhost read-only access to bwctl
Granting user readonly@'%' read-only access to bwctl
Initializing DBI:mysql:bwctl:localhost




After running the script, check mysql again to be sure the proper database and
tables are present:



mysql> show databases;
+----------+
| Database |
+----------+
| bwctl    |
| mysql    |
| test     |
+----------+
3 rows in set (0.00 sec)

mysql> use bwctl;
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Database changed
mysql> show tables;
+-----------------+
| Tables_in_bwctl |
+-----------------+
| DATES           |
+-----------------+
1 row in set (0.00 sec)




To test the collector, first ensure that the etc/owmesh.conf is completely
configured (see the "Configuration" section or read the notes in
"etc/owmesh.conf").  After ensuring the configuration is proper, ensure that
BWCTL is working between all beacons (see above).  Finally, since the collector
relies on having data to collect - the "bwmaster" should be configured and
running (preferably data will be available in the collection directories - see
above).  The best way to test this script is to use the "-Z", "-d", and "-v"
flags.  This will pipe a lot of output directly to the screen which can then be
scrutinized. The following is an example of starting the script in this manner:



[user@clean-centos4 bwctl]$ sudo /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl -c /opt/perfsonar_ps/perfsonarbuoy_ma/etc -dvZ
req{RECVNODE} = CENTOS_32_4 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{TIMESTAMP} = 14864456162250060081 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{BWTCP} = 1 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{BWWINDOWSIZE} = 4M at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{SENDADDR} = 192.168.69.172:4823 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{RECVADDR} = 192.168.69.174:4823 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{FILESIZE} = 1101 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{MEASUREMENTSET} = TEST-BWTCP4-STAR at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{TOOL} = bwctl/iperf at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{SECRETNAME} = 16Jul2009 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{SENDLONGNAME} = CentOS 5 (32 Bit) at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{SENDNODE} = CENTOS_32_5 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{OP} = TXFR at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{DESCRIPTION} = Star Testing - 2 Hour TCP Throughput (iperf) at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{RECVLONGNAME} = CentOS 4 (32 Bit) at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{FILEMD5} = fa48f265f6fca028e9933ac415928cf4 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{ADDRTYPE} = BW4 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{BWTESTDURATION} = 10 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
ADD_SESSION: Adding 14864456162250060081 to TEST-BWTCP4-STAR_CENTOS_32_4_CENTOS_32_5
ADD_SESSION: TEST-BWTCP4-STAR_CENTOS_32_4_CENTOS_32_5: inserted /var/lib/perfsonar/perfsonarbuoy_ma/bwctl/upload/ZVSFPTRDaE at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 983, <SESS> line 22.
req{RECVNODE} = CENTOS_64_5 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{TIMESTAMP} = 14864456229400867121 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{BWTCP} = 1 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{BWWINDOWSIZE} = 4M at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{SENDADDR} = 192.168.69.174:4823 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{RECVADDR} = 192.168.69.141:4823 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{FILESIZE} = 1010 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{MEASUREMENTSET} = TEST-BWTCP4-STAR at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{TOOL} = bwctl/iperf at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{SECRETNAME} = 16Jul2009 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{SENDLONGNAME} = CentOS 4 (32 Bit) at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{SENDNODE} = CENTOS_32_4 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{OP} = TXFR at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{DESCRIPTION} = Star Testing - 2 Hour TCP Throughput (iperf) at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{RECVLONGNAME} = CentOS 5 (64 Bit) at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{FILEMD5} = 10b33d7145472b745b4fb424daeaa177 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{ADDRTYPE} = BW4 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
req{BWTESTDURATION} = 10 at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 484.
ADD_SESSION: Adding 14864456229400867121 to TEST-BWTCP4-STAR_CENTOS_64_5_CENTOS_32_4
ADD_SESSION: TEST-BWTCP4-STAR_CENTOS_64_5_CENTOS_32_4: inserted /var/lib/perfsonar/perfsonarbuoy_ma/bwctl/upload/yDuzvSuAqP at /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwcollector.pl line 983, <SESS> line 20.




Checking back on the database, we can see that tables are being created:



mysql> show tables;
+-----------------+
| Tables_in_bwctl |
+-----------------+
| 200909_DATA     |
| 200909_NODES    |
| 200909_TESTSPEC |
| DATES           |
+-----------------+
4 rows in set (0.00 sec)



Performing select statements on tables will reveal the results of the
powcollector script:



mysql> select * from 200909_NODES;
+------------+-------------+-------------------+----------------+------------+------------+
| node_id    | node_name   | longname          | addr           | first      | last       |
+------------+-------------+-------------------+----------------+------------+------------+
| 2058961398 | CENTOS_32_4 | CentOS 4 (32 Bit) | 192.168.69.174 | 1251912095 | 1251912111 |
| 1654532545 | CENTOS_32_5 | CentOS 5 (32 Bit) | 192.168.69.172 | 1251912095 | 1251912095 |
| 3506274557 | CENTOS_64_5 | CentOS 5 (64 Bit) | 192.168.69.141 | 1251912111 | 1251912111 |
+------------+-------------+-------------------+----------------+------------+------------+
3 rows in set (0.00 sec)



A simple "ctrl-c" will kill the bwcollector process when you have finished
debugging.





perfSONAR-BUOY Web Service:
---------------------------

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:8085/perfSONAR_PS/services/pSB etc/requests/EchoRequest.xml

This will test the basic functionality 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 this 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) 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

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

Mon May 17 11:01:46 EDT 2010
