perfsonar development work

Author: zurawski
Date: 2006-08-08 12:29:17 -0400 (Tue, 08 Aug 2006)
New Revision: 1522

Modified:
   branches/release/perfsonar/releng/perfSONAR-1.0/Readme.txt
Log:
Updated Readme to address bug #52 and comments from perfsonar-users 
list.

-jason



Modified: branches/release/perfsonar/releng/perfSONAR-1.0/Readme.txt
===================================================================
--- branches/release/perfsonar/releng/perfSONAR-1.0/Readme.txt  2006-08-08 
16:06:59 UTC (rev 1521)
+++ branches/release/perfsonar/releng/perfSONAR-1.0/Readme.txt  2006-08-08 
16:29:17 UTC (rev 1522)
@@ -1,16 +1,29 @@
 ------------------------------------------------------------
-                    perfSONAR v1.0 README
+                    perfSONAR v1.1 README
 ------------------------------------------------------------
 
 1) Pre-installation tasks
   a) Introduction
   b) Java
+    i)  Installation
+    ii) Configuration    
   c) Tomcat
+    i)  Installation
+    ii) Configuration  
   d) Axis
+    i)  Installation
+    ii) Configuration  
   e) eXist
+    i)  Installation
+    ii) Configuration 
+      A)  eXist GUI Configuration
+      B)  eXist non-GUI Configuration
   f) RRDTool
+    i)  Installation
+    ii) Configuration 
 2) Installation Notes
 3) Use
+    i)  Testing
 4) Problems
 
 ------------------------------------------------------------
@@ -20,21 +33,29 @@
 a) Introduction
 ------------------------------------------------------------
        These instructions assume the target operating syst-
-       em to be of the unix family (specifically linux).
+       em to be of the unix family (specifically linux). C-
+       ontributers have reported that perfSONAR will work
+       under all major flavors of linux (REL, Fedora, Debi-
+       an, Unbuntu, Gentoo, Suse, Mandrivia) as well as Fr-
+       eeBSD and MacOS X.
 
 b) Java
 ------------------------------------------------------------
        This version of perfSONAR is java based, as such a 
-       working version of java (JRE or JDK) is required. W-
-       e are using Java version 5, which can be downloaded 
-       from this location:
+       working version of java (JDK preferred, JRE accepta-
+       ble) is required. We are using Java version 5, whic-
+       h can be downloaded from this location:
        
        http://java.sun.com/j2se/1.5.0/download.jsp
        
        Any minor version of Java 5 will do, and the user m-
-       ay install the JRE or JDK, but is also free to inst-
-       all EE or NetBeans if so inclined.  
+       ay install the JDK or JRE, but is also free to inst-
+       all the EE or NetBeans editions if so inclined.
        
+       
+i) Installation
+------------------------------------------------------------
+
        To install via the binary (replace X and Y with ver-
        sion numbers).  It helps to be root or use sudo as 
        you install:
@@ -62,23 +83,25 @@
        he basic issue is that 'pack' files are not expanded
        to their jar equivalent. To solve this problem, try 
        writing a script like this (be sure to set executab-
-       le permissions):
+       le permissions and making sure to replace X and Y w-
+       ith your versions):
        
        
        #!/bin/sh
        for i in `find /usr/java | grep ^.*\.pack$`
        do
                j=`echo $i | sed -e 's/\.pack/\.jar/'`
-               unpack200 $i $j
-       done
-       
-       
-       This should convert the pack files to jar files.  
-       
+               /usr/java/jdk1.5.X_Y/bin/unpack200 $i $j
+       done    
+
+
+ii) Configuration
+------------------------------------------------------------
+               
        After setting up java, it is necessary to adjust so-
        me of your system paths.  This can be done in 
        /etc/profile or ~/.bashrc  be sure to logout/login 
-       or source the files after editing:
+       or 'source' the files after editing:
        
 export JAVA_HOME=/usr/java/jdk1.5.X_Y
 export PATH=$JAVA_HOME/bin:$PATH
@@ -88,6 +111,11 @@
                
 export CLASSPATH=.:$CLASSPATH:/usr/java/jdk1.5.X_Y/lib
 
+       Another common error invloves using terminal sessio-
+       ns on a computer that has had environmental variabl-
+       es changed.  Be sure to 'source' all terminal sessi-
+       ons after making these changes.
+       
 
 c) Tomcat
 ------------------------------------------------------------
@@ -95,15 +123,27 @@
        downloaded from this location:
        
        http://www.apache.org/dist/tomcat/tomcat-5/v5.0.28/
-       bin/jakarta-tomcat-5.0.28.tar.gz
+bin/jakarta-tomcat-5.0.28.tar.gz
 
+       If your system uses a package manager (apt, yum, et-
+       c.) it may be possible to install the necessary pac-
+       kages via a binary method instead of from source.  
+       The version that your package manager suggests could
+       of course differ from what we present here, and may 
+       place components in different locations; be aware t-
+       hat the instructions we present here are tailored to
+       installation using the above resource.
+
+i) Installation
+------------------------------------------------------------
+
        Installation is straight forward:
        
                tar -zxf jakarta-tomcat-5.0.28.tar.gz
                mv jakarta-tomcat-5.0.28 /usr/local
                
        It is helpful to install symbolic links (to shorten
-       relative path names).  To do so:
+       relative path names), this step is optional:
                
                cd /usr/local
                ln -s jakarta-tomcat-5.0.28 tomcat-5.0.28
@@ -140,19 +180,23 @@
                        or
                chmod +x /etc/init.d/tomcat
 
+
+ii) Configuration
+------------------------------------------------------------
+
        If this service is to be visible on the outside, en-
        sure that your firewall allows traffic to reach port
        8080 (or whatever other port that tomcat may decide 
-       to run on.
+       to run on.              
        
        To test tomcat, start the program and visit:
        
-       http://HOSTNAME:8080
+       http://$HOSTNAME:8080
        
        You should see a tomcat start page.  If you see not-
        hing, or get an error be sure your port and firewall
        settings are correct, as well as your relative Java
-       paths.
+       paths (for the environmental variables).
        
 d) Axis
 ------------------------------------------------------------
@@ -160,20 +204,42 @@
        le Object Access Protocol") and can be downloaded f-
        rom this location:
 
-       http://www.apache.org/dist/ws/axis/1_2_1/
-       axis-bin-1_2_1.tar.gz
+       http://archive.apache.org/dist/ws/axis/1_2_1/
+axis-bin-1_2_1.tar.gz
 
        It is recommended that the 'binary' installation (n-
        ote the 'bin' in the filename) be installed; the us-
        er is free to install from source if desired.
 
+       If your system uses a package manager (apt, yum, et-
+       c.) it may be possible to install the necessary pac-
+       kages via a binary method instead of from source.  
+       The version that your package manager suggests could
+       of course differ from what we present here, and may 
+       place components in different locations; be aware t-
+       hat the instructions we present here are tailored to
+       installation using the above resource.
+
+       Together with tomcat, axis is able to provide a sim-
+       ple network communication system that allows perfSO-
+       NAR services the ability to be contacted from the o-
+       utside, without having to worry about the details t-
+       hat are involved with communication protocols.  A p-
+       erfSONAR service is only concerned about the request
+       messages it receives and does not really need to kn-
+       ow the details of SOAP and HTTP.
+
+
+i) Installation
+------------------------------------------------------------
+
        Installation is straight forward:
 
                tar -zxf axis-bin-1_2_1.tar.gz
                mv axis-1_2_1 /usr/local/axis-1_2_1
 
        It is helpful to install symbolic links (to shorten
-       relative path names).  To do so:
+       relative path names), this step is optional:
 
                cd /usr/local
                ln -s axis-1_2_1 axis-1.2.1
@@ -186,12 +252,25 @@
                ln -s ../../axis/webapps/axis axis
        
        The user is also free to physical move, or hardlink
-       the directory to the appropriate location.
+       the directory to the appropriate location as well.
        
        If you are currently running tomcat, you must of co-
        urse stop it, and re-start it to ensure axis is rec-
        ognized.
        
+       Restarting tomcat does not uninstall or harm any of
+       the services that have been installed (or deployed).
+       By restarting the tomcat server, any newly deployed 
+       libraries or services will be recognized and loaded
+       into main memory so they may be used.  It is of note
+       to remark that any configuration change (to perfSON-
+       AR specific files or to the tomcat/axis configurati-
+       on) will require a tomcat restart.
+
+
+ii) Configuration
+------------------------------------------------------------
+       
        To test axis, start the program and visit:
        
                http://HOSTNAME:8080/axis
@@ -205,18 +284,18 @@
                http://HOSTNAME:8080/axis/happyaxis.jsp
 
        Unfortunately, at this stage in the installation, t-
-       his will fail.  Why does this fail?  There is a key
-       library (activation.jar) and two optional libraries
-       (xmlsec.jar and mail.jar) that are not included by
-       default in the axis package.  perfSONAR DOES include
-       these libraries, and will install them as a part of
-       deployment.  For now, just be sure that you can acc-
-       ess axis, despite it not being 'happy'.
+       his will 'fail'.  Why does this fail?  There is a k-
+       ey library (activation.jar) and two optional librar-
+       ies (xmlsec.jar and mail.jar) that are not included 
+       by default in the axis package.  perfSONAR DOES inc-
+       lude these libraries, and will install them as a pa-
+       rt of deployment.  For now, just be sure that you c-
+       an see the axis page, despite it not being 'happy'.
        
        After setting up axis, it is necessary to adjust so-
        me of your system paths.  This can be done in 
        /etc/profile or ~/.bashrc  be sure to logout/login 
-       or source the files after editing:
+       or 'source' the files after editing:
        
 export AXIS_LIB=/usr/local/tomcat/webapps/axis/WEB-INF/lib
 export AXISCLASSPATH=$AXIS_LIB/ALL_JARS_IN_DIRECTORY
@@ -234,14 +313,22 @@
        be found:
        
        http://superb-east.dl.sourceforge.net/sourceforge/
-       exist/eXist-snapshot-20060316.jar
+exist/eXist-snapshot-20060316.jar
        
-       We do recommend this particular snapshot as it has 
+       We do recommend this particular snapshot as it has
        passed many of our internal tests.
+
+       eXist is required for the installation of the Lookup
+       Service (LS), but is an optional component of the R-
+       RD Measurement Archive (RRDMA).
        
+       
+i) Installation
+------------------------------------------------------------
+       
        To install the database you have two options:
        
-       Headless (no GUI):
+       Headless (no GUI access):
                java -jar eXist-snapshot-20060316.jar \
 -p /usr/local/eXist-20060316
        
@@ -258,6 +345,10 @@
                ln -s eXist-20060316 eXist
                        or
                ln -s eXist-20060316 exist
+
+
+ii) Configuration
+------------------------------------------------------------
                
        Internally, eXist uses jetty as its servlet engine, 
        and also attempts to use port 8080.  There is an ea-
@@ -284,7 +375,7 @@
        After setting up eXist, it is necessary to adjust s-
        ome of your system paths.  This can be done in 
        /etc/profile or ~/.bashrc  be sure to logout/login 
-       or source the files after editing:      
+       or 'source' the files after editing:    
 
 export EXIST_HOME=/usr/local/eXist
 export PATH=$EXIST_HOME/bin:$PATH
@@ -302,8 +393,15 @@
        at occur on the server side):
        
                /usr/local/eXist/bin/./startup.sh
-               
 
+
+A) eXist GUI Configuration
+------------------------------------------------------------
+
+       The following instructions assume GUI access, please
+       skip this section if you intend to configure via wi-
+       thout the help of the GUI:
+                               
        2) Start a client to set up db (will need a GUI for 
        this, ssh -X works well):
        
@@ -359,13 +457,152 @@
                owner: 'rrdmaservice'    
                group: 'guest'  
                
-       9) Exit the client
+       9) Double click on 'ls' or type 'cd ls' to enter the
+          directory.
+          
+       10)Click the 'store file' button (a document with a 
+          + symbol) to store a new document.
+       
+          Navigate to the $PERFSONAR/conf directory and 
+          store:
+          
+          - LSStore.xml
+          - LSStore-control.xml
+          
+       11)Adjust the permissions as in step 8.
 
+       12)Because the rrd config file is generated as a pa-
+          rt of the installation process, it cannot be ins-
+          talled until the installer has run (the installer
+          can of course install the file automatically). T-
+          he following steps (if followed) should be done 
+          AFTER installing the RRDMA:
+
+       13)Click the parent directory button ('^') or type 
+          cd ..
+
+       14)Double click on 'rrdmaconfig' or type
+          'cd rrdmaconfig' to enter the directory.
+
+       15)Click the 'store file' button (a document with a 
+          + symbol) to store a new document.
+       
+          Navigate to the $PERFSONAR/conf directory and 
+          store:
+          
+          - rrd-database_TEST.xml
+          
+       16)Adjust the permissions as in step 8.         
+               
+       17)Exit the client
+
+
+B) eXist non-GUI Configuration
+------------------------------------------------------------
+
+       The following instructions are for a non-GUI config-
+       uration, ignore these if you have successfully comp-
+       leted the above section:
+
+       2) Start a client to set up db:
+       
+               /usr/local/eXist/bin/./client.sh -s 
+-ouri=xmldb:exist://localhost:8680/exist/xmlrpc
+
+          You will see the database prompt:
+          
+          exist:/db>
+                               
+       3a) Set up users (both users are outlined here) 
+               
+       3b) Type:
+               
+               3b-a) adduser lookupservice
+       
+               3b-b) Password = 'sonar'
+
+               3b-c) Re-enter Password = 'sonar'
+
+               3b-d) Home collection = 'none' (just press 
+                     enter)
+               
+               3b-e) Enter groups = 'guest'
+               
+               3b-f) The user should be created, and a mes-
+                     sage:
+
+                      'user <...> created'             
+               
+                     will be displayed.                
+               
+       3b) Type:
+               
+               3b-a) adduser rrdmaservice
+       
+               3b-b) Password = 'rrdmaservice'
+
+               3b-c) Re-enter Password = 'rrdmaservice'
+
+               3b-d) Home collection = 'none' (just press 
+                     enter)
+               
+               3b-e) Enter groups = 'guest'
+               
+               3b-f) The user should be created, and a mes-
+                     sage:
+
+                      'user <...> created'             
+               
+                     will be displayed.                
+                       
+       
+* THE NEXT STEPS CAN BE INSTANTIATED BY THE INSTALLER *        
+
+               
+       5) Type 'mkcol ls'
+                       
+       6) Type 'cd ls' to enter the directory
+       
+       7) Type:
+       
+               7a) put $PERFSONAR/conf/LSStore.xml
+
+               7b) put $PERFSONAR/conf/LSStore-control.xml
+
+       8) Type:
+       
+               8a) chown lookupservice guest LSStore.xml
+       
+               8b) chown lookupservice guest 
+LSStore-control.xml
+
+       9) Type 'mkcol rrdmaconfig'
+       
+       10)Because the rrd config file is generated as a pa-
+          rt of the installation process, it cannot be ins-
+          talled until the installer has run (the installer
+          can of course install the file automatically). T-
+          he following steps (if followed) should be done 
+          AFTER installing the RRDMA:
+       
+       11)Type 'cd rrdmaconfig' to enter the directory
+       
+       12)Type:
+       
+               11a) put $PERFSONAR/conf/
+rrd-database_TEST.xml
+               
+       13)Type:
+       
+               12a) chown rrdmaservice guest 
+rrd-database_TEST.xml
+
+
        At this point eXist is ready to have an XML collect-
        ion imported, this will be done as a part of the in-
        stallation.
+       
 
-
 f) RRDTool
 ------------------------------------------------------------
 
@@ -386,6 +623,10 @@
        http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/
        pub/libs/zlib-1.2.3.tar.gz
        
+       
+i) Installation
+------------------------------------------------------------
+       
        If your system uses a package manager (apt, yum, et-
        c.) it may be possible to install the necessary pac-
        kages via a binary method instead of from source.
@@ -397,7 +638,7 @@
                ./configure --prefix=/usr/local/rrdtool
                
        The configure may fail if your system is missing so-
-       me of the supporting libraries.  If so read the log 
+       me of the supporting libraries.  If so, read the log
        messages carefully, download the proper library from
        above and try again (or attempt to use a package ma-
        nagement system such as yum or apt to aide your pro-
@@ -407,6 +648,10 @@
                make
                sudo make install
 
+
+ii) Configuration
+------------------------------------------------------------
+
        After setting up rrdtool, it is necessary to adjust 
        some of your system paths.  This can be done in 
        /etc/profile or ~/.bashrc  be sure to logout/login 
@@ -440,6 +685,10 @@
        If you get a blank, something is wrong.  If you see
        values, make sure they are the 'correct' values.
        
+       Also be sure that all open sessions (i.e. terminal 
+       windows) have been 'sourced' to the newest environ-
+       mental settings.
+       
        Common issues that will cause the installation to
        fail include:
        
@@ -471,6 +720,14 @@
                        sole or by ssh -X).
 
                        run 'java -jar perfSONAR-1.0.jar'
+
+                       To date the most common errors with 
+                       the GUI based installer are related 
+                       to permissions as well as improper  
+                       entry of configuration settings.    
+                       Please read each field as you are e-
+                       ntering the data carefully before f-
+                       inalizing the information.
                
                Textual (perl script):
                        X access is NOT needed
@@ -484,8 +741,13 @@
                                ./install.pl 
                                        or 
                                perl install.pl 
+                               
+                       To date the most common errors with 
+                       the text based installer are related
+                       to permissions and different versio-
+                       ns of shell and perl interpreters.
+                       
                
-               
 ------------------------------------------------------------
 3) Use
 ------------------------------------------------------------
@@ -494,10 +756,15 @@
        followed.  The application will not work correctly 
        until this is corrected.
 
+
+i) Testing
+------------------------------------------------------------
+
        Once installed, the services may be tested via the
-       client test scripts found in the clients/ directory 
+       client test scripts found in the scripts/ directory 
        of the installation.  These tests will verify the s-
-       ervices work.  
+       ervices work using request messages found in the 
+       client/ directory.
 
        The client is located in the package:
        
@@ -514,9 +781,9 @@
        Errors indicating the class file cannot be found are
        more than likely related to the CLASSPATH.
        
-       The test scripts we install will include a fabricat-
-       ed CLASSPATH, don't let this stop you from changing
-       the CLASSPATH on your own.
+       The test scripts we install include a fabricated 
+       CLASSPATH to ensure the tests work; don't let this 
+       stop you from changing the CLASSPATH on your own.
        
 ------------------------------------------------------------
 4) Problems